neo4j 1.0.0.beta.17 → 1.0.0.beta.18

data/lib/neo4j/index/lucene_query.rb

@@ -0,0 +1,156 @@
+module Neo4j
+  module Index
+    # == LuceneQuery
+    #
+    # This object is returned when you call the #find method on the Node, Relationship.
+    # The actual query is not executed until the first item is requested.
+    #
+    # You can perform a query in many different ways:
+    #
+    # ==== By Hash
+    #
+    # Example:
+    #  Person.find(:name => 'foo', :age => 3)
+    #
+    # ==== By Range
+    #
+    # Example:
+    #  Person.find(:age).between(15,35)
+    #
+    # ==== By Lucene Query Syntax
+    #
+    # Example
+    #  Car.find('wheels:"4" AND colour: "blue")
+    #
+    # For more information about the syntax see http://lucene.apache.org/java/3_0_2/queryparsersyntax.html
+    #
+    # ==== By Compound Queries
+    #
+    # You can combine several queries by <tt>AND</tt>ing those together.
+    #
+    # Example:
+    #   Vehicle.find(:weight).between(5.0, 100000.0).and(:name).between('a', 'd')
+    #
+    # === See Also
+    # * Neo4j::Index::Indexer#index
+    # * Neo4j::Index::Indexer#find - which returns an LuceneQuery
+    #
+    class LuceneQuery
+      include Enumerable
+      attr_accessor :left_and_query, :left_or_query
+      
+      def initialize(index, decl_props, query)
+        @index = index
+        @query = query
+        @decl_props = decl_props
+      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 between(lower, upper)
+        raise "Expected a symbol. Syntax for range queries example: index(:weight).between(a,b)" unless Symbol === @query
+        raise "Can't only do range queries on Neo4j::NodeMixin, Neo4j::Model, Neo4j::RelationshipMixin" unless @decl_props
+        type = @decl_props[@query] && @decl_props[@query][:type] 
+        raise "Missing type declaration of property #{@query}. E.g. property :#{@query}, :type => Float; index :#{@query}" unless type
+        if type != String
+          raise "find(#{@query}).between(#{lower}, #{upper}) to allowed since #{lower} is not a Float or Fixnum" if lower === Float or lower === Fixnum
+          raise "find(#{@query}).between(#{lower}, #{upper}) to allowed since #{upper} is not a Float or Fixnum" if upper === Float or upper === Fixnum
+          @query = org.apache.lucene.search.NumericRangeQuery.new_double_range(@query.to_s, lower, upper, false, false)
+        else
+          raise "find(#{@query}).between(#{lower}, #{upper}) to allowed since #{lower} is not a String" if lower === String
+          raise "find(#{@query}).between(#{lower}, #{upper}) to allowed since #{upper} is not a String" if upper === String
+          @query = org.apache.lucene.search.TermRangeQuery.new(@query.to_s, lower, upper, false, false)
+        end
+        self
+      end
+
+      def and(query2)
+        new_query = LuceneQuery.new(@index, @decl_props, query2)
+        new_query.left_and_query = self
+        new_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 build_and_query(query)
+        left_query = @left_and_query.build_query
+        and_query  = org.apache.lucene.search.BooleanQuery.new
+        and_query.add(left_query, org.apache.lucene.search.BooleanClause::Occur::MUST)
+        and_query.add(query, org.apache.lucene.search.BooleanClause::Occur::MUST)
+        and_query
+      end
+
+      def build_sort_query(query)
+        java_sort_fields = @order.keys.inject([]) do |memo, field|
+          decl_type = @decl_props && @decl_props[field] && @decl_props[field][:type]
+          type      = case
+                        when Float == decl_type
+                          org.apache.lucene.search.SortField::DOUBLE
+                        when Fixnum == decl_type
+                          org.apache.lucene.search.SortField::LONG
+                        else
+                          org.apache.lucene.search.SortField::STRING
+                      end
+          memo << org.apache.lucene.search.SortField.new(field.to_s, type, @order[field])
+        end
+        sort             = org.apache.lucene.search.Sort.new(*java_sort_fields)
+        org.neo4j.index.impl.lucene.QueryContext.new(query).sort(sort)
+      end
+
+      def build_hash_query(query)
+        and_query  = org.apache.lucene.search.BooleanQuery.new
+
+        query.each_pair do |key, value|
+          raise "Only String values valid in find(hash) got :#{key} => #{value} which is not a String" if !value.is_a?(String) && @decl_props[key] && @decl_props[key][:type] != String
+          term = org.apache.lucene.index.Term.new(key.to_s, value.to_s)
+          term_query = org.apache.lucene.search.TermQuery.new(term)
+          and_query.add(term_query, org.apache.lucene.search.BooleanClause::Occur::MUST)
+        end
+        and_query
+      end
+      
+      def build_query
+        query = @query
+        query = build_hash_query(query) if Hash === query
+        query = build_and_query(query) if @left_and_query
+        query = build_sort_query(query) if @order
+        query
+      end
+
+      def perform_query
+        @index.query(build_query)
+      end
+    end
+  end
+end
+

data/lib/neo4j/load.rb

@@ -1,6 +1,7 @@
 module Neo4j
 
-  # Module used to load both Nodes and Relationship from the database
+  # === Mixin responsible for loading Ruby wrappers for Neo4j Nodes and Relationship.
+  #
   module Load
     def wrapper(node) # :nodoc:
       return node unless node.property?(:_classname)
@@ -11,7 +12,7 @@ module Neo4j
       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.
+    # Checks if the given entity (node/relationship) or entity id (#neo_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

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

@@ -6,7 +6,23 @@ module Neo4j::Mapping
       # The generated accessor is a simple wrapper around the #[] and
       # #[]= operators.
       #
+      # ==== Types
       # If a property is set to nil the property will be removed.
+      # A property can be of any primitive type (Boolean, String, Fixnum, Float) and does not
+      # even have to be the same.
+      #
+      # Example:
+      #   class Foo
+      #     include Neo4j::NodeMixin
+      #     property :age
+      #   end
+      #
+      # Example:
+      #   foo = Foo.new
+      #   foo.age = "hej" # first set it to string
+      #   foo.age = 42  # change it to a Fixnum
+      #
+      # However, you can specify an type for the index, see Neo4j::Index::Indexer#index
       #
       # ==== Example
       #   class Baaz; end

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

@@ -6,6 +6,7 @@ module Neo4j::Mapping
 
       # Specifies a relationship between two node classes.
       # Generates assignment and accessor methods for the given relationship.
+      # Both incoming and outgoing relationships can be declared, see Neo4j::Mapping::DeclRelationshipDsl
       #
       # ==== Example
       #
@@ -43,6 +44,7 @@ module Neo4j::Mapping
       # Specifies a relationship between two node classes.
       # Generates assignment and accessor methods for the given relationship
       # Old relationship is deleted when a new relationship is assigned.
+      # Both incoming and outgoing relationships can be declared, see Neo4j::Mapping::DeclRelationshipDsl
       #
       # ==== Example
       #
@@ -58,7 +60,7 @@ module Neo4j::Mapping
       #
       # ==== Returns
       #
-      # Neo4j::Relationships::DeclRelationshipDsl
+      # Neo4j::Mapping::DeclRelationshipDsl
       #
       def has_one(rel_type, params = {})
         clazz = self

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

@@ -1,5 +1,6 @@
 module Neo4j::Mapping
   module ClassMethods
+    # Used to hold information about which relationships and properties has been declared.
     module Root
       #attr_reader :_decl_rels, :_decl_props
 
@@ -13,11 +14,13 @@ module Neo4j::Mapping
       end
 
 
+      # a hash of all relationships which has been declared with a has_n or has_one using Neo4j::Mapping::ClassMethods::Relationship
       def _decl_rels
         @@_all_decl_rels[self] ||= {}
         @_decl_props = @@_all_decl_rels[self]
       end
 
+      # a hash of all properties which has been declared with <tt>property</tt> using the Neo4j::Mapping::ClassMethods::Property
       def _decl_props
         @@_all_decl_props[self] ||= {}
         @_decl_props = @@_all_decl_props[self]

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

@@ -1,39 +1,43 @@
 module Neo4j::Mapping
   module ClassMethods
+    # Holds all defined rules and trigger them when an event is received.
+    #
+    # See Rule
+    # 
     class Rules
       class << self
         def add(clazz, field, props, &block)
-          clazz = clazz.to_s
-          @rules ||= {}
+          clazz                   = clazz.to_s
+          @rules                  ||= {}
           # was there no ruls for this class AND is neo4j running ?
           if !@rules.include?(clazz) && Neo4j.running?
             # maybe Neo4j was started first and the rules was added later. Create rule nodes now
             create_rule_node_for(clazz)
           end
-          @rules[clazz] ||= {}
-          filter = block.nil? ? Proc.new { |*| true } : block
-          @rules[clazz][field] = filter
-          @triggers ||= {}
-          @triggers[clazz] ||= {}
-          trigger = props[:trigger].nil? ? [] : props[:trigger]
+          @rules[clazz]           ||= {}
+          filter                  = block.nil? ? Proc.new { |*| true } : block
+          @rules[clazz][field]    = filter
+          @triggers               ||= {}
+          @triggers[clazz]        ||= {}
+          trigger                 = props[:trigger].nil? ? [] : props[:trigger]
           @triggers[clazz][field] = trigger.respond_to?(:each) ? trigger : [trigger]
         end
-	
-	def inherit(parent_class, subclass)
-	  # copy all the rules
-	  @rules[parent_class.to_s].each_pair do |field, filter|
-	    subclass.rule field, &filter
-	  end if @rules[parent_class.to_s]
-	end
+
+        def inherit(parent_class, subclass)
+          # copy all the rules
+          @rules[parent_class.to_s].each_pair do |field, filter|
+            subclass.rule field, &filter
+          end if @rules[parent_class.to_s]
+        end
 
         def trigger_other_rules(node)
-	  clazz = node[:_classname]
-	  @rules[clazz].keys.each do |field|
-	    rel_types = @triggers[clazz][field]
-	    rel_types.each do |rel_type|
-	      node.incoming(rel_type).each { |n| n.trigger_rules }
-	    end
-	  end
+          clazz = node[:_classname]
+          @rules[clazz].keys.each do |field|
+            rel_types = @triggers[clazz][field]
+            rel_types.each do |rel_type|
+              node.incoming(rel_type).each { |n| n.trigger_rules }
+            end
+          end
         end
 
         def fields_for(clazz)
@@ -70,17 +74,17 @@ module Neo4j::Mapping
         end
 
         def rule_for(clazz)
-	  if Neo4j.ref_node.rel?(clazz)
-	    Neo4j.ref_node._rel(:outgoing, clazz)._end_node
-	  else
-	    # this should be called if the rule node gets deleted
-	    create_rule_node_for(clazz)
-	  end
+          if Neo4j.ref_node.rel?(clazz)
+            Neo4j.ref_node._rel(:outgoing, clazz)._end_node
+          else
+            # this should be called if the rule node gets deleted
+            create_rule_node_for(clazz)
+          end
         end
 
 
         def on_relationship_created(rel, *)
-	  trigger_start_node = trigger?(rel._start_node)
+          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
@@ -89,52 +93,52 @@ module Neo4j::Mapping
 
 
         def on_property_changed(node, *)
-	  trigger_rules(node) if trigger?(node)
+          trigger_rules(node) if trigger?(node)
         end
 
         def trigger_rules(node)
           trigger_rules_for_class(node, node[:_classname])
-	  trigger_other_rules(node)
+          trigger_other_rules(node)
         end
-	
-	def trigger_rules_for_class(node, clazz)
-	  return if @rules[clazz].nil?
+
+        def trigger_rules_for_class(node, clazz)
+          return if @rules[clazz].nil?
 
           agg_node = rule_for(clazz)
           @rules[clazz].each_pair do |field, rule|
             if run_rule(rule, node)
               # is this node already included ?
-	      unless connected?(field, agg_node, node)
+              unless connected?(field, agg_node, node)
                 agg_node.outgoing(field) << node
               end
             else
               # remove old ?
-	      break_connection(field, agg_node, node)
+              break_connection(field, agg_node, node)
             end
           end
-	  
-	  # recursively add relationships for all the parent classes with rules that also pass for this node
-	  if clazz = eval("#{clazz}.superclass")
-	    trigger_rules_for_class(node, clazz.to_s)
-	  end
-	end
-	
-	# work out if two nodes are connected by a particular relationship
-	# uses the end_node to start with because it's more likely to have less relationships to go through
-	# (just the number of superclasses it has really)
-	def connected?(relationship, start_node, end_node)
-	  end_node.incoming(relationship).each do |n|
-	    return true if n == start_node
-	  end
-	  false
-	end
-	
-	# sever a direct one-to-one relationship if it exists
-	def break_connection(relationship, start_node, end_node)
-	  end_node.rels(relationship).incoming.each do |r|
-	    return r.del if r.start_node == start_node
-	  end
-	end
+
+          # recursively add relationships for all the parent classes with rules that also pass for this node
+          if clazz = eval("#{clazz}.superclass")
+            trigger_rules_for_class(node, clazz.to_s)
+          end
+        end
+
+        # work out if two nodes are connected by a particular relationship
+        # uses the end_node to start with because it's more likely to have less relationships to go through
+        # (just the number of superclasses it has really)
+        def connected?(relationship, start_node, end_node)
+          end_node.incoming(relationship).each do |n|
+            return true if n == start_node
+          end
+          false
+        end
+
+        # sever a direct one-to-one relationship if it exists
+        def break_connection(relationship, start_node, end_node)
+          end_node.rels(relationship).incoming.each do |r|
+            return r.del if r.start_node == start_node
+          end
+        end
 
         def run_rule(rule, node)
           if rule.arity != 1
@@ -147,6 +151,75 @@ module Neo4j::Mapping
     end
 
 
+    # Allows you to group nodes by providing a rule.
+    #
+    # === Example, finding all nodes of a certain class
+    # Just add a rule without a code block, then all nodes of that class will be grouped under the given key (<tt>all</tt>
+    # for the example below).
+    #
+    #   class Person
+    #     include Neo4j::NodeMixin
+    #     rule :all
+    #   end
+    #
+    # Then you can get all the nodes of type Person (and siblings) by
+    #   Person.all.each {|x| ...}
+    #
+    # === Example, finding all nodes with a given condition on a property
+    #
+    #   class Person
+    #     include Neo4j::NodeMixin
+    #     property :age
+    #     rule(:old) { age > 10 }
+    #   end
+    #
+    #  Now we can find all nodes with a property <tt>age</tt> above 10.
+    #
+    # === Chain Rules
+    #
+    #   class NewsStory
+    #     include Neo4j::NodeMixin
+    #     has_n :readers
+    #     rule(:featured) { |node| node[:featured] == true }
+    #     rule(:young_readers) { !readers.find{|user| !user.young?}}
+    #   end
+    #
+    # You can combine two rules. Let say you want to find all stories which are featured and has young readers:
+    #   NewsStory.featured.young_readers.each {...}
+    #
+    # === Trigger Other Rules
+    # You can let one rule trigger another rule.
+    # Let say you have readers of some magazine and want to know if the magazine has old or young readers.
+    # So when a reader change from young to old you want to trigger all the magazine that he reads (a but stupid example)
+    #
+    # Example
+    #   class Reader
+    #     include Neo4j::NodeMixin
+    #     property :age
+    #     rule(:young, :trigger => :readers) { age < 15 }
+    #   end
+    #
+    #   class NewsStory
+    #     include Neo4j::NodeMixin
+    #     has_n :readers
+    #     rule(:young_readers) { !readers.find{|user| !user.young?}}
+    #   end
+    #
+    # === Performance Considerations
+    # If you have many rules and many updates this can be a bit slow.
+    # In order to speed it up somewhat you can use the raw java node object instead by providing an argument in your block.
+    #
+    # Example:
+    #
+    #   class Person
+    #     include Neo4j::NodeMixin
+    #     property :age
+    #     rule(:old) {|node| node[:age] > 10 }
+    #   end
+    #
+    # === Thread Safe ?
+    # Not sure...
+    #
     module Rule
 
       # Creates an rule node attached to the Neo4j.ref_node
@@ -168,13 +241,13 @@ module Neo4j::Mapping
       #   p1.young?    # => true
       #
       def rule(name, props = {}, &block)
-	singelton = class << self;
+        singelton = class << self;
           self;
         end
-	
+
         # define class methods
         singelton.send(:define_method, name) do
-          agg_node = Rules.rule_for(self)
+          agg_node  = Rules.rule_for(self)
           raise "no rule node for #{name}  on #{self}" if agg_node.nil?
           traversal = agg_node.outgoing(name) # TODO possible to cache this object
           Rules.fields_for(self).each do |filter_name|
@@ -188,15 +261,15 @@ module Neo4j::Mapping
         # define instance methods
         self.send(:define_method, "#{name}?") do
           instance_eval &block
-	end
+        end
 
         Rules.add(self, name, props, &block)
       end
-      
+
       def inherit_rules_from(clazz)
-	Rules.inherit(clazz, self)
+        Rules.inherit(clazz, self)
       end
-      
+
       # This is typically used for RSpecs to clean up rule nodes created by the #rule method.
       # It also remove the given class method.
       def delete_rules
@@ -209,6 +282,8 @@ module Neo4j::Mapping
         Rules.delete(self)
       end
 
+      # Force to trigger the rules.
+      # You don't normally need that since it will be done automatically.
       def trigger_rules(node)
         Rules.trigger_rules(node)
       end