neo4j 2.0.0.alpha.5-java → 2.0.0.alpha.6-java

data/lib/neo4j/rails/relationships/relationships.rb

@@ -1,103 +1,206 @@
 module Neo4j
   module Rails
-    module Relationships
-
-      def write_changed_relationships #:nodoc:
-        @_relationships.each_value do |storage|
-          storage.persist
-        end
-      end
 
-      def relationships_changed?
-        @_relationships.each_value do |storage|
-          return true if !storage.persisted?
-        end
-        false
-      end
+    # This module overrides the Neo4j::Core::Rels module so that it can handle unpersisted relationships.
+    #
+    module Relationships
+      extend ActiveSupport::Concern
 
-      def clear_relationships #:nodoc:
-        @_relationships && @_relationships.each_value{|storage| storage.remove_from_identity_map}
-        @_relationships = {}
+      included do
+        # TODO THIS DOES NOT WORK
+        alias_method :_core_rels, :rels
+        alias_method :_core_rel, :rel
+        alias_method :_core_rel?, :rel?
+        alias_method :_core_outgoing, :outgoing
+        alias_method :_core_incoming, :incoming
       end
 
-
-      def _create_or_get_storage(rel_type) #:nodoc:
-        dsl = _decl_rels_for(rel_type.to_sym)
-        @_relationships[rel_type.to_sym] ||= Storage.new(self, rel_type, dsl)
+      # Same as  {http://rdoc.info/github/andreasronge/neo4j-core/master/Neo4j/Core/Rels#outgoing-instance_method Neo4j::Core::Node#outgoing}
+      # Since the incoming method is redefined we might need the neo4j-core version of this method.
+      # @see #incoming
+      # @api public
+      def _outgoing(rel_type)
+        _core_outgoing(rel_type)
       end
 
-      def _create_or_get_storage_for_decl_rels(decl_rels) #:nodoc:
-        @_relationships[decl_rels.rel_type.to_sym] ||= Storage.new(self, decl_rels.rel_type, decl_rels)
-      end
-
-      def _storage_for(rel_type) #:nodoc:
-        @_relationships[rel_type.to_sym]
+      # Same as  {http://rdoc.info/github/andreasronge/neo4j-core/master/Neo4j/Core/Rels#incoming-instance_method Neo4j::Core::Node#incoming}
+      # Since the incoming method is redefined we might need the neo4j-core version of this method.
+      # @see #incoming
+      # @api public
+      def _incoming(rel_type)
+        _core_incomig(rel_type)
       end
 
-      # If the node is persisted and it does not have any unsaved relationship it returns a Neo4j::NodeTraverser.
-      # Otherwise it will return a NodesDSL which behaves like the Neo4j::NodeTraverser except that it does not
-      # allow to traverse both persisted and not persisted (not saved yet) relationship more then depth one.
+      # Similar to {http://rdoc.info/github/andreasronge/neo4j-core/master/Neo4j/Core/Rels#outgoing-instance_method Neo4j::Core::Node#outgoing}
+      # but allows traversing both persisted and unpersisted relationship of depth one.
+      # For deeper or more advanced traversals see #_outgoing
       #
-      # See, Neo4j::NodeRelationship#outgoing (when node is persisted) which returns a Neo4j::NodeTraverser
+      # @example create a relationship between two nodes which is not persisted
+      #  node.outgoing(:foo) << other_node
+      #
+      # @example create and persist a relationship between two nodes with given node
+      #  node.outgoing(:foo) << other_node
+      #  node.save
+      #
+      # @example create a new node with given attributes and persist the relationship
+      #  node.outgoing(:foo).create(:name => 'bla')
       #
+      # @example create a new node with given attributes and but do not  persist the relationship
+      #  node.outgoing(:foo).new(:name => 'bla')
+      #
+      # @see #rels
+      # @see #_outgoing
+      # @api public
+      # @param [String, Symbol] rel_type the relationship type we want to create or traverse
+      # @return [NodesDSL]
       def outgoing(rel_type)
         storage = _create_or_get_storage(rel_type)
         NodesDSL.new(storage, :outgoing)
       end
 
 
-      # Traverse or update an incoming relationship
+      # Similar to {http://rdoc.info/github/andreasronge/neo4j-core/master/Neo4j/Core/Rels#incoming-instance_method Neo4j::Core::Node#incoming}
+      # but allows traversing both persisted and unpersisted relationship of depth one.
       # See #outgoing
       # See, Neo4j::NodeRelationship#outgoing (when node is persisted) which returns a Neo4j::NodeTraverser
+      # @param (see #outgoing)
+      # @api public
+      # @return [NodesDSL]
       def incoming(rel_type)
         storage = _create_or_get_storage(rel_type)
         NodesDSL.new(storage, :incoming)
       end
 
-      # See Neo4j::Rels#rels.
-      #
-      # Will also allow to access unsaved relationships - like the #outgoing and #incoming method.
-      # It one argument - the relationship type.
-      #
+      # Allow to access persisted and unpersisted relationships - like the #outgoing and #incoming method.
       # To only find all the persisted relationship, node._java_node.rels
       #
-      # === Example
-      #
+      # @example
       #   node.outgoing(:foo) << node2
-      #   node.rels(:foo).outgoing #=> [node2]
+      #   node.rels(:outgoing, :foo).outgoing #=> [node2]
       #   node.rels(:foo).incoming #=> []
-      #   node.rels(:foo) #=> [node2] - incoming and outgoing
+      #   node.rels(:both) #=> [node2] - incoming and outgoing of any type
+      #
+      # @example All the relationships between me and another node of given dir & type
+      #   me.rels(:outgoing, :friends).to_other(node)
       #
-      def rels(*rel_types)
-        if rel_types.empty?
-          AllRelsDsl.new(@_relationships, _java_node)
+      # @param [:both, :incoming, :outgoing] dir the direction of the relationship
+      # @param [String, Symbol] rel_type the requested relationship types we want look for, if none it gets relationships of any type
+      # @return [RelsDSL, AllRelsDsl] an object which included the Ruby Enumerable mixin
+      # @note it can return an unpersisted relationship
+      def rels(dir=:both, rel_type=nil)
+        raise "Illegal argument, first argument must be :both, :incoming or :outgoing, got #{dir.inspect}" unless [:incoming, :outgoing, :both].include?(dir)
+        if rel_type.nil?
+          AllRelsDsl.new(@_relationships, _java_node, dir)
         else
-          storage = _create_or_get_storage(rel_types.first)
-          RelsDSL.new(storage)
+          storage = _create_or_get_storage(rel_type)
+          RelsDSL.new(storage, dir)
         end
       end
 
-      def add_outgoing_rel(rel_type, rel) #:nodoc:
-        _create_or_get_storage(rel_type).add_outgoing_rel(rel)
+      # Returns the only relationship of a given type and direction that is attached to this node, or nil.
+      # 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.
+      # @param [:both, :incoming, :outgoing] dir the direction of the relationship
+      # @param [Symbol, String] rel_type the type of relationship, see Neo4j::Core::Relationship#rel_type
+      # @return [Neo4j::Relationship, nil, Neo4j::Rails::Relationship] the Relationship or wrapper for the Relationship or nil
+      # @raise an exception if more then one relationship of given type and direction was found
+      # @note it can return an unpersisted relationship
+      def rel(dir, rel_type)
+        raise "Illegal argument, first argument must be :both, :incoming or :outgoing, got #{dir.inspect}" unless [:incoming, :outgoing, :both].include?(dir)
+        storage = _create_or_get_storage(rel_type)
+        storage.single_relationship(dir)
       end
 
-      def add_incoming_rel(rel_type, rel) #:nodoc:
-        _create_or_get_storage(rel_type).add_incoming_rel(rel)
+      # 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.
+      #
+      # @param [:both, :incoming, :outgoing] dir  optional default :both (either, :outgoing, :incoming, :both)
+      # @param [String,Symbol] rel_type the key and value to be set, default any type
+      # @return [Boolean] true if one or more relationships exists for the given type and dir otherwise false
+      def rel?(dir=:both, rel_type=nil)
+        raise "Illegal argument, first argument must be :both, :incoming or :outgoing, got #{dir.inspect}" unless [:incoming, :outgoing, :both].include?(dir)
+        storage = _create_or_get_storage(rel_type)
+        !!storage.single_relationship(dir)
       end
 
-      def rm_incoming_rel(rel_type, rel) #:nodoc:
-        _create_or_get_storage(rel_type).rm_incoming_rel(rel)
+
+      # Works like #rels method but instead returns the nodes.
+      # It does try to load a Ruby wrapper around each node
+      # @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
+      def nodes(dir, rel_type)
+        raise "Illegal argument, first argument must be :both, :incoming or :outgoing, got #{dir.inspect}" unless [:incoming, :outgoing, :both].include?(dir)
+        storage = _create_or_get_storage(rel_type)
+        NodesDSL.new(storage, dir)
       end
 
-      def rm_outgoing_rel(rel_type, rel) #:nodoc:
-        _create_or_get_storage(rel_type).rm_outgoing_rel(rel)
+      # Returns the only node of a given type and direction that is attached to this node, or nil.
+      # 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 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
+      # * throws an unchecked exception in all other cases.
+      #
+      # This method should be used only in situations with an invariant as described above. In those situations, a "state-checking" method (e.g. #rel?) is not required,
+      # because this method behaves correctly "out of the box."
+      #
+      # @param (see #rel)
+      # @see Neo4j::Core::Node#wrapper #wrapper - The method used to wrap the node in a Ruby object if the node was found
+      def node(dir, rel_type)
+        raise "Illegal argument, first argument must be :both, :incoming or :outgoing, got #{dir.inspect}" unless [:incoming, :outgoing, :both].include?(dir)
+        storage = _create_or_get_storage(rel_type)
+        storage.single_node(dir)
       end
 
-      def rm_outgoing_rel(rel_type, rel) #:nodoc:
-        _create_or_get_storage(rel_type).rm_outgoing_rel(rel)
+
+      # @private
+      def initialize_relationships
+        @_relationships = {}
+      end
+
+      # @private
+      def write_changed_relationships #:nodoc:
+        @_relationships.each_value do |storage|
+          storage.persist
+        end
       end
 
-      def add_unpersisted_incoming_rel(rel_type, rel) #:nodoc
+      # @private
+      def relationships_changed?
+        @_relationships.each_value do |storage|
+          return true if !storage.persisted?
+        end
+        false
+      end
+
+      # @private
+      def clear_relationships
+        @_relationships && @_relationships.each_value { |storage| storage.remove_from_identity_map }
+        initialize_relationships
+      end
+
+      # @private
+      def add_outgoing_rel(rel_type, rel)
+        _create_or_get_storage(rel_type).add_outgoing_rel(rel)
+      end
+
+      # @private
+      def add_incoming_rel(rel_type, rel)
+        _create_or_get_storage(rel_type).add_incoming_rel(rel)
+      end
+
+      # @private
+      def add_unpersisted_incoming_rel(rel_type, rel)
         if (storage = _create_or_get_storage(rel_type))
           # move the relationship since we are now about to store the relationship
           storage.add_unpersisted_incoming_rel(rel)
@@ -105,7 +208,8 @@ module Neo4j
         end
       end
 
-      def add_unpersisted_outgoing_rel(rel_type, rel) #:nodoc
+      # @private
+      def add_unpersisted_outgoing_rel(rel_type, rel)
         if (storage = _create_or_get_storage(rel_type))
           # move the relationship since we are now about to store the relationship
           storage.add_unpersisted_outgoing_rel(rel)
@@ -113,18 +217,42 @@ module Neo4j
         end
       end
 
-      def rm_unpersisted_outgoing_rel(rel_type, rel)  #:nodoc
+      # @private
+      def rm_unpersisted_outgoing_rel(rel_type, rel)
         if (storage = _storage_for(rel_type))
           storage.rm_unpersisted_outgoing_rel(rel)
         end
       end
 
-      def rm_unpersisted_incoming_rel(rel_type, rel)  #:nodoc
+      # @private
+      def rm_unpersisted_incoming_rel(rel_type, rel)
         if (storage = _storage_for(rel_type))
           storage.rm_unpersisted_incoming_rel(rel)
         end
       end
 
+      protected
+
+      def rm_incoming_rel(rel_type, rel) #:nodoc:
+        _create_or_get_storage(rel_type).rm_incoming_rel(rel)
+      end
+
+      def rm_outgoing_rel(rel_type, rel) #:nodoc:
+        _create_or_get_storage(rel_type).rm_outgoing_rel(rel)
+      end
+
+      def _create_or_get_storage(rel_type) #:nodoc:
+        @_relationships[rel_type.to_sym] ||= Storage.new(self, rel_type)
+      end
+
+      def _create_or_get_storage_for_decl_rels(decl_rels) #:nodoc:
+        @_relationships[decl_rels.rel_type.to_sym] ||= Storage.new(self, decl_rels.rel_type, decl_rels)
+      end
+
+      def _storage_for(rel_type) #:nodoc:
+        @_relationships[rel_type.to_sym]
+      end
+
 
     end
   end

data/lib/neo4j/rails/relationships/rels_dsl.rb

@@ -7,13 +7,14 @@ module Neo4j
       class AllRelsDsl
         include Enumerable
 
-        def initialize(rels_stores, node)
+        def initialize(rels_stores, node, dir)
           @rels_stores = rels_stores
           @node = node
+          @dir = dir
         end
 
         def each
-          @rels_stores.each_value {|storage| storage.relationships(:both).each{|r| yield r}}
+          @rels_stores.each_value {|storage| storage.relationships(@dir).each{|r| yield r}}
           @node && @node.rels.each {|r| yield r}
         end
 
@@ -29,7 +30,7 @@ module Neo4j
         # Notice, only persisted relationships will be returned.
         def to_other(other)
           raise('node.rels(...).to_other() not allowed on a node that is not persisted') unless @node
-          @node.rels.to_other(other)
+          @node._java_node.rels(@dir).to_other(other)
         end
 
         def delete_all
@@ -68,7 +69,7 @@ module Neo4j
       class RelsDSL
         include Enumerable
 
-        def initialize(storage, dir=:both)
+        def initialize(storage, dir)
           @storage = storage
           @dir = dir
         end
@@ -76,16 +77,16 @@ module Neo4j
 
         # Same as Neo4j::Rails::Relationships::NodesDSL#build except that you specify the properties of the
         # relationships and it returns a relationship
-        def build(attrs = {})
-          node = @storage.build(attrs)
-          @storage.create_relationship_to(node, @dir)
+        def build(rels_attrs = nil, node_attr = nil)
+          node = @storage.build(node_attr)
+          @storage.create_relationship_to(node, @dir, rels_attrs)
         end
 
         # Same as Neo4j::Rails::Relationships::NodesDSL#create except that you specify the properties of the
         # relationships and it returns a relationship
-        def create(attrs = {})
-          node = @storage.create(attrs)
-          rel = @storage.create_relationship_to(node, @dir)
+        def create(rels_attrs = {}, node_attr = nil)
+          node = @storage.build(node_attr)
+          rel = @storage.create_relationship_to(node, @dir, rels_attrs)
           node.save
           rel
         end
@@ -94,7 +95,7 @@ module Neo4j
         # Returns an Enumerable. If the node is not persisted it will raise an error.
         # Notice, only persisted relationships will be returned.
         def to_other(other)
-          @storage.to_other(other)
+          @storage.to_other(@dir, other)
         end
 
         # Connects this node with an already existing other node with a new relationship.
@@ -109,8 +110,8 @@ module Neo4j
 
         # Same as Neo4j::Rails::Relationships::NodesDSL#create! except that you specify the properties of the
         # relationships and it returns a relationship
-        def create!(attrs)
-          node = @storage.create(attrs)
+        def create!(rels_attrs)
+          node = @storage.create(rels_attrs)
           rel = @storage.create_relationship_to(node, @dir)
           node.save!
           rel
@@ -118,7 +119,7 @@ module Neo4j
 
         # Specifies that we want outgoing (undeclared) relationships.
         #
-        # ==== Example
+        # @example
         #   class Thing < Neo4j::Rails::Model
         #   end
         #
@@ -141,13 +142,13 @@ module Neo4j
         end
 
         # Simply counts all relationships
-        def size
-          @storage.size(@dir)
+        def count
+          @storage.count(@dir)
         end
 
         # True if no relationship
         def empty?
-          size == 0
+          !@storage.relationships?(@dir)
         end
 
         # Destroys all relationships object. Will not destroy the nodes.

data/lib/neo4j/rails/relationships/storage.rb

@@ -4,10 +4,9 @@ module Neo4j
 
       # Holds the relationships in memory but also allows read access to persisted relationships
       class Storage #:nodoc:
-        include Neo4j::ToJava
         attr_reader :dsl, :node, :rel_type
 
-        def initialize(node, rel_type, dsl)
+        def initialize(node, rel_type, dsl=nil)
           @rel_type = rel_type.to_sym
           @node = node
           @rel_class = (dsl && dsl.relationship_class) || Neo4j::Rails::Relationship
@@ -37,17 +36,20 @@ module Neo4j
           @unpersisted_incoming_rels = nil
         end
 
-        def size(dir)
+        def count(dir)
           counter = 0
           # count persisted relationship
-          @node._java_node && @node._java_node.getRelationships(java_rel_type, dir_to_java(dir)).each { |*| counter += 1 }
+          @node._rels(dir, @rel_type).each { |*| counter += 1 } if @node.persisted?
           # count relationship which has not yet been persisted
           counter += relationships(dir).size
           counter
         end
 
-        def to_other(other)
-          (@node._java_node) ? @node._java_node.rels(@rel_type).to_other(other) : raise('node.rels(...).to_other() not allowed on a node that is not persisted')
+        def to_other(dir, other)
+          raise('node.rels(...).to_other() not allowed on a node that is not persisted') if @node.new_record?
+          all_relationships(dir).find_all do |rel|
+            rel._other_node(@node) == other
+          end
         end
 
         def build(attrs)
@@ -69,10 +71,6 @@ module Neo4j
           end
         end
 
-        def java_rel_type
-          type_to_java(rel_type)
-        end
-
         def each_rel(dir, &block) #:nodoc:
           relationships(dir).each { |rel| block.call rel }
           if @node.persisted?
@@ -83,7 +81,7 @@ module Neo4j
 
         def cache_relationships(dir)
           @persisted_relationships[dir] ||= []
-          node._java_node.getRelationships(java_rel_type, dir_to_java(dir)).each do |rel|
+          node._rels(dir, @rel_type).each do |rel|
             @persisted_relationships[dir] << rel.wrapper
           end
         end
@@ -91,8 +89,8 @@ module Neo4j
         def cache_persisted_nodes_and_relationships(dir)
           @persisted_related_nodes[dir] ||= []
           @persisted_node_to_relationships[dir] ||= {}
-          @node._java_node.getRelationships(java_rel_type, dir_to_java(dir)).each do |rel|
-            end_node = rel.getOtherNode(@node._java_node).wrapper
+          @node._rels(dir, @rel_type).each do |rel|
+            end_node = rel._other_node(@node._java_node).wrapper
             @persisted_related_nodes[dir] << end_node
             @persisted_node_to_relationships[dir][end_node]=rel
           end
@@ -116,10 +114,14 @@ module Neo4j
           end
         end
 
+        def relationships?(dir)
+          !!relationships(dir).first || (@node.persisted? && @node._rels(dir, @rel_type).first)
+        end
+
         def single_relationship(dir, raw = false)
           rel = relationships(dir).first
           if rel.nil? && @node.persisted?
-            java_rel = @node._java_node.getSingleRelationship(java_rel_type, dir_to_java(dir))
+            java_rel = @node._rel(dir, @rel_type)
             raw ? java_rel : java_rel && java_rel.wrapper
           else
             rel
@@ -148,11 +150,11 @@ module Neo4j
           end
         end
 
-        def create_relationship_to(to, dir)
+        def create_relationship_to(to, dir, attributes=nil)
           if dir == :outgoing
-            @rel_class.new(@rel_type, @node, to, self)
+            @rel_class.new(@rel_type, @node, to, attributes)
           else
-            @rel_class.new(@rel_type, to, @node, self)
+            @rel_class.new(@rel_type, to, @node, attributes)
           end
         end