neo4j-core 3.0.0.alpha.13 → 3.0.0.alpha.14

data/lib/neo4j/node.rb

@@ -20,20 +20,20 @@ module Neo4j
     include Wrapper
     include PropertyContainer
 
-    # @return [Hash] all properties of the node
+    # @return [Hash<Symbol, Object>] all properties of the node
     def props()
       raise 'not implemented'
     end
 
     # replace all properties with new properties
-    # @param [Hash] hash a hash of properties the node should have
-    def props=(hash)
+    # @param [Hash<Symbol, Object>] properties a hash of properties the node should have
+    def props=(properties)
       raise 'not implemented'
     end
 
     # Updates the properties, keeps old properties
-    # @param [Hash] hash hash of properties that should be updated on the node
-    def update_props(hash)
+    # @param [Hash<Symbol, Object>] properties hash of properties that should be updated on the node
+    def update_props(properties)
       raise 'not implemented'
     end
 
@@ -43,14 +43,14 @@ module Neo4j
     end
 
     # Directly set the property on the node (low level method, may need transaction)
-    # @param [Hash, String] key
+    # @param [Symbol, String] key
     # @param value see Neo4j::PropertyValidator::VALID_PROPERTY_VALUE_CLASSES for valid values
     def set_property(key, value)
       raise 'not implemented'
     end
 
     # Directly get the property on the node (low level method, may need transaction)
-    # @param [Hash, String] key
+    # @param [Symbol, String] key
     # @return the value of the key
     def get_property(key, value)
       raise 'not implemented'
@@ -59,7 +59,7 @@ module Neo4j
     # Creates a relationship of given type to other_node with optionally properties
     # @param [Symbol] type the type of the relation between the two nodes
     # @param [Neo4j::Node] other_node the other node
-    # @param [Hash] props optionally properties for the created relationship
+    # @param [Hash<Symbol, Object>] props optionally properties for the created relationship
     def create_rel(type, other_node, props = nil)
       raise 'not implemented'
     end
@@ -68,11 +68,11 @@ module Neo4j
     # Returns an enumeration of relationships.
     # It always returns relationships of depth one.
     #
-    # @param [Hash] opts the options to create a message with.
-    # @option opts [Symbol] :dir dir the direction of the relationship, allowed values: :both, :incoming, :outgoing.
-    # @option opts [Symbol] :type the type of relationship to navigate
-    # @option opts [Symbol] :between return all the relationships between this and given node
-    # @return [Enumerable] of Neo4j::Relationship objects
+    # @param [Hash] match the options to create a message with.
+    # @option match [Symbol] :dir dir the direction of the relationship, allowed values: :both, :incoming, :outgoing.
+    # @option match [Symbol] :type the type of relationship to navigate
+    # @option match [Symbol] :between return all the relationships between this and given node
+    # @return [Enumerable<Neo4j::Relationship>] of Neo4j::Relationship objects
     #
     # @example Return both incoming and outgoing relationships of any type
     #   node_a.rels
@@ -88,11 +88,13 @@ module Neo4j
     end
 
     # Adds one or more Neo4j labels on the node
+    # @param [Array<Symbol>] labels one or more labels to add
     def add_label(*labels)
       raise 'not implemented'
     end
 
     # Sets label on the node. Any old labels will be removed
+    # @param [Array<Symbol>] labels one or more labels to set
     def set_label(*labels)
       raise 'not implemented'
     end
@@ -103,7 +105,7 @@ module Neo4j
     end
 
     #
-    # @return all labels on the node
+    # @return [Array<Symbol>]all labels on the node
     def labels()
       raise 'not implemented'
     end
@@ -118,7 +120,7 @@ module Neo4j
       raise 'not implemented'
     end
 
-    # @returns all the Neo4j labels for this node
+    # @return all the Neo4j labels for this node
     def labels
       raise 'not implemented'
     end
@@ -150,12 +152,12 @@ module Neo4j
     end
 
     # Returns true or false if there is one or more relationships
-    # Same as `!! #rel()`
+    # @return [Boolean]
     def rel?(spec = {})
       raise 'not implemented'
     end
 
-    # Same as Neo4j::Node#exist?
+    # @return [Boolean] true if the node exists
     def exist?
       raise 'not implemented'
     end
@@ -164,8 +166,8 @@ module Neo4j
     # It does try to load a Ruby wrapper around each node
     # @abstract
     # @param (see #rels)
-    # @return [Enumerable] an Enumeration of either Neo4j::Node objects or wrapped Neo4j::Node objects
-    # @notice it's possible that the same node is returned more then once because of several relationship reaching to the same node, see #outgoing for alternative
+    # @return [Enumerable<Neo4j::Node>] an Enumeration of either Neo4j::Node objects or wrapped Neo4j::Node objects
+    # @note it's possible that the same node is returned more than once because of several relationship reaching to the same node, see #outgoing for alternative
     def nodes(specs = {})
       #rels(specs).map{|n| n.other_node(self)}
     end

data/lib/neo4j/relationship.rb

@@ -27,20 +27,20 @@ module Neo4j
     include EntityEquality
     include Wrapper
 
-    # @return [Hash] all properties of the relationship
+    # @return [Hash<Symbol,Object>] all properties of the relationship
     def props()
       raise 'not implemented'
     end
 
     # replace all properties with new properties
-    # @param [Hash] hash a hash of properties the relationship should have
-    def props=(hash)
+    # @param [Hash] properties a hash of properties the relationship should have
+    def props=(properties)
       raise 'not implemented'
     end
 
     # Updates the properties, keeps old properties
-    # @param [Hash] hash hash of properties that should be updated on the relationship
-    def update_props(hash)
+    # @param [Hash<Symbol,Object>] properties hash of properties that should be updated on the relationship
+    def update_props(properties)
       raise 'not implemented'
     end
 
@@ -70,7 +70,7 @@ module Neo4j
     end
 
     # Same as #start_node but does not wrap the node
-    # @returns [Neo4j::Node]
+    # @return [Neo4j::Node]
     def _start_node
       raise 'not implemented'
     end
@@ -82,7 +82,7 @@ module Neo4j
     end
 
     # Same as #end_node but does not wrap the node
-    # @returns [Neo4j::Node]
+    # @return [Neo4j::Node]
     def _end_node
       raise 'not implemented'
     end

data/lib/neo4j/session.rb

@@ -46,39 +46,72 @@ module Neo4j
       end
     end
 
-    # Executes a Cypher Query
-    # Returns an enumerable of hash values, column => value
+    # Executes a Cypher Query.
+    # Returns an enumerable of hash values where each hash corresponds to a row unless +return+ or +map_return+
+    # is not an array. The search result can be mapped to Neo4j::Node or Neo4j::Relationship is your own Ruby wrapper class
+    # by specifying a map_return parameter.
     #
-    # @example Using the Cypher DSL
-    #  q = session.query("START n=node({param}) RETURN n", :param => 0)
-    #  q.first[:n] #=> the node
-    #  q.columns.first => :n
+    # @param [Hash, String] q the cypher query, as a pure string query or a hash which will generate a cypher string.
+    # @option q [Hash] :params cypher parameters
+    # @option q [Symbol,Hash] :label the label to match. You can specify several labels by using a hash of variable names and labels.
+    # @option q [Symbol] :conditions key and value of properties which the label nodes must match
+    # @option q [Hash] :conditions key and value of properties which the label nodes must match
+    # @option q [String, Array] :match the cypher match clause
+    # @option q [String, Array] :where the cypher where clause
+    # @option q [String, Array, Symbol] :return the cypher where clause
+    # @option q [String, Hash, Symbol] :map_return mapping of the returned values, e.g. :id_to_node, :id_to_rel, or :value
+    # @option q [Hash<Symbol, Proc>] :map_return_procs custom mapping functions of :map_return types
+    # @option q [String,Symbol,Array<Hash>] :order the order
+    # @option q [Fixnum] :limit enables the return of only subsets of the total result.
+    # @option q [Fixnum] :skip enables the return of only subsets of the total result.
+    # @return [Enumerable] the result, an enumerable of Neo4j::Node objects unless a pure cypher string is given or return/map_returns is specified, see examples.
+    # @raise CypherError if invalid cypher
+    # @example Cypher String and parameters
+    #   Neo4j::Session.query("START n=node({p}) RETURN ID(n)", params: {p: 42})
     #
-    # @example Using the Cypher DSL
-    #  q = session.query{ match node(3) <=> node(:x); ret :x}
-    #  q.first[:n] #=> the @node
-    #  q.columns.first => :n
+    # @example label
+    #   # If there is no :return parameter it will try to return Neo4j::Node objects
+    #   # Default parameter is :n in the generated cypher
+    #   Neo4j::Session.query(label: :person) # => MATCH (n:`person`) RETURN ID(n) # or RETURN n for embedded
     #
-    # @example Using the Cypher DSL and one parameter (n=Neo4j.ref_node)
-    #  q = session.query(Neo4j.ref_node){|n| n <=> node(:x); :x}
-    #  q.first[:n] #=> the @node
-    #  q.columns.first => :n
+    # @example to_s
+    #   # What Cypher is returned ? check with to_s
+    #   Neo4j::Session.query(label: :person).to_s # =>
     #
-    # @example Using an array of nodes
-    #  # same as - two_nodes=node(Neo4j.ref_node.neo_id, node_b.neo_id), b = node(b.neo_id)
-    #  q = session.query([Neo4j.ref_node, node_b], node_c){|two_nodes, b| two_nodes <=> b; b}
+    # @example return
+    #   Neo4j::Session.query(label: :person, return: :age)  # returns age properties
+    #   Neo4j::Session.query(label: :person, return: [:name, :age]) # returns a hash of name and age properties
+    #   Neo4j::Session.query(label: :person, return: 'count(n) AS c')
+    #
+    # @example map_return - an Enumerable of names (String)
+    #   Neo4j::Session.query("START n=node(42) RETURN n.name", map_return: :value)
+    #
+    # @example map_return - Enumerable of an Hash with name property, Neo4j::Relationship and Neo4j::Node as values
+    #   Neo4j::Session.query("START n=node(42) MATCH n-[r]->[x] RETURN n.name as N, ID(r) as R, ID(x) as X",
+    #      map_return: {N: :value, R: :id_to_rel, X: :id_to_node})
+    #
+    # @example map_return, only for embedded_db, to_rel, and to_node allows direct mapping to Neo4j::Node and Neo4j::Relationship without ID(n)
+    #   Neo4j::Session.query("START n=node(42) MATCH n-[r]->[x] RETURN n.name as N, r, x", map_return: {N: :value, r: :to_rel, x: :to_node})
+    #
+    # @example map_return_procs, custom mapping function
+    #   Neo4j::Session.query(label: :person, map_return: :age_times_two, map_return_procs: {age_times_two: ->(row){(row[:age] || 0) * 2}})
+    #
+    # @example match
+    #   Neo4j::Session.query(label: :person, match: 'n--m')
+    #
+    # @example where
+    #   Neo4j::Session.query(label: :person, where: 'n.age > 40')
+    #   Neo4j::Session.query(label: :person, where: 'n.age > {age}', params: {age: 40})
+    #
+    # @example condition
+    #   Neo4j::Session.query(label: :person, conditions: {age: 42})
+    #   Neo4j::Session.query(label: :person, conditions: {name: /foo?bar.*/})
     #
-    # @see Cypher
     # @see http://docs.neo4j.org/chunked/milestone/cypher-query-lang.html The Cypher Query Language Documentation
-    # @note Returns a read-once only forward iterable.
-    # @param params parameter for the query_dsl block
-    # @return [Neo4j::Cypher::ResultWrapper] a forward read once only Enumerable, containing hash values.
+    # @note Returns a read-once only forward iterable for the embedded database.
     #
-    # @abstract
-    def query(*params, &query_dsl)
-      cypher_params = params.pop if params.last.is_a?(Hash)
-      q = query_dsl ? Neo4j::Cypher.query(*params, &query_dsl).to_s : params[0]
-      _query(q, cypher_params)
+    def query(q)
+      raise 'not implemented, abstract'
     end
 
     # Same as #query but does not accept an DSL and returns the raw result from the database.
@@ -92,7 +125,7 @@ module Neo4j
       # Creates a new session to Neo4j
       # @see also Neo4j::Server::CypherSession#open for :server_db params
       # @param db_type the type of database, e.g. :embedded_db, or :server_db
-      def open(db_type, *params)
+      def open(db_type=:server_db, *params)
         register(create_session(db_type, params))
       end
 
@@ -112,6 +145,11 @@ module Neo4j
         @@current_session
       end
 
+      # @see Neo4j::Session#query
+      def query(*params)
+        current.query(*params)
+      end
+
       def named(name)
         @@all_sessions[name] || raise("No session named #{name}.")
       end
@@ -147,8 +185,12 @@ module Neo4j
         @@current_session = nil if @@current_session == session
       end
 
+      def inspect
+         "Neo4j::Session available: #{@@factories && @@factories.keys}"
+      end
+
       def register_db(db, &session_factory)
-        raise "Factory for #{db} already exists" if @@factories[db]
+        puts "replace factory for #{db}" if @@factories[db]
         @@factories[db] = session_factory
       end
     end

data/lib/neo4j/session.rb~

@@ -0,0 +1,202 @@
+module Neo4j
+  class Session
+
+    @@current_session = nil
+    @@all_sessions = {}
+    @@factories = {}
+
+    # @abstract
+    def close
+      self.class.unregister(self)
+    end
+
+    # Only for embedded database
+    # @abstract
+    def start
+      raise "not impl."
+    end
+
+    # Only for embedded database
+    # @abstract
+    def shutdown
+      raise "not impl."
+    end
+
+    # Only for embedded database
+    # @abstract
+    def running
+      raise "not impl."
+    end
+
+    def auto_commit?
+      true # TODO
+    end
+
+    # @abstract
+    def begin_tx
+      raise "not impl."
+    end
+
+    class CypherError < StandardError
+      attr_reader :error_msg, :error_status, :error_code
+      def initialize(error_msg, error_code, error_status)
+        super(error_msg)
+        @error_msg = error_msg
+        @error_status = error_status
+      end
+    end
+
+    # Executes a Cypher Query.
+    # Returns an enumerable of hash values where each hash corresponds to a row unless +return+ or +map_return+
+    # is not an array. The search result can be mapped to Neo4j::Node or Neo4j::Relationship is your own Ruby wrapper class
+    # by specifying a map_return parameter.
+    #
+    # @param [Hash, String] q the cypher query, as a pure string query or a hash which will generate a cypher string.
+    # @option q [Hash] :params cypher parameters
+    # @option q [Symbol,Hash] :label the label to match. You can specify several labels by using a hash of variable names and labels.
+    # @option q [Symbol] :conditions key and value of properties which the label nodes must match
+    # @option q [Hash] :conditions key and value of properties which the label nodes must match
+    # @option q [String, Array] :match the cypher match clause
+    # @option q [String, Array] :where the cypher where clause
+    # @option q [String, Array, Symbol] :return the cypher where clause
+    # @option q [String, Hash, Symbol] :map_return mapping of the returned values, e.g. :id_to_node, :id_to_rel, or :value
+    # @option q [Hash<Symbol, Proc>] :map_return_procs custom mapping functions of :map_return types
+    # @option q [String,Symbol,Array<Hash>] :order the order
+    # @option q [Fixnum] :limit enables the return of only subsets of the total result.
+    # @option q [Fixnum] :skip enables the return of only subsets of the total result.
+    # @return [Enumerable] the result, an enumerable of Neo4j::Node objects unless a pure cypher string is given or return/map_returns is specified, see examples.
+    # @raise CypherError if invalid cypher
+    # @example Cypher String and parameters
+    #   Neo4j::Session.query("START n=node({p}) RETURN ID(n)", params: {p: 42})
+    #
+    # @example label
+    #   # If there is no :return parameter it will try to return Neo4j::Node objects
+    #   # Default parameter is :n in the generated cypher
+    #   Neo4j::Session.query(label: :person) # => MATCH (n:`person`) RETURN ID(n) # or RETURN n for embedded
+    #
+    # @example to_s
+    #   # What Cypher is returned ? check with to_s
+    #   Neo4j::Session.query(label: :person).to_s # =>
+    #
+    # @example return
+    #   Neo4j::Session.query(label: :person, return: :age)  # returns age properties
+    #   Neo4j::Session.query(label: :person, return: [:name, :age]) # returns a hash of name and age properties
+    #   Neo4j::Session.query(label: :person, return: 'count(n) AS c')
+    #
+    # @example map_return - an Enumerable of names (String)
+    #   Neo4j::Session.query("START n=node(42) RETURN n.name", map_return: :value)
+    #
+    # @example map_return - Enumerable of an Hash with name property, Neo4j::Relationship and Neo4j::Node as values
+    #   Neo4j::Session.query("START n=node(42) MATCH n-[r]->[x] RETURN n.name as N, ID(r) as R, ID(x) as X",
+    #      map_return: {N: :value, R: :id_to_rel, X: :id_to_node})
+    #
+    # @example map_return, only for embedded_db, to_rel, and to_node allows direct mapping to Neo4j::Node and Neo4j::Relationship without ID(n)
+    #   Neo4j::Session.query("START n=node(42) MATCH n-[r]->[x] RETURN n.name as N, r, x", map_return: {N: :value, r: :to_rel, x: :to_node})
+    #
+    # @example map_return_procs, custom mapping function
+    #   Neo4j::Session.query(label: :person, map_return: :age_times_two, map_return_procs: {age_times_two: ->(row){(row[:age] || 0) * 2}})
+    #
+    # @example match
+    #   Neo4j::Session.query(label: :person, match: 'n--m')
+    #
+    # @example where
+    #   Neo4j::Session.query(label: :person, where: 'n.age > 40')
+    #   Neo4j::Session.query(label: :person, where: 'n.age > {age}', params: {age: 40})
+    #
+    # @example condition
+    #   Neo4j::Session.query(label: :person, conditions: {age: 42})
+    #   Neo4j::Session.query(label: :person, conditions: {name: /foo?bar.*/})
+    #
+    # @see http://docs.neo4j.org/chunked/milestone/cypher-query-lang.html The Cypher Query Language Documentation
+    # @note Returns a read-once only forward iterable for the embedded database.
+    #
+    def query(q)
+      raise 'not implemented, abstract'
+    end
+
+    # Same as #query but does not accept an DSL and returns the raw result from the database.
+    # Notice, it might return different values depending on which database is used, embedded or server.
+    # @abstract
+    def _query(*params)
+      raise 'not implemented'
+    end
+
+    class << self
+      # Creates a new session to Neo4j
+      # @see also Neo4j::Server::CypherSession#open for :server_db params
+      # @param db_type the type of database, e.g. :embedded_db, or :server_db
+      def open(db_type=:server_db, *params)
+        register(create_session(db_type, params))
+      end
+
+      def open_named(db_type, name, default = nil, *params)
+        raise "Multiple sessions is currently only supported for Neo4j Server connections." unless db_type == :server_db
+        register(create_session(db_type, params), name, default)
+      end
+
+      def create_session(db_type, params = {})
+        unless (@@factories[db_type])
+          raise "Can't connect to database '#{db_type}', available #{@@factories.keys.join(',')}"
+        end
+        @@factories[db_type].call(*params)
+      end
+
+      def current
+        @@current_session
+      end
+
+      # @see Neo4j::Session#query
+      def query(*params)
+        current.query(*params)
+      end
+
+      def named(name)
+        @@all_sessions[name] || raise("No session named #{name}.")
+      end
+
+      def set_current(session)
+        @@current_session = session
+      end
+
+      def add_listener(&listener)
+        self._listeners << listener
+      end
+
+      def _listeners
+        @@listeners ||= []
+        @@listeners
+      end
+
+      def _notify_listeners(event, data)
+        _listeners.each {|li| li.call(event, data)}
+      end
+
+      def register(session, name = nil, default = nil)
+        if default == true
+          set_current(session)
+        elsif default.nil?
+          set_current(session) unless @@current_session
+        end
+        @@all_sessions[name] = session if name
+        @@current_session
+      end
+
+      def unregister(session)
+        @@current_session = nil if @@current_session == session
+      end
+
+      def all_sessions
+        @@all_sessions
+      end
+
+      def inspect
+         "Neo4j::Session available: #{@@factories && @@factories.keys}"
+      end
+
+      def register_db(db, &session_factory)
+        puts "replace factory for #{db}" if @@factories[db]
+        @@factories[db] = session_factory
+      end
+    end
+  end
+end