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

data/Gemfile

@@ -1,3 +1,12 @@
 source :gemcutter
 
 gemspec
+
+group 'test' do
+  gem "rake", ">= 0.8.7"
+  gem "rdoc", ">= 2.5.10"
+  gem "horo", ">= 1.0.2"
+  gem "rspec-apigen", ">= 0.0.4"
+  gem "rspec", ">= 2.0.0"
+  gem "rspec-rails-matchers", ">= 0.2.1"
+end

data/README.rdoc

@@ -1,40 +1,104 @@
-= Neo4j.rb
+== Welcome to Neo4j.rb
 
 Neo4j.rb is a graph database for JRuby.
 
-
- 
-It provides:
-* Mapping of ruby objects to nodes in networks rather than in tables.
-* Dynamic, and schema-free - no need to declare nodes/properties/relationships in advance.
-* Storage of ruby object to a file system.
-* Fast traversal of relationships between nodes in a huge node space.
-* Transaction with rollbacks support. 
-* Indexing and querying of ruby objects.
-* Migration and BatchInserter support
-* Can be used instead of ActiveRecord in Ruby on Rails or Merb
-* Can be accessible as REST resources.
+You can think of \Neo4j as a high-performance graph engine with all the features of a mature and robust database.
+The programmer works with an object-oriented, flexible network structure rather than with strict and static tables — yet enjoys all the benefits of a fully transactional, enterprise-strength database.
 
 It uses two powerful and mature Java libraries:
-* Neo4J (http://www.neo4j.org/) - for persistence and traversal of the graph
-* Lucene (http://lucene.apache.org/java/docs/index.html) for querying and indexing.
+* {Neo4J}[http://www.neo4j.org] - for persistence and traversal of the graph
+* {Lucene}[http://lucene.apache.org/java/docs/index.html] for querying and indexing.
+
+=== Why Neo4j.rb or a Graph Database ?
+
+Here are some of the major benefits of Neo4j.rb
+
+* Domain Modeling - use the language of a graph (nodes/relationship/properties) to express your domain !
+  * Schema Less and Efficient storage of Semi Structured Information
+  * No {O/R mismatch}[http://en.wikipedia.org/wiki/Object-relational_impedance_mismatch] - very natural to map a graph to an Object Oriented language like Ruby.
+* {Performance}[http://www.oscon.com/oscon2009/public/schedule/detail/8364]
+* Embedded Database - no database tier, easier to install, test, deploy and configure. It is run in the same process as your application.
+* Express Queries as Traversals
+  * Fast deep traversal instead of slow SQL queries that span many table joins.
+  * Very natural to express graph related problem with traversals (recommendation engine, find shortest parth etc..)
+* Seamless integration with Ruby on Rails.
+* ACID Transaction with rollbacks support.
 
 === Documentation
-* Wiki: http://github.com/andreasronge/neo4j/wiki
-* API Documentation - http://neo4j.rubyforge.org/ (of the released version)
 
-=== Project information
-* GitHub - http://github.com/andreasronge/neo4j/tree/master
-* Issue Tracking - http://neo4j.lighthouseapp.com
-* Twitter - http://twitter.com/ronge
-* IRC -  #neo4j @ irc.freenode.net
-* Source repo - git://github.com/andreasronge/neo4j.git
-* Mailing list - http://groups.google.com/group/neo4jrb (neo4jrb@googlegroups.com)
+* {Documentation and Getting Started with Neo4j}[http://github.com/andreasronge/neo4j/wiki]
+* {API Documentation (released version)}[http://neo4j.rubyforge.org]
+
+=== Some Examples
+
+==== Neo4j::Node
+
+Example of creating a Neo4j::Node
+
+  require "rubygems"
+  require 'neo4j'
+
+  Neo4j::Transaction.run do
+    node = Neo4j::Node.new :name => 'andreas'
+    node.outgoing(:friends) << Neo4j::Node.new :name => 'peter'
+    node.outgoing(:friends).each {|node| puts "name #{node[:name]}"}
+  end
+
+==== Neo4j::Mapping::NodeMixin
+
+Example of mapping a ruby class to a node and delaring properties and relationships and lucene index.
+
+  class Person
+    include Neo4j::NodeMixin
+    property :name
+    property :city
+
+    has_n :friends
+    has_one :address
+    index :name
+  end
+
+  # assume we have an transaction already running
+  andreas = Person.new :name => 'andreas'
+  andreas.friends << Person.new :name => 'peter'
+  andreas.friends.each {|person| puts "name #{person.name}" }
+  Person.find("name: andreas").first.name # => 'andreas'
+
+==== Neo4j::Rails::Model
+
+Example of using Neo4j with Rails 3 (ActiveModel)
+
+  class User < Neo4j::Model
+    attr_accessor :password
+    attr_accessible :email, :password, :password_confirmation, :pending_account
+
+    after_save   :encrypt_password
+
+    email_regex = /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i
+
+    validates :email, :presence => true,:format   => { :with => email_regex }
+    validates :email, :uniqueness => true, :unless => :pending_account?
+    accepts_nested_attributes_for :avatar, :allow_destroy => true
+
+    property :email
+    index :email
+
+    has_one(:avatar).to(Avator)
+
+    ...
+  end
 
 === Presentation Materials and other URLs
-* Ruby Manor 2008 - Jonathan Conway: http://jaikoo.com/assets/presentations/neo4j.pdf
-* Nordic Ruby 2010 (upcoming May 21-23) http://nordicruby.org/speakers#user_29
-* Neo4j wiki - http://wiki.neo4j.org/content/Main_Page (check the guidelines and domain modeling gallery pages)
+* {Intoduction to Neo4j.rb}[http://www.slideshare.net/andreasronge/neo4jrb]
+* {Nordic Ruby 2010 May 21-23}[http://nordicruby.org/speakers#user_29]
+* {Neo4j wiki, check the guidelines and domain modeling gallery pages}[http://wiki.neo4j.org/content/Main_Page]
+
+=== Project information
+* {GitHub}[http://github.com/andreasronge/neo4j/tree/master]
+* {Lighthouse Issue Tracking}[http://neo4j.lighthouseapp.com]
+* {Twitter}[http://twitter.com/ronge]
+* IRC -  #neo4j @ irc.freenode.net
+* {Mailing list, neo4jrb@googlegroups.com}[http://groups.google.com/group/neo4jrb]
 
 === Contributing
 
@@ -46,4 +110,4 @@ Please also check/add issues at lighthouse, http://neo4j.lighthouseapp.com
 === License
 * Neo4j.rb - MIT, see the LICENSE file http://github.com/andreasronge/neo4j/tree/master/LICENSE.
 * Lucene -  Apache, see http://lucene.apache.org/java/docs/features.html
-* Neo4j - Dual free software/commercial license, see http://neo4j.org/
+* \Neo4j - Dual free software/commercial license, see http://neo4j.org/

data/lib/neo4j.rb

@@ -12,10 +12,17 @@ require 'neo4j/jars/neo4j-lucene-index-0.1-20101002.153213-102.jar'
 require 'neo4j/to_java'
 require 'neo4j/version'
 require 'neo4j/equal'
-require 'neo4j/index'
-require 'neo4j/relationship_traverser'
+
 require 'neo4j/event_handler'
 require 'neo4j/database'
+require 'neo4j/neo4j'
+
+require 'neo4j/index/index'
+require 'neo4j/index/class_methods'
+require 'neo4j/index/index_registry'
+require 'neo4j/index/indexer'
+require 'neo4j/index/wrapped_query'
+require 'neo4j/relationship_traverser'
 require 'neo4j/node_traverser'
 require 'neo4j/property'
 require 'neo4j/transaction'
@@ -24,7 +31,6 @@ require 'neo4j/load'
 require 'neo4j/relationship'
 require 'neo4j/node'
 require 'neo4j/config'
-require 'neo4j/neo4j'
 require 'neo4j/mapping/class_methods/init_node'
 require 'neo4j/mapping/class_methods/init_rel'
 require 'neo4j/mapping/class_methods/root'

data/lib/neo4j/database.rb

@@ -20,8 +20,11 @@ module Neo4j
       if @running
         @graph.unregister_transaction_event_handler(@event_handler)
         @event_handler.neo4j_shutdown(self)
+        @graph.shutdown
+        @graph = nil
+        @lucene = nil
       end
-      @graph.shutdown
+
       @running = false
     end
 
@@ -37,7 +40,14 @@ module Neo4j
     def each_node
       iter = @graph.all_nodes.iterator
       while (iter.hasNext)
-        yield Node.wrapper(iter.next)
+        yield iter.next.wrapper
+      end
+    end
+
+    def _each_node
+      iter = @graph.all_nodes.iterator
+      while (iter.hasNext)
+        yield iter.next
       end
     end
 

data/lib/neo4j/equal.rb

@@ -1,9 +1,5 @@
 module Neo4j
   module Equal
-    def neo_id
-      getId
-    end
-
     def equal?(o)
       eql?(o)
     end

data/lib/neo4j/event_handler.rb

@@ -19,9 +19,9 @@ module Neo4j
       data.created_nodes.each{|node| node_created(node)}
       data.assigned_node_properties.each { |tx_data| property_changed(tx_data.entity, tx_data.key, tx_data.previously_commited_value, tx_data.value) }
       data.removed_node_properties.each { |tx_data| property_changed(tx_data.entity, tx_data.key, tx_data.previously_commited_value, nil) unless data.deleted_nodes.include?(tx_data.entity) }
-      data.deleted_nodes.each { |node| node_deleted(node, deleted_properties_for(node,data))}
-      data.created_relationships.each {|rel| relationship_created(rel)}
-      data.deleted_relationships.each {|rel| relationship_deleted(rel, deleted_rel_properties_for(rel, data))}
+      data.deleted_nodes.each { |node| node_deleted(node, deleted_properties_for(node,data), data)}
+      data.created_relationships.each {|rel| relationship_created(rel, data)}
+      data.deleted_relationships.each {|rel| relationship_deleted(rel, deleted_rel_properties_for(rel, data), data)}
       data.assigned_relationship_properties.each { |tx_data| rel_property_changed(tx_data.entity, tx_data.key, tx_data.previously_commited_value, tx_data.value) }
       data.removed_relationship_properties.each {|tx_data| rel_property_changed(tx_data.entity, tx_data.key, tx_data.previously_commited_value, nil) unless data.deleted_relationships.include?(tx_data.entity) }
     end
@@ -69,16 +69,16 @@ module Neo4j
       @listeners.each {|li| li.on_node_created(node) if li.respond_to?(:on_node_created)}
     end
 
-    def node_deleted(node,old_properties)
-      @listeners.each {|li| li.on_node_deleted(node,old_properties) if li.respond_to?(:on_node_deleted)}
+    def node_deleted(node,old_properties, data)
+      @listeners.each {|li| li.on_node_deleted(node,old_properties, data) if li.respond_to?(:on_node_deleted)}
     end
 
-    def relationship_created(relationship)
-      @listeners.each {|li| li.on_relationship_created(relationship) if li.respond_to?(:on_relationship_created)}
+    def relationship_created(relationship, tx_data)
+      @listeners.each {|li| li.on_relationship_created(relationship, tx_data) if li.respond_to?(:on_relationship_created)}
     end
 
-    def relationship_deleted(relationship, old_props)
-      @listeners.each {|li| li.on_relationship_deleted(relationship, old_props) if li.respond_to?(:on_relationship_deleted)}
+    def relationship_deleted(relationship, old_props, data)
+      @listeners.each {|li| li.on_relationship_deleted(relationship, old_props, data) if li.respond_to?(:on_relationship_deleted)}
     end
 
     def property_changed(node, key, old_value, new_value)

data/lib/neo4j/index/class_methods.rb

@@ -0,0 +1,61 @@
+module Neo4j
+  module Index
+    module ClassMethods
+      attr_reader :_indexer
+
+      extend Forwardable
+
+      ##
+      # See Neo4j::Index::Indexer#index
+      # Forwards to the indexer that should be used.
+      # It is possible to share the same index for several different classes, see #node_indexer.
+      # :singleton-method: index
+
+      ##
+      # See Neo4j::Index::Indexer#find
+      # Forwards to the indexer that should be used.
+      # It is possible to share the same index for several different classes, see #node_indexer.
+      # :singleton-method: find
+
+
+      def_delegators :@_indexer, :index, :find, :index?, :index_type?, :clear_index_type, :rm_index_type, :add_index, :rm_index, :index_type_for, :index_name
+
+
+      # Sets which indexer should be used for the given node class.
+      # You can share an indexer between several different classes.
+      #
+      # ==== Example
+      #   class Contact
+      #      include Neo4j::NodeMixin
+      #      index :name
+      #      has_one :phone
+      #   end
+      #
+      #   class Phone
+      #      include Neo4j::NodeMixin
+      #      property :phone
+      #      index :phone, :indexer => Person, :via => proc{|node| node.incoming(:phone).first}
+      #   end
+      #
+      #   # Find an contact with a phone number, this works since they share the same index
+      #   Contact.find('phone: 12345 AND name: 'pelle'')
+      #
+      # ==== Returns
+      # The indexer that should be used to index the given class
+      def node_indexer(clazz)
+        indexer(clazz, :node)
+      end
+
+      # Sets which indexer should be used for the given relationship class
+      # Same as #node_indexer except that it indexes relationships instead of nodes.
+      #
+      def rel_indexer(clazz)
+        indexer(clazz, :rel)
+      end
+
+      def indexer(clazz, type) #:nodoc:
+        @_indexer = IndexerRegistry.create_for(self, clazz, type)
+      end
+    end
+  end
+end

data/lib/neo4j/index/index.rb

@@ -0,0 +1,33 @@
+module Neo4j
+
+  module Index
+
+    # Adds an index on the given property
+    # Notice that you normally don't have to do that since you simply can declare
+    # that the property and index should be updated automatically by using the class method #index.
+    #
+    # The index operation will take place immediately unlike when using the Neo4j::Index::ClassMethods::index
+    # method which instead will guarantee that the neo4j database and the lucene database will be consistent.
+    # It uses a two phase commit when the transaction is about to be committed.
+    #
+    # ==== See also
+    # Neo4j::Index::ClassMethods::index
+    #
+    def add_index(field, value=self[field])
+      self.class.add_index(wrapped_entity, field.to_s, value)
+    end
+
+    # Removes an index on the given property.
+    # Just like #add_index this is normally not needed since you instead can declare it with the
+    # #index class method instead.
+    #
+    # ==== See also
+    # Neo4j::Index::ClassMethods::index
+    # Neo4j::Index#add_index
+    #
+    def rm_index(field, value=self[field])
+      self.class.rm_index(wrapped_entity, field.to_s, value)
+    end
+
+  end
+end

data/lib/neo4j/index/index_registry.rb

@@ -0,0 +1,67 @@
+module Neo4j
+  module Index
+    class IndexerRegistry #:nodoc:
+      class << self
+
+        def clear_all_indexes
+          @@indexers.values.each {|i| i.clear_index_type}
+        end
+
+        def create_for(this_clazz, using_other_clazz, type)
+          @@indexers ||= {}
+          @@indexers[this_clazz.to_s] = @@indexers[using_other_clazz.to_s] || Indexer.new(this_clazz, type)
+          @@indexers[this_clazz.to_s]
+        end
+
+        def find_by_class(classname)
+          @@indexers[classname]
+        end
+
+        def on_node_deleted(node, old_props, tx_data)
+          indexer = find_by_class(old_props['_classname'] || node.class.to_s)
+          indexer && indexer.remove_index_on_fields(node, old_props, tx_data)
+        end
+
+        def on_property_changed(node, field, old_val, new_val)
+          classname = node['_classname'] || node.class.to_s
+          indexer = find_by_class(classname)
+          indexer && indexer.update_index_on(node, field, old_val, new_val)
+        end
+
+        def on_rel_property_changed(rel, field, old_val, new_val)
+          # works exactly like for nodes
+          on_property_changed(rel, field, old_val, new_val)
+        end
+
+        def on_relationship_created(rel, tx_data)
+          end_node = rel._end_node
+          # if end_node was created in this transaction then it will be handled in on_property_changed
+          created = tx_data.created_nodes.find{|n| n.neo_id == end_node.neo_id}
+          unless created
+            indexer = find_by_class(end_node['_classname'])
+            indexer && indexer.update_on_new_relationship(rel)
+          end
+        end
+
+        def on_relationship_deleted(rel, old_props, tx_data)
+          on_node_deleted(rel, old_props, tx_data)
+          # if only the relationship has been deleted then we have to remove the index
+          # if both the relationship and the node has been deleted then the index will be removed in the
+          # on_node_deleted callback
+          end_node = rel._end_node
+          deleted = tx_data.deleted_nodes.find{|n| n.neo_id == end_node.neo_id}
+          unless deleted
+            indexer = find_by_class(end_node['_classname'])
+            indexer && indexer.update_on_deleted_relationship(rel)
+          end
+        end
+
+        def on_neo4j_shutdown(*)
+          @@indexers.each_value {|indexer| indexer.on_neo4j_shutdown}
+        end
+      end
+    end
+    Neo4j.unstarted_db.event_handler.add(IndexerRegistry)
+
+  end
+end

data/lib/neo4j/index/indexer.rb

@@ -0,0 +1,193 @@
+module Neo4j
+  module Index
+    class Indexer #:nodoc:
+      attr_reader :indexer_for
+
+      def initialize(clazz, type)
+        # part of the unique name of the index
+        @indexer_for = clazz
+
+        # do we want to index nodes or relationships ?
+        @type = type
+
+        @indexes = {} # key = type, value = java neo4j index
+        @field_types = {} # key = field, value = type (e.g. :exact or :fulltext)
+        @via_relationships = {} # key = field, value = relationship
+      end
+
+      def to_s
+        "Indexer @#{object_id} [index_for:#{@indexer_for}, field_types=#{@field_types.keys.join(', ')}, via=#{@via_relationships.inspect}]"
+      end
+
+      #  add an index on a field so that it will be automatically updated by neo4j events.
+      def index(field, conf = {})
+        if conf[:via]
+          rel_dsl = @indexer_for._decl_rels[conf[:via]]
+          raise "No relationship defined for '#{conf[:via]}'. Check class '#{@indexer_for}': index :#{field}, via=>:#{conf[:via]} <-- error. Define it with a has_one or has_n" unless rel_dsl
+          raise "Only incoming relationship are possible to define index on. Check class '#{@indexer_for}': index :#{field}, via=>:#{conf[:via]}" unless rel_dsl.incoming?
+          via_indexer = rel_dsl.to_class._indexer
+
+          field = field.to_s
+          @via_relationships[field] = rel_dsl
+          conf.delete :via # avoid endless recursion
+          via_indexer.index(field, conf)
+        else
+          raise "Already defined an (via?) index on #{field}, Using the same index for from two classes ? Check index :#{field}, :via => :#{@indexer_for}" if @field_types[field.to_s]
+          @field_types[field.to_s] = conf[:type] || :exact
+        end
+      end
+
+      def remove_index_on_fields(node, props, tx_data)
+        @field_types.keys.each { |field| rm_index(node, field, props[field]) if props[field] }
+        # remove all via indexed fields
+        @via_relationships.each_value do |dsl|
+          indexer = dsl.to_class._indexer
+          tx_data.deleted_relationships.each do |rel|
+            start_node = rel._start_node
+            next if node != rel._end_node
+            indexer.remove_index_on_fields(start_node, props, tx_data)
+          end
+        end
+      end
+
+      def update_on_deleted_relationship(relationship)
+        update_on_relationship(relationship, false)
+      end
+
+      def update_on_new_relationship(relationship)
+        update_on_relationship(relationship, true)
+      end
+
+      def update_on_relationship(relationship, is_created)
+        rel_type = relationship.rel_type
+        end_node = relationship._end_node
+        # find which via relationship match rel_type
+        @via_relationships.each_pair do |field, dsl|
+          # have we declared an index on this changed relationship ?
+          next unless dsl.incoming_dsl.namespace_type == rel_type
+
+          # yes, so find the node and value we should update the index on
+          val        = end_node[field]
+          start_node = relationship._start_node
+
+          # find the indexer to use
+          indexer   = dsl.to_class._indexer
+
+          # is the relationship created or deleted ?
+          if is_created
+            indexer.update_index_on(start_node, field, nil, val)
+          else
+            indexer.update_index_on(start_node, field, val, nil)
+          end
+        end
+      end
+
+      def update_index_on(node, field, old_val, new_val)
+        if @via_relationships.include?(field)
+          dsl = @via_relationships[field]
+          to_class = dsl.to_class
+
+          dsl.all_relationships(node).each do |rel|
+            other = rel._start_node
+            to_class._indexer.update_index_on(other, field, old_val, new_val)
+          end
+        end
+
+        if @field_types.include?(field)
+          rm_index(node, field, old_val) if old_val
+          add_index(node, field, new_val) if new_val
+        end
+      end
+
+      def index?(field)
+        @field_types.include?(field.to_s)
+      end
+
+      def index_type_for(field)
+        return nil unless index?(field)
+        @field_types[field.to_s]
+      end
+
+      def index_type?(type)
+        @field_types.values.include?(type)
+      end
+
+      def add_index(entity, field, value)
+        index_for_field(field.to_s).add(entity, field, value)
+      end
+
+      def rm_index(entity, field, value)
+        index_for_field(field).remove(entity, field, value)
+      end
+
+      def find(query, params = {})
+        type = params[:type] || :exact
+        index = index_for_type(type)
+        query = (params[:wrapped].nil? || params[:wrapped]) ? WrappedQuery.new(index, query) : index.query(query)
+
+        if block_given?
+          begin
+            ret = yield query
+          ensure
+            query.close
+          end
+          ret
+        else
+          query
+        end
+      end
+
+      # clears the index, if no type is provided clear all types of indexes
+      def clear_index_type(type=nil)
+        if type
+          #raise "can't clear index of type '#{type}' since it does not exist ([#{@field_types.values.join(',')}] exists)" unless index_type?(type)
+          @indexes[type] && @indexes[type].clear
+        else
+          @indexes.each_value { |index| index.clear }
+        end
+      end
+
+      def on_neo4j_shutdown
+        # Since we might start the database again we must make sure that we don't keep any references to
+        # an old lucene index service.
+        @indexes.clear
+      end
+
+      def rm_index_type(type=nil)
+        if type
+          @field_types.delete_if { |k, v| v == type }
+        else
+          @field_types.clear
+        end
+      end
+
+      def index_for_field(field)
+        type = @field_types[field]
+        @indexes[type] ||= create_index_with(type)
+      end
+
+      def index_for_type(type)
+        @indexes[type] ||= create_index_with(type)
+      end
+
+      def lucene_config(type)
+        conf = Neo4j::Config[:lucene][type.to_sym]
+        raise "unknown lucene type #{type}" unless conf
+        conf
+      end
+
+      def create_index_with(type)
+        db=Neo4j.started_db
+        index_config = lucene_config(type)
+        if @type == :node
+          db.lucene.node_index("#{@indexer_for}-#{type}", index_config)
+        else
+          db.lucene.relationship_index("#{@indexer_for}-#{type}", index_config)
+        end
+      end
+
+    end
+
+  end
+
+end