neo4j 1.0.0.beta.13 → 1.0.0.beta.14

data/lib/neo4j/index/wrapped_query.rb

@@ -0,0 +1,59 @@
+module Neo4j
+  module Index
+
+    class WrappedQuery
+      include Enumerable
+
+      def initialize(index, query)
+        @index = index
+        @query = query
+      end
+
+      def each
+        hits.each { |n| yield n.wrapper }
+      end
+
+      def close
+        @hits.close if @hits
+      end
+
+      def empty?
+        hits.size == 0
+      end
+
+      def [](index)
+        each_with_index {|node,i| break node if index == i}
+      end
+
+      def size
+        hits.size
+      end
+
+      def hits
+        @hits ||= perform_query
+      end
+
+      def desc(*fields)
+        @order = fields.inject(@order || {}) { |memo, field| memo[field] = true; memo }
+        self
+      end
+
+      def asc(*fields)
+        @order = fields.inject(@order || {}) { |memo, field| memo[field] = false; memo }
+        self
+      end
+
+      def perform_query
+        if @order
+          java_sort_fields = @order.keys.inject([]) do |memo, field|
+            memo << org.apache.lucene.search.SortField.new(field.to_s, org.apache.lucene.search.SortField::STRING, @order[field])
+          end
+          sort = org.apache.lucene.search.Sort.new(*java_sort_fields)
+          @query = org.neo4j.index.impl.lucene.QueryContext.new(@query).sort(sort)
+        end
+        @index.query(@query)
+      end
+    end
+  end
+end
+

data/lib/neo4j/load.rb

@@ -1,17 +1,20 @@
 module Neo4j
+
+  # Module used to load both Nodes and Relationship from the database
   module Load
-    def wrapper(node)
+    def wrapper(node) # :nodoc:
       return node unless node.property?(:_classname)
       to_class(node[:_classname]).load_wrapper(node)
     end
 
-    def to_class(class_name)
+    def to_class(class_name) # :nodoc:
       class_name.split("::").inject(Kernel) {|container, name| container.const_get(name.to_s) }
     end
 
+    # Checks if the given node or node id exists in the database.
     def exist?(node_or_node_id, db = Neo4j.started_db)
       id = node_or_node_id.kind_of?(Fixnum) ?  node_or_node_id : node_or_node_id.id
-      load(id, db) != nil
+      _load(id, db) != nil
     end
   end
 end

data/lib/neo4j/mapping/class_methods/relationship.rb

@@ -33,8 +33,8 @@ module Neo4j::Mapping
         module_eval(%Q{
                 def #{rel_type}_rels
                     dsl = #{clazz}._decl_rels[:'#{rel_type.to_s}']
-                    Neo4j::Mapping::HasN.new(self, dsl).rels
-      end}, __FILE__, __LINE__)
+                    dsl.all_relationships(self).wrapped
+                end}, __FILE__, __LINE__)
 
         _decl_rels[rel_type.to_sym] = Neo4j::Mapping::DeclRelationshipDsl.new(rel_type, false, params)
       end
@@ -64,26 +64,20 @@ module Neo4j::Mapping
         clazz = self
         module_eval(%Q{def #{rel_type}=(value)
                   dsl = #{clazz}._decl_rels[:'#{rel_type.to_s}']
-                  dir = dsl.direction
-                  dsl = dsl.incoming? ? dsl.incoming_dsl(self) : dsl
-                  rel = dsl.single_relationship(self, dir)
+                  rel = dsl.single_relationship(self)
                   rel.del unless rel.nil?
-                  dsl.create_relationship_to(self, value)
+                  dsl.create_relationship_to(self, value) if value
               end}, __FILE__, __LINE__)
 
         module_eval(%Q{def #{rel_type}
                   dsl = #{clazz}._decl_rels[:'#{rel_type.to_s}']
-                  dir = dsl.direction
-                  dsl = dsl.incoming? ? dsl.incoming_dsl(self) : dsl
-                  dsl.single_relationship(self, dir)
+                  dsl.single_node(self)
               end}, __FILE__, __LINE__)
 
-        # TODO
         module_eval(%Q{
               def #{rel_type}_rel
                   dsl = #{clazz}._decl_rels[:'#{rel_type.to_s}']
-                  r = Neo4j::Mapping::HasN.new(self, dsl).rels
-                  [*r][0]
+                  dsl.single_relationship(self)
     end}, __FILE__, __LINE__)
 
         _decl_rels[rel_type.to_sym] = Neo4j::Mapping::DeclRelationshipDsl.new(rel_type, true, params)
@@ -91,4 +85,4 @@ module Neo4j::Mapping
 
     end
   end
-end
+end

data/lib/neo4j/mapping/class_methods/rule.rb

@@ -61,16 +61,16 @@ module Neo4j::Mapping
         end
 
         def rule_for(clazz)
-          Neo4j.ref_node.outgoing(clazz).first
+          Neo4j.ref_node._rel(:outgoing, clazz)._end_node
         end
 
 
-        def on_relationship_created(rel)
-          trigger_start_node = trigger?(rel.start_node)
-          trigger_end_node   = trigger?(rel.end_node)
+        def on_relationship_created(rel, *)
+          trigger_start_node = trigger?(rel._start_node)
+          trigger_end_node   = trigger?(rel._end_node)
           # end or start node must be triggered by this event
           return unless trigger_start_node || trigger_end_node
-          on_property_changed(trigger_start_node ? rel.start_node : rel.end_node)
+          on_property_changed(trigger_start_node ? rel._start_node : rel._end_node)
         end
 
 
@@ -100,8 +100,7 @@ module Neo4j::Mapping
 
         def run_rule(rule, node)
           if rule.arity != 1
-            wrapper = Neo4j::Node.wrapper(node)
-            wrapper.instance_eval(&rule)
+            node.wrapper.instance_eval(&rule)
           else
             rule.call(node)
           end

data/lib/neo4j/mapping/decl_relationship_dsl.rb

@@ -89,22 +89,33 @@ module Neo4j::Mapping
       @direction == :incoming
     end
 
-    def incoming_dsl(node)
-      # which class specifies the incoming DSL ?
-      clazz = to_class || node.class
-      dsl = clazz._decl_rels[to_type]
-      raise "Unspecified outgoing relationship '#{to_type}' for incoming relationship '#{rel_id}' on class #{clazz}" if dsl.nil?
+    def incoming_dsl
+      dsl = to_class._decl_rels[to_type]
+      raise "Unspecified outgoing relationship '#{to_type}' for incoming relationship '#{rel_id}' on class #{to_class}" if dsl.nil?
       dsl
     end
 
-    def single_relationship(node, dir)
-      type = type_to_java(namespace_type)
-      dir  = dir_to_java(dir)
-      rel = node._java_node.getSingleRelationship(type, dir)
-      rel.nil? ? nil : rel.other_node(node).wrapper
+    def single_node(node)
+      rel = single_relationship(node)
+      rel && rel.other_node(node).wrapper
+    end
+
+    def single_relationship(node)
+      dir = direction
+      dsl = incoming? ? incoming_dsl : self
+      node._java_node.rel(dir, dsl.namespace_type)
+    end
+
+    def all_relationships(node)
+      dsl = incoming? ? incoming_dsl : self
+      type = type_to_java(dsl.namespace_type)
+      dir  = dir_to_java(direction)
+      node._java_node.getRelationships(type, dir)
     end
 
     def create_relationship_to(node, other)
+      dsl = incoming? ? incoming_dsl : self
+
       # If the are creating an incoming relationship we need to swap incoming and outgoing nodes
       if @direction == :outgoing
         from, to = node, other
@@ -112,9 +123,10 @@ module Neo4j::Mapping
         from, to = other, node
       end
 
-      java_type = type_to_java(namespace_type)
+      java_type = type_to_java(dsl.namespace_type)
+
       rel = from._java_node.create_relationship_to(to._java_node, java_type)
-      rel[:_classname] =  relationship_class.to_s if relationship_class
+      rel[:_classname] =  dsl.relationship_class.to_s if dsl.relationship_class
 
       # TODO - not implemented yet
       # the from.neo_id is only used for cascade_delete_incoming since that node will be deleted when all the list items has been deleted.

data/lib/neo4j/mapping/has_n.rb

@@ -11,7 +11,7 @@ module Neo4j
       def initialize(node, dsl) # :nodoc:
         @node = node
         @direction = dsl.direction
-        @dsl = @direction == :outgoing ? dsl : dsl.incoming_dsl(node)
+        @dsl = @direction == :outgoing ? dsl : dsl.incoming_dsl
       end
 
       def to_s
@@ -41,16 +41,6 @@ module Neo4j
       end
 
 
-      # Returns the relationships instead of the nodes.
-      #
-      # ==== Example
-      # # return the relationship objects between the folder and file nodes:
-      # folder.files.rels.each {|x| ...}
-      #
-      def rels
-        Neo4j::RelationshipTraverser.new(@node._java_node, [@dsl.namespace_type], @direction)
-      end
-
       # Returns true if there are no node in this type of relationship
       def empty?
         first != nil

data/lib/neo4j/mapping/node_mixin.rb

@@ -6,7 +6,7 @@ module Neo4j::Mapping
 
     def_delegators :@_java_node, :[]=, :[], :property?, :props, :attributes, :update, :neo_id, :id, :rels, :rel?, :to_param, :getId,
                    :rel, :del, :list?, :print, :print_sub, :outgoing, :incoming, :both,
-                   :equal?, :eql?, :==, :exist?, :getRelationships, :getSingleRelationship
+                   :equal?, :eql?, :==, :exist?, :getRelationships, :getSingleRelationship, :rels_raw, :rel
 
 
     # --------------------------------------------------------------------------
@@ -49,7 +49,7 @@ module Neo4j::Mapping
         class << self
           alias_method :orig_new, :new
         end
-      end
+      end unless c.respond_to?(:orig_new)
 
       c.extend ClassMethods::Root
       c.extend ClassMethods::Property

data/lib/neo4j/neo4j.rb

@@ -59,6 +59,11 @@ module Neo4j
       Enumerator.new(this_db, :each_node)
     end
 
+    # Same as #all_nodes but does not return wrapped nodes.
+    def _all_nodes(this_db = self.started_db)
+      Enumerator.new(this_db, :_each_node)
+    end
+
     def event_handler(this_db = default_db)
       this_db.event_handler
     end

data/lib/neo4j/node.rb

@@ -42,16 +42,52 @@ module Neo4j
   end
 
 
+  # A node in the graph with properties and relationships to other entities.
+  # Along with relationships, nodes are the core building blocks of the Neo4j data representation model.
+  # Node has three major groups of operations: operations that deal with relationships, operations that deal with properties and operations that traverse the node space.
+  # The property operations give access to the key-value property pairs.
+  # Property keys are always strings. Valid property value types are the primitives(<tt>String</tt>, <tt>Fixnum</tt>, <tt>Float</tt>, <tt>Boolean</tt>), and arrays of those primitives.
+  #
+  # === Instance Methods form Included Mixins
+  # * Neo4j::Property - methods that deal with properties
+  # * Neo4j::NodeRelationship methods for relationship
+  # * Neo4j::Equal equality operators: <tt>eql?</tt>, <tt>equal</tt>, <tt>==</tt>
+  # * Neo4j::Index lucene index methods, like indexing a node
+  #
+  # === Class Methods from Included Mixins
+  # * Neo4j::Index::ClassMethods lucene index class methods, like find
+  # * Neo4j::Load - methods for loading a node
+  #
+  # See also the Neo4j::NodeMixin if you want to wrap a node with your own Ruby class.
+  #
   class Node
     extend Neo4j::Index::ClassMethods
+    extend Neo4j::Load
 
     self.node_indexer self
 
     class << self
-      include Neo4j::Load
 
-      # Creates a new node using the default db instance when given no args
-      # Same as Neo4j::Node#create
+      # Returns a new neo4j Node.
+      # The return node is actually an Java obejct of type org.neo4j.graphdb.Node java object
+      # which has been extended (see the included mixins for Neo4j::Node).
+      #
+      # The created node will have a unique id - Neo4j::Property#neo_id
+      #
+      # ==== Parameters
+      # *args :: a hash of properties to initialize the node with or nil
+      #
+      # ==== Returns
+      # org.neo4j.graphdb.Node java object
+      #
+      # ==== Examples
+      #
+      #  Neo4j::Transaction.run do
+      #    Neo4j::Node.new
+      #    Neo4j::Node.new :name => 'foo', :age => 100
+      #  end
+      #
+      #
       def new(*args)
         # the first argument can be an hash of properties to set
         props = args[0].respond_to?(:each_pair) && args[0]
@@ -67,15 +103,28 @@ module Neo4j
       # create is the same as new
       alias_method :create, :new
 
+      # Loads a node or wrapped node given a native java node or an id.
+      # If there is a Ruby wrapper for the node then it will create a Ruby object that will
+      # wrap the java node (see Neo4j::NodeMixin).
+      #
+      # If the node does not exist it will return nil
+      #
       def load(node_id, db = Neo4j.started_db)
-        wrapper(db.graph.get_node_by_id(node_id.to_i))
+        node = _load(node_id, db)
+        return nil if node.nil?
+        node.wrapper
+      end
+
+      # Same as load but does not return the node as a wrapped Ruby object.
+      #
+      def _load(node_id, db)
+        db.graph.get_node_by_id(node_id.to_i)
       rescue java.lang.IllegalStateException
         nil # the node has been deleted
       rescue org.neo4j.graphdb.NotFoundException
         nil
       end
 
-
     end
   end
 end

data/lib/neo4j/node_relationship.rb

@@ -4,7 +4,38 @@ module Neo4j
   module NodeRelationship
     include ToJava
 
-    def outgoing(type=nil)
+
+    # Returns the outgoing nodes for this node.
+    #
+    # ==== Returns
+    # a Neo4j::NodeTraverser which can be used to further specify which nodes should be included
+    # in traversal by using the <tt>depth</tt>, <tt>filter</tt> and <tt>prune</tt> methods.
+    #
+    # ==== Examples
+    #   # Find all my friends (nodes of depth 1 of type <tt>friends</tt>)
+    #   me.outgoing(:friends).each {|friend| puts friend[:name]}
+    #
+    #   # Find all my friends and their friends (nodes of depth 1 of type <tt>friends</tt>)
+    #   # me.outgoing(:friends).depth(2).each {|friend| puts friend[:name]}
+    #
+    #   # Find all my friends and include my self in the result
+    #   me.outgoing(:friends).depth(4).include_start_node.each {...}
+    #
+    #   # Find all my friends friends friends, etc. at any depth
+    #   me.outgoing(:friends).depth(:all).each {...}
+    #
+    #   # Find all my friends friends but do not include my friends (only depth == 2)
+    #   me.outgoing(:friends).depth(2).filter{|path| path.length == 2}
+    #
+    #   # Find all my friends but 'cut off' some parts of the traversal path
+    #   me.outgoing(:friends).depth(42).prune(|path| an_expression_using_path_returning_true_false }
+    #
+    #   # Find all my friends and work colleges
+    #   me.outgoing(:friends).outgoing(:work).each {...}
+    #
+    # Of course all the methods <tt>outgoing</tt>, <tt>incoming</tt>, <tt>both</tt>, <tt>depth</tt>, <tt>include_start_node</tt>, <tt>filter</tt>, and <tt>prune</tt> can be combined.
+    #
+    def outgoing(type)
       if type
         NodeTraverser.new(self).outgoing(type)
       else
@@ -13,7 +44,12 @@ module Neo4j
       end
     end
 
-    def incoming(type=nil)
+
+    # Returns the incoming nodes of given type(s).
+    #
+    # See #outgoing
+    #
+    def incoming(type)
       if type
         NodeTraverser.new(self).incoming(type)
       else
@@ -22,6 +58,12 @@ module Neo4j
       end
     end
 
+    # Returns both incoming and outgoing nodes of given types(s)
+    #
+    # If a type is not given then it will return all types of relationships.
+    #
+    # See #outgoing
+    #
     def both(type=nil)
       if type
         NodeTraverser.new(self).both(type)
@@ -30,11 +72,58 @@ module Neo4j
       end
     end
 
+
+    # Returns an enumeration of relationship objects.
+    # It always returns relationship of depth one.
+    #
+    # See Neo4j::Relationship
+    #
+    # ==== Examples
+    #   # Return both incoming and outgoing relationships
+    #   me.rels(:friends, :work).each {|relationship|...}
+    #
+    #   # Only return outgoing relationship of given type
+    #   me.rels(:friends).outgoing.first.end_node # => my friend node
+    #
     def rels(*type)
       RelationshipTraverser.new(self, type, :both)
     end
 
 
+    # Returns the only relationship of a given type and direction that is attached to this node, or null.
+    # This is a convenience method that is used in the commonly occuring situation where a node has exactly zero or
+    # one relationships of a given type and direction to another node.
+    # Typically this invariant is maintained by the rest of the code: if at any time more than one such relationships
+    # exist, it is a fatal error that should generate an unchecked exception. This method reflects that semantics and
+    # returns either:
+    #
+    # * nil if there are zero relationships of the given type and direction,
+    # * the relationship if there's exactly one, or
+    # * raise an exception in all other cases.
+    def rel(dir, type)
+      result = _rel(dir, type)
+      result && result.wrapper
+    end
+
+    # Same as rel but does not return a ruby wrapped object but instead returns the Java object.
+    def _rel(dir, type)
+      get_single_relationship(type_to_java(type), dir_to_java(dir))
+    end
+
+    # Returns the raw java neo4j relationship object.
+    def rels_raw(dir=:both, *types)
+      if types.size > 1
+        java_types = types.inject([]) { |result, type| result << type_to_java(type) }.to_java(:'org.neo4j.graphdb.RelationshipType')
+        get_relationships(java_types)
+      elsif types.size == 1
+        get_relationships(type_to_java(types[0], dir_to_java(dir)))
+      elsif dir == :both
+        get_relationships(dir_to_java(dir))
+      else
+        raise "illegal argument, does not accept #{dir} #{types.join(',')} - only dir=:both for any relationship types"
+      end
+    end
+
     # Check if the given relationship exists
     # Returns true if there are one or more relationships from this node to other nodes
     # with the given relationship.
@@ -57,4 +146,4 @@ module Neo4j
 
   end
 
-end
+end