lib/neo4j/neo4j.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Neo4j connector through its JSON REST API using curl.
  16 #
  17 # For ease of use and testing this module provide a wrapper to the `neo4j` command:
  18 #
  19 #     # Start the Neo4j server
  20 #     var srv = new Neo4jServer
  21 #     assert srv.start_quiet
  22 #
  23 # In order to connect to Neo4j you need a connector:
  24 #
  25 #     # Create new Neo4j client
  26 #     var client = new Neo4jClient("http://localhost:7474")
  27 #     assert client.is_ok
  28 #
  29 # The fundamental units that form a graph are nodes and relationships.
  30 #
  31 # Nodes are used to represent entities stored in base:
  32 #
  33 #     # Create a disconnected node
  34 #     var andres = new NeoNode
  35 #     andres["name"] = "Andres"
  36 #     # Connect the node to Neo4j
  37 #     client.save_node(andres)
  38 #     assert andres.is_linked
  39 #
  40 #     # Create a second node
  41 #     var kate = new NeoNode
  42 #     kate["name"] = "Kate"
  43 #     client.save_node(kate)
  44 #     assert kate.is_linked
  45 #
  46 # Relationships between nodes are a key part of a graph database.
  47 # They allow for finding related data. Just like nodes, relationships can have properties.
  48 #
  49 #     # Create a relationship
  50 #     var loves = new NeoEdge(andres, "LOVES", kate)
  51 #     client.save_edge(loves)
  52 #     assert loves.is_linked
  53 #
  54 # Nodes can also be loaded fron Neo4j:
  55 #
  56 #     # Get a node from DB and explore edges
  57 #     var url = andres.url.to_s
  58 #     var from = client.load_node(url)
  59 #     assert from["name"].to_s == "Andres"
  60 #     var to = from.out_nodes("LOVES").first            # follow the first LOVES relationship
  61 #     assert to["name"].to_s == "Kate"
  62 #
  63 # For more details, see http://docs.neo4j.org/chunked/milestone/rest-api.html
  64 module neo4j
  65
  66 import curl_json
  67 import error
  68
  69 # Handles Neo4j server start and stop command
  70 #
  71 # `neo4j` binary must be in `PATH` in order to work
  72 class Neo4jServer
  73
  74         # Start the local Neo4j server instance
  75         fun start: Bool do
  76                 sys.system("neo4j start console")
  77                 return true
  78         end
  79
  80         # Like `start` but redirect the console output to `/dev/null`
  81         fun start_quiet: Bool do
  82                 sys.system("neo4j start console > /dev/null")
  83                 return true
  84         end
  85
  86         # Stop the local Neo4j server instance
  87         fun stop: Bool do
  88                 sys.system("neo4j stop")
  89                 return true
  90         end
  91
  92         # Like `stop` but redirect the console output to `/dev/null`
  93         fun stop_quiet: Bool do
  94                 sys.system("neo4j stop > /dev/null")
  95                 return true
  96         end
  97 end
  98
  99 # `Neo4jClient` is needed to communicate through the REST API
 100 #
 101 #     var client = new Neo4jClient("http://localhost:7474")
 102 #     assert client.is_ok
 103 class Neo4jClient
 104
 105         # Neo4j REST services baseurl
 106         var base_url: String
 107         # REST service to get node data
 108         private var node_url: String
 109         # REST service to batch
 110         private var batch_url: String
 111         # REST service to send cypher requests
 112         private var cypher_url: String
 113
 114         private var curl = new Curl
 115
 116         init(base_url: String) do
 117                 self.base_url = base_url
 118                 var root = service_root
 119                 assert root isa JsonObject else
 120                         sys.stderr.write "Neo4jClientError: cannot connect to server at <{base_url}>.\n"
 121                 end
 122                 self.node_url = root["node"].to_s
 123                 self.batch_url = root["batch"].to_s
 124                 self.cypher_url = root["cypher"].to_s
 125         end
 126
 127         fun service_root: Serializable do return get(base_url / "db/data")
 128
 129         # Is the connection with the Neo4j server ok?
 130         fun is_ok: Bool do return service_root isa JsonObject
 131
 132         # Empty the graph
 133         fun clear_graph do
 134                 cypher(new CypherQuery.from_string("MATCH (n) OPTIONAL MATCH n-[r]-() DELETE r, n"))
 135         end
 136
 137         # Last errors
 138         var errors = new Array[String]
 139
 140         # Nodes view stored locally
 141         private var local_nodes = new HashMap[String, nullable NeoNode]
 142
 143         # Save the node in base
 144         #
 145         #     var client = new Neo4jClient("http://localhost:7474")
 146         #
 147         #     # Create a node
 148         #     var andres = new NeoNode
 149         #     andres["name"] = "Andres"
 150         #     client.save_node(andres)
 151         #     assert andres.is_linked
 152         #
 153         # Once linked, nodes cannot be created twice:
 154         #
 155         #     var oldurl = andres.url
 156         #     client.save_node(andres) # do nothing
 157         #     assert andres.url == oldurl
 158         fun save_node(node: NeoNode): Bool do
 159                 if node.is_linked then return true
 160                 node.neo = self
 161                 var batch = new NeoBatch(self)
 162                 batch.save_node(node)
 163                 # batch.create_edges(node.out_edges)
 164                 var errors = batch.execute
 165                 if not errors.is_empty then
 166                         errors.add_all errors
 167                         return false
 168                 end
 169                 local_nodes[node.url.to_s] = node
 170                 return true
 171         end
 172
 173         # Load a node from base
 174         # Data, labels and edges will be loaded lazily.
 175         fun load_node(url: String): NeoNode do
 176                 if local_nodes.has_key(url) then
 177                         var node = local_nodes[url]
 178                         if node != null then return node
 179                 end
 180                 var node = new NeoNode.from_neo(self, url)
 181                 local_nodes[url] = node
 182                 return node
 183         end
 184
 185         # Remove the entity from base
 186         fun delete_node(node: NeoNode): Bool do
 187                 if not node.is_linked then return false
 188                 var url = node.url.to_s
 189                 delete(url)
 190                 local_nodes[url] = null
 191                 node.url = null
 192                 return true
 193         end
 194
 195         # Edges view stored locally
 196         private var local_edges = new HashMap[String, nullable NeoEdge]
 197
 198         # Save the edge in base
 199         # From and to nodes will be created.
 200         #
 201         #     var client = new Neo4jClient("http://localhost:7474")
 202         #
 203         #     var andres = new NeoNode
 204         #     var kate = new NeoNode
 205         #     var edge = new NeoEdge(andres, "LOVES", kate)
 206         #     client.save_edge(edge)
 207         #     assert andres.is_linked
 208         #     assert kate.is_linked
 209         #     assert edge.is_linked
 210         fun save_edge(edge: NeoEdge): Bool do
 211                 if edge.is_linked then return true
 212                 edge.neo = self
 213                 edge.from.out_edges.add edge
 214                 edge.to.in_edges.add edge
 215                 var batch = new NeoBatch(self)
 216                 batch.save_edge(edge)
 217                 var errors = batch.execute
 218                 if not errors.is_empty then
 219                         errors.add_all errors
 220                         return false
 221                 end
 222                 local_edges[edge.url.to_s] = edge
 223                 return true
 224         end
 225
 226         # Load a edge from base
 227         # Data will be loaded lazily.
 228         fun load_edge(url: String): NeoEdge do
 229                 if local_edges.has_key(url) then
 230                         var node = local_edges[url]
 231                         if node != null then return node
 232                 end
 233                 var edge = new NeoEdge.from_neo(self, url)
 234                 local_edges[url] = edge
 235                 return edge
 236         end
 237
 238         # Remove the edge from base
 239         fun delete_edge(edge: NeoEdge): Bool do
 240                 if not edge.is_linked then return false
 241                 var url = edge.url.to_s
 242                 delete(url)
 243                 local_edges[url] = null
 244                 edge.url = null
 245                 return true
 246         end
 247
 248         # Retrieve all nodes with specified `lbl`
 249         #
 250         #     var client = new Neo4jClient("http://localhost:7474")
 251         #
 252         #     var andres = new NeoNode
 253         #     andres.labels.add_all(["Human", "Male"])
 254         #     client.save_node(andres)
 255         #     var kate = new NeoNode
 256         #     kate.labels.add_all(["Human", "Female"])
 257         #     client.save_node(kate)
 258         #
 259         #     var nodes = client.nodes_with_label("Human")
 260         #     assert nodes.has(andres)
 261         #     assert nodes.has(kate)
 262         fun nodes_with_label(lbl: String): Array[NeoNode] do
 263                 var res = get(base_url / "db/data/label/{lbl.to_percent_encoding}/nodes")
 264                 var nodes = new Array[NeoNode]
 265                 for json in res.as(JsonArray) do
 266                         var obj = json.as(JsonObject)
 267                         var node = load_node(obj["self"].to_s)
 268                         node.internal_properties = obj["data"].as(JsonObject)
 269                         nodes.add node
 270                 end
 271                 return nodes
 272         end
 273
 274         # Retrieve nodes belonging to all the specified `labels`.
 275         #
 276         #     var client = new Neo4jClient("http://localhost:7474")
 277         #
 278         #     var andres = new NeoNode
 279         #     andres.labels.add_all(["Human", "Male"])
 280         #     client.save_node(andres)
 281         #     var kate = new NeoNode
 282         #     kate.labels.add_all(["Human", "Female"])
 283         #     client.save_node(kate)
 284         #
 285         #     var nodes = client.nodes_with_labels(["Human", "Male"])
 286         #     assert nodes.has(andres)
 287         #     assert not nodes.has(kate)
 288         fun nodes_with_labels(labels: Array[String]): Array[NeoNode] do
 289                 assert not labels.is_empty
 290
 291                 # Build the query.
 292                 var buffer = new Buffer
 293                 buffer.append "match n where \{label_0\} in labels(n)"
 294                 for i in [1..labels.length[ do
 295                         buffer.append " and \{label_{i}\} in labels(n)"
 296                 end
 297                 buffer.append " return n"
 298                 var query = new CypherQuery.from_string(buffer.write_to_string)
 299                 for i in [0..labels.length[ do
 300                         query.params["label_{i}"] = labels[i]
 301                 end
 302
 303                 # Retrieve the answer.
 304                 var res = cypher(query)
 305                 var nodes = new Array[NeoNode]
 306                 for json in res.as(JsonObject)["data"].as(JsonArray) do
 307                         var obj = json.as(JsonArray).first.as(JsonObject)
 308                         var node = load_node(obj["self"].to_s)
 309                         node.internal_properties = obj["data"].as(JsonObject)
 310                         nodes.add node
 311                 end
 312                 return nodes
 313         end
 314
 315         # Perform a `CypherQuery`
 316         # see: CypherQuery
 317         fun cypher(query: CypherQuery): Serializable do
 318                 return post("{cypher_url}", query.to_rest)
 319         end
 320
 321         # GET JSON data from `url`
 322         fun get(url: String): Serializable do
 323                 var request = new JsonGET(url)
 324                 var response = request.execute
 325                 return parse_response(response)
 326         end
 327
 328         # POST `params` to `url`
 329         fun post(url: String, params: Serializable): Serializable do
 330                 var request = new JsonPOST(url)
 331                 request.json_data = params
 332                 var response = request.execute
 333                 return parse_response(response)
 334         end
 335
 336         # PUT `params` at `url`
 337         fun put(url: String, params: Serializable): Serializable do
 338                 var request = new JsonPUT(url)
 339                 request.json_data = params
 340                 var response = request.execute
 341                 return parse_response(response)
 342         end
 343
 344         # DELETE `url`
 345         fun delete(url: String): Serializable do
 346                 var request = new JsonDELETE(url)
 347                 var response = request.execute
 348                 return parse_response(response)
 349         end
 350
 351         # Parse the cURL `response` as a JSON string
 352         private fun parse_response(response: CurlResponse): Serializable do
 353                 if response isa CurlResponseSuccess then
 354                         var str = response.body_str
 355                         if str.is_empty then return new JsonObject
 356                         var res = str.parse_json
 357                         if res isa JsonParseError then
 358                                 var e = new NeoError(res.to_s, "JsonParseError")
 359                                 e.cause = res
 360                                 return e
 361                         end
 362                         if res == null then
 363                                 # empty response wrap it in empty object
 364                                 return new JsonObject
 365                         else if res isa JsonObject and res.has_key("exception") then
 366                                 var error = "Neo4jError::{res["exception"] or else "null"}"
 367                                 var msg = ""
 368                                 if res.has_key("message") then
 369                                         msg = res["message"].to_s
 370                                 end
 371                                 return new NeoError(msg, error)
 372                         else
 373                                 return res
 374                         end
 375                 else if response isa CurlResponseFailed then
 376                         return new NeoError("{response.error_msg} ({response.error_code})", "CurlError")
 377                 else
 378                         return new NeoError("Unexpected response \"{response}\".", "CurlError")
 379                 end
 380         end
 381 end
 382
 383 # A Cypher query for Neo4j REST API
 384 #
 385 # The Neo4j REST API allows querying with Cypher.
 386 # The results are returned as a list of string headers (columns), and a data part,
 387 # consisting of a list of all rows, every row consisting of a list of REST representations
 388 # of the field value - Node, Relationship, Path or any simple value like String.
 389 #
 390 # Example:
 391 #
 392 #     var client = new Neo4jClient("http://localhost:7474")
 393 #     var query = new CypherQuery
 394 #     query.nmatch("(n)-[r:LOVES]->(m)")
 395 #     query.nwhere("n.name=\"Andres\"")
 396 #     query.nreturn("m.name")
 397 #     var res = client.cypher(query).as(JsonObject)
 398 #     assert res["data"].as(JsonArray).first.as(JsonArray).first == "Kate"
 399 #
 400 # For more details, see: http://docs.neo4j.org/chunked/milestone/rest-api-cypher.html
 401 class CypherQuery
 402         # Query string to perform
 403         private var query: String = ""
 404
 405         # `params` to embed in the query like in prepared statements
 406         var params = new JsonObject
 407
 408         # init the query from a query string
 409         init from_string(query: String) do
 410                 self.query = query
 411         end
 412
 413         # init the query with parameters
 414         init with_params(params: JsonObject) do
 415                 self.params = params
 416         end
 417
 418         # Pass the argument `value` as the parameter `key`.
 419         #
 420         # SEE: `set`
 421         fun []=(key: String, value: nullable Serializable) do
 422                 params[key] = value
 423         end
 424
 425         # Add a `CREATE` statement to the query
 426         fun ncreate(query: String): CypherQuery do
 427                 self.query = "{self.query}CREATE {query} "
 428                 return self
 429         end
 430
 431         # Add a `START` statement to the query
 432         fun nstart(query: String): CypherQuery do
 433                 self.query = "{self.query}START {query} "
 434                 return self
 435         end
 436
 437         # Add a `MATCH` statement to the query
 438         fun nmatch(query: String): CypherQuery do
 439                 self.query = "{self.query}MATCH {query} "
 440                 return self
 441         end
 442
 443         # Add a `WHERE` statement to the query
 444         fun nwhere(query: String): CypherQuery do
 445                 self.query = "{self.query}WHERE {query} "
 446                 return self
 447         end
 448
 449         # Add a `AND` statement to the query
 450         fun nand(query: String): CypherQuery do
 451                 self.query = "{self.query}AND {query} "
 452                 return self
 453         end
 454
 455         # Add a `RETURN` statement to the query
 456         fun nreturn(query: String): CypherQuery do
 457                 self.query = "{self.query}RETURN {query} "
 458                 return self
 459         end
 460
 461         # Pass the argument `value` as the parameter `key`.
 462         #
 463         # Return `self`.
 464         #
 465         # ```
 466         # var query = (new CypherQuery).
 467         #               nmatch("(n)").
 468         #               nwhere("n.key = \{key\}").
 469         #               set("key", "foo")
 470         #
 471         # assert query.params["key"] == "foo"
 472         # ```
 473         #
 474         # SEE: `[]=`
 475         fun set(key: String, value: nullable Serializable): SELF do
 476                 self[key] = value
 477                 return self
 478         end
 479
 480         # Translate the query to the body of a corresponding Neo4j REST request.
 481         fun to_rest: JsonObject do
 482                 var obj = new JsonObject
 483                 obj["query"] = query
 484                 if not params.is_empty then
 485                         obj["params"] = params
 486                 end
 487                 return obj
 488         end
 489
 490         redef fun to_s do return to_rest.to_s
 491 end
 492
 493 # The fundamental units that form a graph are nodes and relationships.
 494 #
 495 # Entities can have two states:
 496 #
 497 # * linked: the NeoEntity references an existing node or edge in Neo4j
 498 # * unlinked: the NeoEntity is not yet created in Neo4j
 499 #
 500 # If the entity is initialized unlinked from neo4j:
 501 #
 502 #     # Create a disconnected node
 503 #     var andres = new NeoNode
 504 #     andres["name"] = "Andres"
 505 #     # At this point, the node is not linked
 506 #     assert not andres.is_linked
 507 #
 508 # Then we can link the entity to the base:
 509 #
 510 #     # Init client
 511 #     var client = new Neo4jClient("http://localhost:7474")
 512 #     client.save_node(andres)
 513 #     # The node is now linked
 514 #     assert andres.is_linked
 515 #
 516 # Entities can also be loaded from Neo4j:
 517 #
 518 #     # Get a node from Neo4j
 519 #     var url = andres.url.to_s
 520 #     var node = client.load_node(url)
 521 #     assert node.is_linked
 522 #
 523 # When working in connected mode, all reading operations are executed lazily on the base:
 524 #
 525 #     # Get the node `name` property
 526 #     assert node["name"] == "Andres"   # loaded lazily from base
 527 abstract class NeoEntity
 528         # Neo4j client connector
 529         private var neo: Neo4jClient is noinit
 530
 531         # Entity unique URL in Neo4j REST API
 532         var url: nullable String = null
 533
 534         # Temp id used in batch mode to update the entity
 535         private var batch_id: nullable Int = null
 536
 537         # Load the entity from base
 538         private init from_neo(neo: Neo4jClient, url: String) is nosuper do
 539                 self.neo = neo
 540                 self.url = url
 541         end
 542
 543         # Init entity from JSON representation
 544         private init from_json(neo: Neo4jClient, obj: JsonObject) is nosuper do
 545                 self.neo = neo
 546                 self.url = obj["self"].to_s
 547                 self.internal_properties = obj["data"].as(JsonObject)
 548         end
 549
 550         # Create a empty (and not-connected) entity
 551         init do
 552                 self.internal_properties = new JsonObject
 553         end
 554
 555         # Is the entity linked to a Neo4j database?
 556         fun is_linked: Bool do return url != null
 557
 558         # In Neo4j, both nodes and relationships can contain properties.
 559         # Properties are key-value pairs where the key is a string.
 560         # Property values are JSON formatted.
 561         #
 562         # Properties are loaded lazily
 563         fun properties: JsonObject do return internal_properties or else load_properties
 564
 565         private var internal_properties: nullable JsonObject = null
 566
 567         private fun load_properties: JsonObject do
 568                 var obj = neo.get(url.to_s / "properties").as(JsonObject)
 569                 internal_properties = obj
 570                 return obj
 571         end
 572
 573         # Get the entity `id` if connected to base
 574         fun id: nullable Int do
 575                 if url == null then return null
 576                 return url.split("/").last.to_i
 577         end
 578
 579         # Get the entity property at `key`
 580         fun [](key: String): nullable Serializable do
 581                 if not properties.has_key(key) then return null
 582                 return properties[key]
 583         end
 584
 585         # Set the entity property `value` at `key`
 586         fun []=(key: String, value: nullable Serializable) do properties[key] = value
 587
 588         # Is the property `key` set?
 589         fun has_key(key: String): Bool do return properties.has_key(key)
 590 end
 591
 592 # Nodes are used to represent entities stored in base.
 593 # Apart from properties and relationships (edges),
 594 # nodes can also be labeled with zero or more labels.
 595 #
 596 # A label is a `String` that is used to group nodes into sets.
 597 # All nodes labeled with the same label belongs to the same set.
 598 # A node may be labeled with any number of labels, including none,
 599 # making labels an optional addition to the graph.
 600 #
 601 # Creating new nodes:
 602 #
 603 #     var client = new Neo4jClient("http://localhost:7474")
 604 #
 605 #     var andres = new NeoNode
 606 #     andres.labels.add "Person"
 607 #     andres["name"] = "Andres"
 608 #     andres["age"] = 22
 609 #     client.save_node(andres)
 610 #     assert andres.is_linked
 611 #
 612 # Get nodes from Neo4j:
 613 #
 614 #     var url = andres.url.to_s
 615 #     var node = client.load_node(url)
 616 #     assert node["name"] == "Andres"
 617 #     assert node["age"].to_s.to_i      == 22
 618 class NeoNode
 619         super NeoEntity
 620
 621         private var internal_labels: nullable Array[String] = null
 622         private var internal_in_edges: nullable List[NeoEdge] = null
 623         private var internal_out_edges: nullable List[NeoEdge] = null
 624
 625         init do
 626                 super
 627                 self.internal_labels = new Array[String]
 628                 self.internal_in_edges = new List[NeoEdge]
 629                 self.internal_out_edges = new List[NeoEdge]
 630         end
 631
 632         redef fun to_s do
 633                 var tpl = new FlatBuffer
 634                 tpl.append "\{"
 635                 tpl.append "labels: [{labels.join(", ")}],"
 636                 tpl.append "data: {properties.to_json}"
 637                 tpl.append "\}"
 638                 return tpl.write_to_string
 639         end
 640
 641         # A label is a `String` that is used to group nodes into sets.
 642         # A node may be labeled with any number of labels, including none.
 643         # All nodes labeled with the same label belongs to the same set.
 644         #
 645         # Many database queries can work with these sets instead of the whole graph,
 646         # making queries easier to write and more efficient.
 647         #
 648         # Labels are loaded lazily
 649         fun labels: Array[String] do return internal_labels or else load_labels
 650
 651         private fun load_labels: Array[String] do
 652                 var labels = new Array[String]
 653                 var res = neo.get(url.to_s / "labels")
 654                 if res isa JsonArray then
 655                         for val in res do labels.add val.to_s
 656                 end
 657                 internal_labels = labels
 658                 return labels
 659         end
 660
 661         # Get the list of `NeoEdge` pointing to `self`
 662         #
 663         # Edges are loaded lazily
 664         fun in_edges: List[NeoEdge] do return internal_in_edges or else load_in_edges
 665
 666         private fun load_in_edges: List[NeoEdge] do
 667                 var edges = new List[NeoEdge]
 668                 var res = neo.get(url.to_s / "relationships/in").as(JsonArray)
 669                 for obj in res do
 670                         edges.add(new NeoEdge.from_json(neo, obj.as(JsonObject)))
 671                 end
 672                 internal_in_edges = edges
 673                 return edges
 674         end
 675
 676         # Get the list of `NeoEdge` pointing from `self`
 677         #
 678         # Edges are loaded lazily
 679         fun out_edges: List[NeoEdge] do return internal_out_edges or else load_out_edges
 680
 681         private fun load_out_edges: List[NeoEdge] do
 682                 var edges = new List[NeoEdge]
 683                 var res = neo.get(url.to_s / "relationships/out")
 684                 for obj in res.as(JsonArray) do
 685                         edges.add(new NeoEdge.from_json(neo, obj.as(JsonObject)))
 686                 end
 687                 internal_out_edges = edges
 688                 return edges
 689         end
 690
 691         # Get nodes pointed by `self` following a `rel_type` edge
 692         fun out_nodes(rel_type: String): Array[NeoNode] do
 693                 var res = new Array[NeoNode]
 694                 for edge in out_edges do
 695                         if edge.rel_type == rel_type then res.add edge.to
 696                 end
 697                 return res
 698         end
 699
 700         # Get nodes pointing to `self` following a `rel_type` edge
 701         fun in_nodes(rel_type: String): Array[NeoNode] do
 702                 var res = new Array[NeoNode]
 703                 for edge in in_edges do
 704                         if edge.rel_type == rel_type then res.add edge.from
 705                 end
 706                 return res
 707         end
 708 end
 709
 710 # A relationship between two nodes.
 711 # Relationships between nodes are a key part of a graph database.
 712 # They allow for finding related data. Just like nodes, relationships can have properties.
 713 #
 714 # Create a relationship:
 715 #
 716 #     var client = new Neo4jClient("http://localhost:7474")
 717 #     # Create nodes
 718 #     var andres = new NeoNode
 719 #     andres["name"] = "Andres"
 720 #     var kate = new NeoNode
 721 #     kate["name"] = "Kate"
 722 #     # Create a relationship of type `LOVES`
 723 #     var loves = new NeoEdge(andres, "LOVES", kate)
 724 #     client.save_edge(loves)
 725 #     assert loves.is_linked
 726 #
 727 # Get an edge from DB:
 728 #
 729 #     var url = loves.url.to_s
 730 #     var edge = client.load_edge(url)
 731 #     assert edge.from["name"].to_s == "Andres"
 732 #     assert edge.to["name"].to_s == "Kate"
 733 class NeoEdge
 734         super NeoEntity
 735
 736         private var internal_from: nullable NeoNode
 737         private var internal_to: nullable NeoNode
 738         private var internal_type: nullable String
 739         private var internal_from_url: nullable String
 740         private var internal_to_url: nullable String
 741
 742         init(from: NeoNode, rel_type: String, to: NeoNode) do
 743                 self.internal_from = from
 744                 self.internal_to = to
 745                 self.internal_type = rel_type
 746         end
 747
 748         redef init from_neo(neo, url) do
 749                 super
 750                 var obj = neo.get(url).as(JsonObject)
 751                 self.internal_type = obj["type"].to_s
 752                 self.internal_from_url = obj["start"].to_s
 753                 self.internal_to_url = obj["end"].to_s
 754         end
 755
 756         redef init from_json(neo, obj) do
 757                 super
 758                 self.internal_type = obj["type"].to_s
 759                 self.internal_from_url = obj["start"].to_s
 760                 self.internal_to_url = obj["end"].to_s
 761         end
 762
 763         # Get `from` node
 764         fun from: NeoNode do return internal_from or else load_from
 765
 766         private fun load_from: NeoNode do
 767                 var node = neo.load_node(internal_from_url.to_s)
 768                 internal_from = node
 769                 return node
 770         end
 771
 772         # Get `to` node
 773         fun to: NeoNode do return internal_to or else load_to
 774
 775         private fun load_to: NeoNode do
 776                 var node = neo.load_node(internal_to_url.to_s)
 777                 internal_to = node
 778                 return node
 779         end
 780
 781         # Get edge type
 782         fun rel_type: nullable String do return internal_type
 783
 784         # Get the JSON body of a REST request that create the relationship.
 785         private fun to_rest: JsonObject do
 786                 var obj = new JsonObject
 787                 if to.is_linked then
 788                         obj["to"] = to.url
 789                 else
 790                         obj["to"] = "\{{to.batch_id.to_s}\}"
 791                 end
 792                 obj["type"] = rel_type
 793                 obj["data"] = properties
 794                 return obj
 795         end
 796 end
 797
 798 # Batches are used to perform multiple operations on the REST API in one cURL request.
 799 # This can significantly improve performance for large insert and update operations.
 800 #
 801 # see: http://docs.neo4j.org/chunked/milestone/rest-api-batch-ops.html
 802 #
 803 # This service is transactional.
 804 # If any of the operations performed fails (returns a non-2xx HTTP status code),
 805 # the transaction will be rolled back and all changes will be undone.
 806 #
 807 # Example:
 808 #
 809 #     var client = new Neo4jClient("http://localhost:7474")
 810 #
 811 #     var node1 = new NeoNode
 812 #     var node2 = new NeoNode
 813 #     var edge = new NeoEdge(node1, "TO", node2)
 814 #
 815 #     var batch = new NeoBatch(client)
 816 #     batch.save_node(node1)
 817 #     batch.save_node(node2)
 818 #     batch.save_edge(edge)
 819 #     batch.execute
 820 #
 821 #     assert node1.is_linked
 822 #     assert node2.is_linked
 823 #     assert edge.is_linked
 824 class NeoBatch
 825
 826         # Neo4j client connector
 827         var client: Neo4jClient
 828
 829         # Jobs to perform in this batch
 830         #
 831         # The batch service expects an array of job descriptions as input,
 832         # each job description describing an action to be performed via the normal server API.
 833         var jobs = new HashMap[Int, NeoJob]
 834
 835         # Append a new job to the batch in JSON Format
 836         # see `NeoJob`
 837         fun new_job(nentity: NeoEntity): NeoJob do
 838                 var id = jobs.length
 839                 var job = new NeoJob(id, nentity)
 840                 jobs[id] = job
 841                 return job
 842         end
 843
 844         # Load a node in batch mode also load labels, data and edges
 845         fun load_node(node: NeoNode) do
 846                 var job = new_job(node)
 847                 job.action = load_node_data_action
 848                 job.method = "GET"
 849                 if node.id != null then
 850                         job.to = "/node/{node.id.to_s}"
 851                 else
 852                         job.to = "\{{node.batch_id.to_s}\}"
 853                 end
 854                 job = new_job(node)
 855                 job.action = load_node_labels_action
 856                 job.method = "GET"
 857                 if node.id != null then
 858                         job.to = "/node/{node.id.to_s}/labels"
 859                 else
 860                         job.to = "\{{node.batch_id.to_s}\}/labels"
 861                 end
 862         end
 863
 864         # Load in and out edges into node
 865         fun load_node_edges(node: NeoNode) do
 866                 var job = new_job(node)
 867                 job.action = load_node_in_edges_action
 868                 job.method = "GET"
 869                 if node.id != null then
 870                         job.to = "/node/{node.id.to_s}/relationships/in"
 871                 else
 872                         job.to = "\{{node.batch_id.to_s}\}/relationships/in"
 873                 end
 874                 job = new_job(node)
 875                 job.action = load_node_out_edges_action
 876                 job.method = "GET"
 877                 if node.id != null then
 878                         job.to = "/node/{node.id.to_s}/relationships/out"
 879                 else
 880                         job.to = "\{{node.batch_id.to_s}\}/relationships/out"
 881                 end
 882         end
 883
 884         # Create a `NeoNode` or a `NeoEdge` in batch mode.
 885         fun save_entity(nentity: NeoEntity) do
 886                 if nentity isa NeoNode then
 887                         save_node(nentity)
 888                 else if nentity isa NeoEdge then
 889                         save_edge(nentity)
 890                 else abort
 891         end
 892
 893         # Create a node in batch mode also create labels and edges
 894         fun save_node(node: NeoNode) do
 895                 if node.id != null or node.batch_id != null then return
 896                 # create node
 897                 var job = new_job(node)
 898                 node.batch_id = job.id
 899                 job.action = create_node_action
 900                 job.method = "POST"
 901                 job.to = "/node"
 902                 job.body = node.properties
 903                 # add labels
 904                 job = new_job(node)
 905                 job.method = "POST"
 906                 job.to = "\{{node.batch_id.to_s}\}/labels"
 907                 job.body = new JsonArray.from(node.labels)
 908                 # add edges
 909                 #save_edges(node.out_edges)
 910         end
 911
 912         # Create multiple nodes
 913         # also create labels and edges
 914         fun save_nodes(nodes: Collection[NeoNode]) do for node in nodes do save_node(node)
 915
 916         # Create an edge
 917         # nodes `edge.from` and `edge.to` will be created if not in base
 918         fun save_edge(edge: NeoEdge) do
 919                 if edge.id != null or edge.batch_id != null then return
 920                 # create nodes
 921                 save_node(edge.from)
 922                 save_node(edge.to)
 923                 # create edge
 924                 var job = new_job(edge)
 925                 edge.batch_id = job.id
 926                 job.action = create_edge_action
 927                 job.method = "POST"
 928                 if edge.from.id != null then
 929                         job.to = "/node/{edge.from.id.to_s}/relationships"
 930                 else
 931                         job.to = "\{{edge.from.batch_id.to_s}\}/relationships"
 932                 end
 933                 job.body = edge.to_rest
 934         end
 935
 936         # Create multiple edges
 937         fun save_edges(edges: Collection[NeoEdge]) do for edge in edges do save_edge(edge)
 938
 939         # Execute the batch and update local nodes
 940         fun execute: List[NeoError] do
 941                 var request = new JsonPOST(client.batch_url)
 942                 # request.headers["X-Stream"] = "true"
 943                 var json_jobs = new JsonArray
 944                 for job in jobs.values do json_jobs.add job.to_rest
 945                 request.json_data = json_jobs
 946                 var response = request.execute
 947                 var res = client.parse_response(response)
 948                 return finalize_batch(res)
 949         end
 950
 951         # Associate data from response in original nodes and edges
 952         private fun finalize_batch(response: Serializable): List[NeoError] do
 953                 var errors = new List[NeoError]
 954                 if not response isa JsonArray then
 955                         errors.add(new NeoError("Unexpected batch response format.", "Neo4jError"))
 956                         return errors
 957                 end
 958                 # print " {res.length} jobs executed"
 959                 for res in response do
 960                         if not res isa JsonObject then
 961                                 errors.add(new NeoError("Unexpected job format in batch response.", "Neo4jError"))
 962                                 continue
 963                         end
 964                         var id = res["id"].as(Int)
 965                         var job = jobs[id]
 966                         if job.action == create_node_action then
 967                                 var node = job.entity.as(NeoNode)
 968                                 node.batch_id = null
 969                                 node.url = res["location"].to_s
 970                         else if job.action == create_edge_action then
 971                                 var edge = job.entity.as(NeoEdge)
 972                                 edge.batch_id = null
 973                                 edge.url = res["location"].to_s
 974                         else if job.action == load_node_data_action then
 975                                 var node = job.entity.as(NeoNode)
 976                                 node.internal_properties = res["body"].as(JsonObject)["data"].as(JsonObject)
 977                         else if job.action == load_node_labels_action then
 978                                 var node = job.entity.as(NeoNode)
 979                                 var labels = new Array[String]
 980                                 for l in res["body"].as(JsonArray) do labels.add l.to_s
 981                                 node.internal_labels = labels
 982                         else if job.action == load_node_in_edges_action then
 983                                 var node = job.entity.as(NeoNode)
 984                                 var edges = res["body"].as(JsonArray)
 985                                 node.internal_in_edges = new List[NeoEdge]
 986                                 for edge in edges do
 987                                         node.internal_in_edges.add client.load_edge(edge.as(JsonObject)["self"].to_s)
 988                                 end
 989                         else if job.action == load_node_out_edges_action then
 990                                 var node = job.entity.as(NeoNode)
 991                                 var edges = res["body"].as(JsonArray)
 992                                 node.internal_out_edges = new List[NeoEdge]
 993                                 for edge in edges do
 994                                         node.internal_out_edges.add client.load_edge(edge.as(JsonObject)["self"].to_s)
 995                                 end
 996                         end
 997                 end
 998                 return errors
 999         end
1000
1001         # JobActions
1002         # TODO replace with enum
1003
1004         private fun create_node_action: Int do return 1
1005         private fun create_edge_action: Int do return 2
1006         private fun load_node_data_action: Int do return 3
1007         private fun load_node_labels_action: Int do return 4
1008         private fun load_node_in_edges_action: Int do return 5
1009         private fun load_node_out_edges_action: Int do return 6
1010 end
1011
1012 # A job that can be executed in a `NeoBatch`
1013 # This is a representation of a neo job in JSON Format
1014 #
1015 # Each job description should contain a `to` attribute, with a value relative to the data API root
1016 # (so http://localhost:7474/db/data/node becomes just /node), and a `method` attribute containing
1017 # HTTP verb to use.
1018 #
1019 # Optionally you may provide a `body` attribute, and an `id` attribute to help you keep track
1020 # of responses, although responses are guaranteed to be returned in the same order the job
1021 # descriptions are received.
1022 class NeoJob
1023         # The job uniq `id`
1024         var id: Int
1025         # Entity targeted by the job
1026         var entity: NeoEntity
1027
1028         init(id: Int, entity: NeoEntity) do
1029                 self.id = id
1030                 self.entity = entity
1031         end
1032
1033         # What kind of action do the job
1034         # used to attach responses to original Neo objets
1035         private var action: nullable Int = null
1036
1037         # Job HTTP method: `GET`, `POST`, `PUT`, `DELETE`...
1038         var method: String
1039         # Job service target: `/node`, `/labels` etc...
1040         var to: String
1041         # Body to send with the job service request
1042         var body: nullable Serializable = null
1043
1044         # JSON formated job
1045         fun to_rest: JsonObject do
1046                 var job = new JsonObject
1047                 job["id"] = id
1048                 job["method"] = method
1049                 job["to"] = to
1050                 if not body == null then
1051                         job["body"] = body
1052                 end
1053                 return job
1054         end
1055 end