neo4j-wrapper 0.0.1-java

data/lib/neo4j-wrapper/rule/class_methods.rb

@@ -0,0 +1,204 @@
+module Neo4j
+  module Wrapper
+    module Rule
+
+
+      # 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, :triggers => :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 ?
+      # Yes, since operations are performed in an transaction. However you may get a deadlock exception:
+      # @see http://docs.neo4j.org/chunked/stable/transactions-deadlocks.html Transaction Deadlock
+      #
+      module ClassMethods
+
+        # Creates an rule node attached to the Neo4j.ref_node
+        # Can be used to rule all instances of a specific Ruby class.
+        #
+        # Example of usage:
+        #   class Person
+        #     include Neo4j::NodeMixin
+        #     property :age
+        #     rule :all
+        #     rule :young { self[:age] < 10 }
+        #     rule(:old, :functions => [Sum.new[:age]) { age > 20 }
+        #   end
+        #
+        #   p1 = Person.new :age => 5
+        #   p2 = Person.new :age => 7
+        #   p3 = Person.new :age => 12
+        #   Neo4j::Transaction.finish
+        #   Person.all    # =>  [p1,p2,p3]
+        #   Person.young  # =>  [p1,p2]
+        #   p1.young?    # => true
+        #   p1.sum(old, :age) # the some of the old people's age
+        #
+        def rule(rule_name, props = {}, &block)
+          singleton = class << self;
+            self;
+          end
+
+          # define class methods
+          singleton.send(:define_method, rule_name) do
+            rule_node = Rule.rule_node_for(self)
+            rule_node.traversal(rule_name)
+          end unless respond_to?(rule_name)
+
+          # define instance methods
+          self.send(:define_method, "#{rule_name}?") do
+            instance_eval &block
+          end
+
+          rule = Rule.add(self, rule_name, props, &block)
+
+          rule.functions && rule.functions.each do |func|
+            singleton.send(:define_method, func.class.function_name) do |r_name, *args|
+              rule_node = Rule.rule_node_for(self)
+              function_id = args.empty? ? "_classname" : args[0]
+              function = rule_node.find_function(r_name, func.class.function_name, function_id)
+              function.value(rule_node.rule_node, r_name)
+            end unless respond_to?(func.class.function_name)
+          end
+        end
+
+        def ref_node_for_class
+          Neo4j.ref_node #The reference node for a type falls back to the threadlocal ref node by default.
+        end
+
+        # Assigns the reference node for a class via a supplied block.
+        # Example of usage:
+        #   class Person
+        #     include Neo4j::NodeMixin
+        #     ref_node { Neo4j.default_ref_node }
+        #   end
+        #
+        def ref_node(&block)
+          singleton = class << self;
+            self;
+          end
+          singleton.send(:define_method, :ref_node_for_class) { block.call }
+        end
+
+        def inherit_rules_from(clazz)
+          Rule.inherit(clazz, self)
+        end
+
+        # This is typically used for RSpecs to clean up rule nodes created by the #rule method.
+        # It also remove all the rule class methods.
+        def delete_rules
+          singelton = class << self;
+            self;
+          end
+          rule_node = Rule.rule_node_for(self)
+
+          rule_node.rule_names.each { |rule_name| singelton.send(:remove_method, rule_name) }
+          rule_node.rules.clear
+        end
+
+        # Force to trigger the rules.
+        # You don't normally need that since it will be done automatically.
+        # This can be useful if you need to trigger rules on already existing nodes in the database.
+        # Can also be called from an migration.
+        #
+        def trigger_rules(node, *changes)
+          Rule.trigger_rules(node, *changes)
+        end
+
+        # Returns a proc that will call add method on the given function
+        # Can be used in migration to trigger rules on already existing nodes.
+        # Parameter function_id is default to '_classname' which means that
+        # the function 'reacts' on changes on the property '_classname'.
+        # That property changes only when a node is created or deleted.
+        # Function using function_id '_classname' is typically used for counting number of nodes of a class.
+        def add_function_for(rule_name, function_name_or_class, function_id = '_classname')
+          function_for(:add, rule_name, function_name_or_class, function_id)
+        end
+
+        # See #add_function_for
+        # Calls the delete method on the function.
+        def delete_function_for(rule_name, function_name_or_class, function_id = '_classname')
+          function_for(:delete, rule_name, function_name_or_class, function_id)
+        end
+
+        # Returns a proc that calls the given method on the given function.
+        def function_for(method, rule_name, function_name_or_class, function_id = '_classname')
+          function_name = function_name_or_class.is_a?(Symbol) ? function_name_or_class : function_name_or_class.function_name
+          rule_node = Rule.rule_node_for(self)
+          rule = rule_node.find_rule(rule_name)
+          rule_node_raw = rule_node.rule_node
+
+          function = rule_node.find_function(rule_name, function_name, function_id)
+          lambda do |node|
+            new_value = node[function_id]
+            function.send(method, rule.rule_name, rule_node_raw, new_value)
+          end
+        end
+      end
+
+    end
+  end
+
+end

data/lib/neo4j-wrapper/rule/event_listener.rb

@@ -0,0 +1,66 @@
+module Neo4j
+  module Wrapper
+    module Rule
+      class EventListener
+        class << self
+          # ----------------------------------------------------------------------------------------------------------------
+          # Event handling methods
+          # ----------------------------------------------------------------------------------------------------------------
+
+          def on_relationship_created(rel, *)
+            Rule.trigger_rules(rel._start_node) if Rule.trigger?(rel._start_node)
+            Rule.trigger_rules(rel._end_node) if Rule.trigger?(rel._end_node)
+          end
+
+          def on_property_changed(node, *changes)
+            Rule.trigger_rules(node, *changes) if Rule.trigger?(node)
+          end
+
+          def on_node_deleted(node, old_properties, deleted_relationship_set, deleted_identity_map)
+            # have we deleted a rule node ?
+            del_rule_node = Rule.find_rule_node(node)
+            del_rule_node && del_rule_node.clear_rule_node
+            return if del_rule_node
+
+            # do we have prop_aggregations for this
+            clazz = old_properties['_classname']
+            rule_node = Rule.rule_node_for(clazz)
+            return if rule_node.nil?
+
+            id = node.neo_id
+            rule_node.rules.each do |rule|
+              next if rule.functions.nil? || rule.bulk_update?
+              rule_name = rule.rule_name.to_s
+
+              # is the rule node deleted ?
+              deleted_rule_node = deleted_identity_map.get(rule_node.rule_node.neo_id)
+              next if deleted_rule_node
+
+              rule.functions.each do |function|
+                next unless deleted_relationship_set.contains?(id, rule_name)
+                previous_value = old_properties[function.function_id]
+                function.delete(rule_name, rule_node.rule_node, previous_value) if previous_value
+              end if rule.functions
+            end
+          end
+
+          def classes_changed(changed_class_map)
+            changed_class_map.each_pair do |clazz, class_change|
+              Rule.bulk_trigger_rules(clazz, class_change, changed_class_map)
+            end
+          end
+
+          def on_neo4j_started(db)
+            if not Neo4j::Config[:enable_rules]
+              db.event_handler.remove(self)
+            end
+          end
+        end
+
+
+      end
+      Neo4j.unstarted_db.event_handler.add(EventListener) unless Neo4j.read_only?
+
+    end
+  end
+end

data/lib/neo4j-wrapper/rule/functions/count.rb

@@ -0,0 +1,45 @@
+module Neo4j
+  module Wrapper
+    module Rule
+      module Functions
+
+        # A function for counting number of nodes of a given class.
+        class Count < Function
+          def initialize
+            @property = '_classname'
+          end
+
+          def calculate?(changed_property)
+            true
+          end
+
+          def delete(rule_name, rule_node, _)
+            key = rule_node_property(rule_name)
+            rule_node[key] ||= 0
+            rule_node[key] -= 1
+          end
+
+          def add(rule_name, rule_node, _)
+            key = rule_node_property(rule_name)
+            rule_node[key] ||= 0
+            rule_node[key] += 1
+          end
+
+          def update(*)
+            # we are only counting, not interested in property changes
+          end
+
+          def classes_changed(rule_name, rule_node, class_change)
+            key = rule_node_property(rule_name)
+            rule_node[key] ||= 0
+            rule_node[key] += class_change.net_change
+          end
+
+          def self.function_name
+            :count
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j-wrapper/rule/functions/function.rb

@@ -0,0 +1,76 @@
+module Neo4j
+  module Wrapper
+    module Rule
+      module Functions
+
+        # The base class of rule functions.
+        #
+        # You are expected to at least implement two methods:
+        # * update :: update the rule node value of this function
+        # * function_name :: the name of this function, the name of the generated method - A class method !
+        #
+        class Function
+
+          # Initialize the the function with a property which is usually the same as the function identity.
+          # See the #calculate? method how this property is used.
+          #
+          def initialize(property)
+            @property = property.to_s
+          end
+
+          def to_s
+            "Function #{self.class.function_name} function_id: #{function_id}"
+          end
+
+          # Decides if the function should be called are not
+          #
+          def calculate?(changed_property)
+            @property == changed_property
+          end
+
+
+          # The identity of the function.
+          # Used to identify function.
+          #
+          # ==== Example
+          #   Person.sum(:young, :age)
+          #
+          # In the example above the property :age is the used to identify which function will be called
+          # since there could be several sum method. In the example we want use the sum method that uses the :age property.
+          #
+          def function_id
+            @property
+          end
+
+          # The value of the rule
+          def value(rule_node, rule_name)
+            key = rule_node_property(rule_name)
+            rule_node[key] || 0
+          end
+
+          # Called when a node is removed from a rule group
+          # Default is calling update method which is expected to be implemented in a subclass
+          def delete(rule_name, rule_node, old_value)
+            update(rule_name, rule_node, old_value, nil)
+          end
+
+          # Called when a node is added to a rule group
+          # Default is calling update method which is expected to be implemented in a subclass
+          def add(rule_name, rule_node, new_value)
+            update(rule_name, rule_node, nil, new_value)
+          end
+
+          # the name of the property that holds the value of the function
+          def rule_node_property(rule_name)
+            self.class.rule_node_property(self.class.function_name, rule_name, @property)
+          end
+
+          def self.rule_node_property(function_name, rule_name, prop)
+            "_#{function_name}_#{rule_name}_#{prop}"
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/neo4j-wrapper/rule/functions/sum.rb

@@ -0,0 +1,31 @@
+module Neo4j
+  module Wrapper
+    module Rule
+      module Functions
+
+        class Sum < Function
+          # Updates the function's value.
+          # Called after the transactions commits and a property has been changed on a node.
+          #
+          # ==== Arguments
+          # * rule_name :: the name of the rule group
+          # * rule_node :: the node which contains the value of this function
+          # * old_value new value :: the changed value of the property (when the transaction commits)
+          def update(rule_name, rule_node, old_value, new_value)
+            key = rule_node_property(rule_name)
+            rule_node[key] ||= 0
+            old_value ||= 0
+            new_value ||= 0
+            rule_node[key] += new_value - old_value
+          end
+
+          def self.function_name
+            :sum
+          end
+        end
+
+
+      end
+    end
+  end
+end

data/lib/neo4j-wrapper/rule/instance_methods.rb

@@ -0,0 +1,16 @@
+module Neo4j
+  module Wrapper
+    module Rule
+      module InstanceMethods
+        # Trigger rules.
+        # You don't normally need to call this method (except in Migration) since
+        # it will be triggered automatically by the Neo4j::Wrapper::Rule::Rule
+        # @see Neo4j::Wrapper::Rule::ClassMethods
+        def trigger_rules
+          self.class.trigger_rules(self)
+        end
+      end
+    end
+  end
+
+end

data/lib/neo4j-wrapper/rule/neo4j_core_ext/traverser.rb

@@ -0,0 +1,29 @@
+module Neo4j
+  module Core
+    module Traversal
+      # Extends the Neo4j::Core Traverser in order to add rule traversal methods.
+      class Traverser
+        def filter_method(name, &proc)
+          # add method name
+          singelton = class << self;
+            self;
+          end
+          singelton.send(:define_method, name) { filter &proc }
+          self
+        end
+
+        def functions_method(func, rule_node, rule_name)
+          singelton = class << self;
+            self;
+          end
+          singelton.send(:define_method, func.class.function_name) do |*args|
+            function_id = args.empty? ? "_classname" : args[0]
+            function = rule_node.find_function(rule_name, func.class.function_name, function_id)
+            function.value(rule_node.rule_node, rule_name)
+          end
+          self
+        end
+      end
+    end
+  end
+end

data/lib/neo4j-wrapper/rule/rule.rb

@@ -0,0 +1,134 @@
+module Neo4j
+  module Wrapper
+    module Rule
+
+
+      # Holds all defined rules added by the Neo4j::Rule::ClassMethods#rule method.
+      #
+      # @see Neo4j::Wrapper::Rule::ClassMethods
+      class Rule
+
+        attr_reader :rule_name, :filter, :triggers, :functions
+
+        def initialize(rule_name, props, &block)
+          @rule_name = rule_name
+          @triggers = props[:triggers]
+          @functions = props[:functions]
+          @triggers = [@triggers] if @triggers && !@triggers.respond_to?(:each)
+          @functions = [@functions] if @functions && !@functions.respond_to?(:each)
+          @filter = block
+          @bulk_update = !@functions.nil? && @functions.size == 1 && @functions.first.class.function_name == :count && @filter.nil?
+        end
+
+        def to_s
+          "Rule #{rule_name} props=#{props.inspect}"
+        end
+
+        def find_function(function_name, function_id)
+          function_id = function_id.to_s
+          @functions && @functions.find { |f| f.function_id == function_id && f.class.function_name == function_name }
+        end
+
+        # Reconstruct the properties given when created this rule
+        # Needed when inheriting a rule and we want to duplicate a rule
+        def props
+          props = {}
+          props[:triggers] = @triggers if @triggers
+          props[:functions] = @functions if @functions
+          props
+        end
+
+        def functions_for(property)
+          @functions && @functions.find_all { |f| f.calculate?(property) }
+        end
+
+        def execute_filter(node)
+          if @filter.nil?
+            true
+          elsif @filter.arity != 1
+            node.wrapper.instance_eval(&@filter)
+          else
+            @filter.call(node)
+          end
+        end
+
+        def bulk_update?
+          @bulk_update
+        end
+
+        # ------------------------------------------------------------------------------------------------------------------
+        # Class Methods
+        # ------------------------------------------------------------------------------------------------------------------
+
+        @rule_nodes = {}
+
+        class << self
+
+          def add(clazz, rule_name, props, &block)
+            rule_node = rule_node_for(clazz.to_s)
+            rule_node.remove_rule(rule_name) # remove any previously inherited rules
+            rule = Rule.new(rule_name, props, &block)
+            rule_node.add_rule(rule)
+            rule
+          end
+
+          def rule_names_for(clazz)
+            rule_node = rule_node_for(clazz)
+            rule_node.rules.map { |rule| rule.rule_name }
+          end
+
+          def rule_node_for(clazz)
+            return nil if clazz.nil?
+            @rule_nodes[clazz.to_s] ||= RuleNode.new(clazz)
+          end
+
+          def find_rule_node(node)
+            @rule_nodes && @rule_nodes.values.find { |rn| rn.rule_node?(node) }
+          end
+
+          def inherit(parent_class, subclass)
+            # copy all the rules
+            if rule_node = rule_node_for(parent_class)
+              rule_node.inherit(subclass)
+            end
+          end
+
+          def trigger?(node)
+            classname = node[:_classname]
+            @rule_nodes && classname && rule_node_for(classname) && !rule_node_for(classname).bulk_update?
+          end
+
+          def trigger_rules(node, *changes)
+            classname = node[:_classname]
+            return unless classname # there are no rules if there is not a :_classname property
+            rule_node = rule_node_for(classname)
+            rule_node.execute_rules(node, *changes)
+
+            # recursively add relationships for all the parent classes with rules that also pass for this node
+            recursive(node, rule_node.model_class, *changes)
+          end
+
+          def bulk_trigger_rules(classname, class_change, map)
+            rule_node = rule_node_for(classname)
+            rule_node.classes_changed(class_change)
+            if (clazz = rule_node.model_class.superclass) && clazz.include?(Neo4j::NodeMixin)
+              bulk_trigger_rules(clazz.name, class_change, map) if clazz.to_s != "Neo4j::Rails::Model"
+            end
+          end
+
+          private
+
+          def recursive(node, model_class, *changes)
+            if (clazz = model_class.superclass) && clazz.include?(Neo4j::NodeMixin)
+              if clazz.to_s != "Neo4j::Rails::Model"
+                rule_node = rule_node_for(clazz)
+                rule_node && rule_node.execute_rules(node, *changes)
+                recursive(node, clazz, *changes)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end