neo4j 1.1.1-java → 1.1.2-java

data/CHANGELOG

@@ -1,4 +1,9 @@
-== 1.1.1 / 2011-06-26
+== 1.1.2 / 2011-06-08
+* Added configuration option 'enable_rules' to disable the _all relationships and custom rules [#176]
+* Added a #node method on the Neo4j::Node and Neo4j::NodeMixin. Works like the #rel method but returns the node instead. [#174]
+* Simplify creating relationship between two existing nodes [#175]
+
+== 1.1.1 / 2011-05-26
 * Made neo4j compatible with rails 3.1.0.rc1 [#170]
 * Fix for neo4j-devise [#171]
 * BUG: Neo4j::GraphAlgo shortest path does raise exception if two nodes are not connected [#172]

data/config/neo4j/config.yml

@@ -3,6 +3,10 @@
 # The folder location of the neo4j and lucene database
 storage_path: db
 
+# If enable neo4j.rb will create _all relationship to all instances inheriting from Neo4j::Rails::Model
+# If disabled all custom rules will also be unavailable.
+enable_rules: true
+
 # When using the Neo4j::Model you can let neo4j automatically set timestamps when updating/creating nodes.
 # If set to true neo4j.rb automatically timestamps create and update operations if the model has properties named created_at/created_on or updated_at/updated_on
 # (similar to ActiveRecord).

data/lib/neo4j/config.rb

@@ -13,6 +13,7 @@ module Neo4j
   # <tt>:storage_path</tt>::   default <tt>tmp/neo4j</tt> where the database is stored
   # <tt>:timestamps</tt>::     default <tt>true</tt> for Rails Neo4j::Model - if timestamps should be used when saving the model
   # <tt>:lucene</tt>::         default hash keys: <tt>:fulltext</tt>, <tt>:exact</tt> configuration how the lucene index is stored
+  # <tt>:enable_rules</tt>::   default true, if false the _all relationship to all instances will not be created and custom rules will not be available.
   #
   class Config
     # This code is copied from merb-core/config.rb.

data/lib/neo4j/node_mixin/node_mixin.rb

@@ -43,7 +43,7 @@ module Neo4j
 
     include Neo4j::Rule::Functions
 
-    delegate :[]=, :[], :property?, :props, :attributes, :update, :neo_id, :id, :rels, :rel?, :to_param, :getId,
+    delegate :[]=, :[], :property?, :props, :attributes, :update, :neo_id, :id, :rels, :rel?, :node, :to_param, :getId,
              :rel, :del, :list?, :print, :print_sub, :outgoing, :incoming, :both, :expand, :get_property, :set_property,
              :equal?, :eql?, :==, :exist?, :getRelationships, :getSingleRelationship, :_rels, :rel, :wrapped_entity,
              :to => :@_java_node, :allow_nil => true

data/lib/neo4j/rails/model.rb

@@ -1,5 +1,25 @@
 module Neo4j
   module Rails
+
+    # Includes the Neo4j::NodeMixin and adds ActiveRecord/Model like behaviour.
+    # That means for example that you don't have to care about transactions since they will be
+    # automatically be created when needed.
+    #
+    # ==== Traversals
+    # This class only expose a limited set of traversals.
+    # If you want to access the raw java node to do traversals use the _java_node.
+    #
+    #   class Person < Neo4j::Rails::Model
+    #   end
+    #
+    #   person = Person.find(...)
+    #   person._java_node.outgoing(:foo).depth(:all)...
+    #
+    # ==== has_n and has_one
+    #
+    # The has_n and has_one relationship accessors returns objects of type Neo4j::Rails::Relationships::RelsDSL
+    # and Neo4j::Rails::Relationships::NodesDSL which behaves more like the Active Record relationships.
+    #
     class Model
       include Neo4j::NodeMixin
 

data/lib/neo4j/rails/relationship.rb

@@ -1,8 +1,20 @@
 module Neo4j
   module Rails
+
+    # Includes the Neo4j::RelationshipMixin and adds ActiveRecord/Model like behaviour.
+    # That means for example that you don't have to care about transactions since they will be
+    # automatically be created when needed.
+    #
+    # By default all relationships created by hte Neo4j::Rails::Model will be of this type unless it is specified by
+    # an has_n(...).relationship(relationship_class),
+    #
+    # Notice that this class works like any ActiveModel compliant object with callbacks and validations.
+    # It also implement timestamps (like active record), just add a updated_at or created_at attribute.
+    #
     class Relationship
       include Neo4j::RelationshipMixin
 
+      # The relationship type
       attr_reader :type
 
       index :_classname

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

@@ -2,7 +2,12 @@ module Neo4j
   module Rails
     module Relationships
 
-      class NodesDSL #:nodoc:
+      # Instances of this class is returned from the #outgoing, #incoming and generated accessor methods:
+      # has_n and has_one.
+      # Notice that this class includes the Ruby Enumerable mixin.
+      # If you want to full traversal api use the wrapped java node instead (some_node._java_node.outgoing(...)).
+      #
+      class NodesDSL
         include Enumerable
 
         def initialize(storage, dir)
@@ -10,36 +15,56 @@ module Neo4j
           @dir = dir
         end
 
+        # Creates a new node given the specified attributes and connect it with a relationship.
+        # The new node and relationship will not be saved.
+        # Both the relationship class and the node class can be specified with the has_n and has_one.
+        #
+        # ==== Example
+        #
+        #   class Person < Neo4j::Rails::Model
+        #      has_n(:friends).to(Person).relationship(Friend)
+        #      has_n(:knows)
+        #   end
+        #
+        #   Person.friends.build(:name => 'kalle')  # creates a Person and Friends class.
+        #   Person.knows.build(:name => 'kalle') # creates a Neo4j::Rails::Model and Neo4j::Rails::Relationship class
+        #
         def build(attrs)
           self << (node = @storage.build(attrs))
           node
         end
 
+        # Same as #build except that the relationship and node are saved.
         def create(attrs)
           self << (node = @storage.create(attrs))
           node.save
           node
         end
 
+        # Same as #create but will raise an exception if an error (like validation) occurs.
         def create!(attrs)
           self << (node = @storage.create(attrs))
           node.save!
           node
         end
 
+        # Adds a new node to the relationship
         def <<(other)
           @storage.create_relationship_to(other, @dir)
           self
         end
 
+        # Specifies the depth of the traversal
         def depth(d)
           adapt_to_traverser.depth(d)
         end
 
-        def adapt_to_traverser
+        def adapt_to_traverser # :nodoc:
           Neo4j::Traversal::Traverser.new(@storage.node, @storage.rel_type, @dir)
         end
 
+        # Returns the n:th item in the relationship.
+        # This method simply traverse all relationship and returns the n:th one.
         def [](index)
           i = 0
           each{|x| return x if i == index; i += 1}
@@ -52,6 +77,29 @@ module Neo4j
           super
         end
 
+        # Find one node in the relationship.
+        #
+        # ==== Example
+        #
+        #   class Actor < Neo4j::Rails::Model
+        #     has_n(:acted_in)
+        #   end
+        #
+        #    # find all child nodes
+        #    actor.acted_in.find(:all)
+        #
+        #    # find first child node
+        #    actor.acted_in.find(:first)
+        #
+        #    # find a child node by node
+        #    actor.acted_in.find(some_movie)
+        #
+        #    # find a child node by id" do
+        #    actor.acted_in.find(some_movie.id)
+        #
+        #    #find a child node by delegate to Enumerable#find
+        #    actor.acted_in.find{|n| n.title == 'movie_1'}
+        #
         def find(*args, &block)
           return super(*args, &block) if block
           
@@ -70,6 +118,8 @@ module Neo4j
           end          
         end
 
+        # Same as #find except that it returns an Enumerator of all nodes found.
+        #
         def all(*args)
           unless args.empty?
             enum = Enumerator.new(@storage, :each_node, @dir).find{|n| n == args.first}
@@ -78,6 +128,7 @@ module Neo4j
           end
         end
 
+        #  Returns first node in the relationship specified by the arguments or returns nil.
         def first(*args)
           if result = all(*args)
             if result.respond_to?(:collect) #if it's enumerable, get the first result
@@ -90,6 +141,8 @@ module Neo4j
           end
         end
 
+        # Destroys all nodes (!!!) and relationship in this relatationship.
+        # Notice, if you only want to destroy the relationship use the
         def destroy_all
           each {|n| n.destroy}
         end

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

@@ -1,6 +1,21 @@
 module Neo4j
   module Rails
     module Relationships
+
+      # Instances of this class is returned from the #rels, and generated accessor methods:
+      # has_n and has_one.
+      # Notice, this class is very similar to the Neo4j::Rails::Relationships::NodesDSL except that
+      # if creates, finds relationships instead of nodes.
+      #
+      # ==== Example
+      #   class Person < Neo4j::Rails::Model
+      #      has_n(:friends)
+      #   end
+      #
+      #   person = Person.find(...)
+      #   person.friends_rels  #=> returns a Neo4j::Rails::Relationships::RelsDSL
+      #   rel = person.friends_rels.create(relationship properties)
+      #
       class RelsDSL
         include Enumerable
 
@@ -10,11 +25,15 @@ module Neo4j
         end
 
 
+        # 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)
         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)
@@ -22,6 +41,18 @@ module Neo4j
           rel
         end
 
+        # Connects this node with an already existing other node with a new relationship.
+        # The relationship can optionally be given a hash of properties
+        # Does not save it.
+        # Returns the created relationship
+        def connect(other_node, relationship_properties = nil)
+          rel = @storage.create_relationship_to(other_node, @dir)
+          rel.attributes = relationship_properties if relationship_properties
+          rel
+        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)
@@ -29,11 +60,21 @@ module Neo4j
           rel
         end
 
+        # Specifies that we want outgoing (undeclared) relationships.
+        #
+        # ==== Example
+        #   class Thing < Neo4j::Rails::Model
+        #   end
+        #
+        #   t = Thing.find(...)
+        #   t.rels(:reltype).outgoing  # returns an enumerable of all outgoing relationship of type :reltype
+        #
         def outgoing
           @dir = :outgoing
           self
         end
 
+        # Returns incoming relationship See #outgoing
         def incoming
           @dir = :incoming
           self
@@ -43,22 +84,28 @@ module Neo4j
           @storage.each_rel(@dir, &block)
         end
 
+        # Simply counts all relationships
         def size
           @storage.size(@dir)
         end
 
+        # True if no relationship
         def empty?
           size == 0
         end
 
+        # Destroys all relationships object. Will not destroy the nodes.
         def destroy_all
           each {|n| n.destroy}
         end
 
+        # Delete all relationship.
         def delete_all
           each {|n| n.delete}
         end
 
+        # Same as Neo4j::Rails::Relationships::NodesDSL#find except that it searches the relationships instead of
+        # the nodes.
         def find(*args, &block)
           return super(*args, &block) if block
 
@@ -77,6 +124,8 @@ module Neo4j
             end                             
         end
 
+        # Same as Neo4j::Rails::Relationships::NodesDSL#all except that it searches the relationships instead of
+        # the nodes.
         def all(*args)
           if args.first.class == Neo4j::Rails::Relationship #arg is a relationship
             find_all{|r| r == args.first}
@@ -89,6 +138,8 @@ module Neo4j
           end
         end
 
+        # Same as Neo4j::Rails::Relationships::NodesDSL#first except that it searches the relationships instead of
+        # the nodes.
         def first(*args)
           if result = all(*args)
             if result.respond_to?(:collect) #if it's enumerable, get the first result
@@ -101,7 +152,8 @@ module Neo4j
           end
         end
 
-
+        # Same as Neo4j::Rails::Relationships::NodesDSL#[] except that it returns the n:th relationship instead
+        # of the n:th node
         def [](index)
           i = 0
           each{|x| return x if i == index; i += 1}

data/lib/neo4j/rels/rels.rb

@@ -7,6 +7,31 @@ module Neo4j
   module Rels
     include ToJava
 
+    # 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."
+    #
+    # Does return the Ruby wrapper object (if it has a '_classname' property) unlike the #_node version of this method
+    #
+    def node(dir, type)
+      n = _node(dir, type)
+      n && n.wrapper
+    end
+
+    # Same as #node but instead returns an unwrapped native java node instead
+    def _node(dir, type)
+      r = _rel(dir, type)
+      r && r._other_node(self._java_node)
+    end
+
     # Returns an enumeration of relationship objects.
     # It always returns relationship of depth one.
     #

data/lib/neo4j/rule/event_listener.rb

@@ -8,7 +8,7 @@ module Neo4j
 
         def on_relationship_created(rel, *)
           trigger_start_node = Rule.trigger?(rel._start_node)
-          trigger_end_node   = Rule.trigger?(rel._end_node)
+          trigger_end_node = Rule.trigger?(rel._end_node)
           Rule.trigger_rules(rel._start_node) if trigger_start_node
           Rule.trigger_rules(rel._end_node) if trigger_end_node
         end
@@ -24,14 +24,14 @@ module Neo4j
           return if del_rule_node
 
           # do we have prop_aggregations for this
-          clazz     = old_properties['_classname']
+          clazz = old_properties['_classname']
           rule_node = Rule.rule_node_for(clazz)
           return if rule_node.nil?
 
           id = node.getId
           rule_node.rules.each do |rule|
             next if rule.functions.nil?
-            rule_name         = rule.rule_name.to_s
+            rule_name = rule.rule_name.to_s
 
             # is the rule node deleted ?
             deleted_rule_node = data.deletedNodes.find { |n| n == rule_node.rule_node }
@@ -47,8 +47,12 @@ module Neo4j
           end
         end
 
-        def on_neo4j_started(*)
-          Rule.on_neo4j_started
+        def on_neo4j_started(db)
+          if Neo4j::Config[:enable_rules]
+            Rule.on_neo4j_started
+          else
+            db.event_handler.remove(self)
+          end
         end
       end
 

data/lib/neo4j/version.rb

@@ -1,3 +1,3 @@
 module Neo4j
-  VERSION = "1.1.1"
+  VERSION = "1.1.2"
 end

metadata

@@ -2,7 +2,7 @@
 name: neo4j
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.1.1
+  version: 1.1.2
 platform: java
 authors: 
   - Andreas Ronge
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-26 00:00:00 +02:00
+date: 2011-06-08 00:00:00 +02:00
 default_executable: 
 dependencies: 
   - !ruby/object:Gem::Dependency