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

data/Gemfile

@@ -6,11 +6,11 @@ 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"
+  gem "test-unit"
 end
 
 gem 'ruby-debug-base19' if RUBY_VERSION.include? "1.9"
 gem 'ruby-debug-base' if RUBY_VERSION.include? "1.8"
-gem "ruby-debug-ide"
+gem "ruby-debug-ide"

data/README.rdoc

@@ -15,13 +15,13 @@ 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.
+  * 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.
+* Seamless integration with Ruby on \Rails.
 * ACID Transaction with rollbacks support.
 
 === Documentation

data/lib/generators/neo4j.rb

@@ -0,0 +1,65 @@
+require 'rails/generators/named_base'
+require 'rails/generators/active_model'
+
+module Neo4j
+	module Generators
+	end
+end
+
+class Neo4j::Generators::Base < Rails::Generators::NamedBase #:nodoc:
+	def self.source_root
+		@_neo4j_source_root ||= File.expand_path(File.join(File.dirname(__FILE__),
+			'neo4j', generator_name, 'templates'))
+	end
+end
+
+class Neo4j::Generators::ActiveModel < Rails::Generators::ActiveModel #:nodoc:
+	def self.all(klass)
+		"#{klass}.all"
+	end
+
+	def self.find(klass, params=nil)
+		"#{klass}.find(#{params})"
+	end
+
+	def self.build(klass, params=nil)
+		if params
+			"#{klass}.new(#{params})"
+		else
+			"#{klass}.new"
+		end
+	end
+
+	def save
+		"#{name}.save"
+	end
+
+	def update_attributes(params=nil)
+		"#{name}.update_attributes(#{params})"
+	end
+
+	def errors
+		"#{name}.errors"
+	end
+
+	def destroy
+		"#{name}.destroy"
+	end
+end
+
+module Rails
+  module Generators
+    class GeneratedAttribute #:nodoc:
+      def type_class
+      	case type.to_s.downcase
+					when 'datetime' 										then 'DateTime'
+					when 'date' 												then 'Date'
+					when 'text' 												then 'String'
+					when 'integer', 'number', 'fixnum' 	then 'Fixnum'
+					when 'float' 												then 'Float'
+					else 'String'
+      	end
+      end
+    end
+  end
+end

data/lib/generators/neo4j/model/model_generator.rb

@@ -0,0 +1,39 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'neo4j.rb')
+
+class Neo4j::Generators::ModelGenerator < Neo4j::Generators::Base
+	argument :attributes, :type => :array, :default => [], :banner => "field:type field:type"
+	
+	check_class_collision
+	
+	class_option :timestamps, :type => :boolean
+	class_option :parent,     :type => :string, :desc => "The parent class for the generated model"
+	
+	def create_model_file
+		template "model.rb", File.join('app/models', "#{singular_name}.rb")
+	end
+	
+	protected
+	def migration?
+		false
+	end
+	
+	def timestamps?
+		options[:timestamps]
+	end
+	
+	def parent?
+		options[:parent]
+	end
+	
+	def timestamp_statements
+		%q{
+property :created_at, DateTime
+# property :created_on, Date
+
+property :updated_at, DateTime
+# property :updated_on, Date
+}            
+	end
+	
+	hook_for :test_framework
+end

data/lib/generators/neo4j/model/templates/model.rb

@@ -0,0 +1,7 @@
+class <%= class_name %> < <%= parent? ? options[:parent].classify : "Neo4j::Rails::Model" %>
+<% attributes.each do |attribute| -%>
+	property :<%= attribute.name %><%= ", :type => #{attribute.type_class}" unless attribute.type_class == "String" %>
+<% end -%>
+
+<%= timestamp_statements if timestamps? -%>
+end

data/lib/neo4j.rb

@@ -22,7 +22,7 @@ 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/index/lucene_query'
 require 'neo4j/relationship_traverser'
 require 'neo4j/node_traverser'
 require 'neo4j/property'
@@ -36,7 +36,6 @@ require 'neo4j/mapping/class_methods/init_node'
 require 'neo4j/mapping/class_methods/init_rel'
 require 'neo4j/mapping/class_methods/root'
 require 'neo4j/mapping/class_methods/property'
-require 'neo4j/mapping/class_methods/index'
 require 'neo4j/mapping/class_methods/relationship'
 require 'neo4j/mapping/decl_relationship_dsl'
 require 'neo4j/mapping/has_n'
@@ -54,6 +53,7 @@ require 'neo4j/rails/transaction'
 require 'neo4j/rails/railtie'
 require 'neo4j/rails/validations/uniqueness'
 require 'neo4j/rails/model'
+require 'neo4j/rails/properties'
 require 'neo4j/rails/value'
 require 'neo4j/rails/lucene_connection_closer'
 

data/lib/neo4j/config.rb

@@ -2,9 +2,12 @@
 module Neo4j
 
 
-  # Keeps configuration for neo4j.
+  # == Keeps configuration for neo4j.
   #
-  # Neo4j::Config[:storage_path]:: is used for locating the neo4j database on the filesystem.
+  # The most important configuration is <tt>Neo4j::Config[:storage_path]</tt> which is used to
+  # locate where the neo4j database is stored on the filesystem.
+  # If this directory is empty then a new database will be created, otherwise it will use the
+  # database from that directory.
   #
   class Config
     # This code is copied from merb-core/config.rb.
@@ -45,8 +48,8 @@ module Neo4j
       # Set the value of a config entry.
       #
       # ==== Parameters
-      # key<Object>:: The key to set the parameter for.
-      # val<Object>:: The value of the parameter.
+      # key:: The key to set the parameter for.
+      # val:: The value of the parameter.
       #
       def []=(key, val)
         (@configuration ||= setup)[key] = val
@@ -56,7 +59,7 @@ module Neo4j
       # Gets the the value of a config entry
       #
       # ==== Parameters
-      # key<Object>:: The key of the config entry value we want
+      # key:: The key of the config entry value we want
       #
       def [](key)
         (@configuration ||= setup)[key]
@@ -69,7 +72,7 @@ module Neo4j
       # key<Object>:: The key of the parameter to delete.
       #
       # ==== Returns
-      # Object:: The value of the removed entry.
+      # The value of the removed entry.
       #
       def delete(key)
         @configuration.delete(key)
@@ -90,12 +93,11 @@ module Neo4j
       # Retrieve the value of a config entry, returning the provided default if the key is not present
       #
       # ==== Parameters
-      # key<Object>:: The key to retrieve the parameter for.
-      # default<Object>::
-      # The default value to return if the parameter is not set.
+      # key:: The key to retrieve the parameter for.
+      # default::The default value to return if the parameter is not set.
       #
       # ==== Returns
-      # Object:: The value of the configuration parameter or the default.
+      # The value of the configuration parameter or the default.
       #
       def fetch(key, default)
         @configuration.fetch(key, default)
@@ -116,7 +118,7 @@ module Neo4j
       # Returns the configuration as a hash.
       #
       # ==== Returns
-      # Hash:: The config as a hash.
+      # The config as a hash.
       #
       def to_hash
         @configuration
@@ -125,7 +127,7 @@ module Neo4j
       # Returns the config as YAML.
       #
       # ==== Returns
-      # String:: The config as YAML.
+      # The config as YAML.
       #
       def to_yaml
         require "yaml"

data/lib/neo4j/database.rb

@@ -1,5 +1,5 @@
 module Neo4j
-  class Database
+  class Database #:nodoc:
     attr_reader :graph, :lucene, :event_handler
 
     def initialize()

data/lib/neo4j/equal.rb

@@ -1,4 +1,7 @@
 module Neo4j
+
+  # == This mixin is used for both nodes and relationships to decide if two entities are equal or not.
+  #
   module Equal
     def equal?(o)
       eql?(o)

data/lib/neo4j/event_handler.rb

@@ -1,6 +1,30 @@
 module Neo4j
 
-  # Handles events like a new node is created or deleted
+  # == Handles Transactional Events
+  #
+  # You can use this to receive event before the transaction commits.
+  # The following events are supported:
+  # * <tt>on_neo4j_started</tt>
+  # * <tt>on_neo4j_shutdown</tt>
+  # * <tt>on_node_created</tt>
+  # * <tt>on_node_deleted</tt>
+  # * <tt>on_relationship_created</tt>
+  # * <tt>on_relationship_deleted</tt>
+  # * <tt>on_property_changed</tt>
+  # * <tt>on_rel_property_changed</tt>
+  #
+  # === Usage
+  #
+  #   class MyListener
+  #     def on_node_deleted(node, old_props, tx_data)
+  #     end
+  #   end
+  #
+  #   # to add an listener without starting neo4j:
+  #   Neo4j.unstarted_db.event_handler.add(MyListener.new)
+  #
+  # You only need to implement the methods that you need.
+  #
   class EventHandler
     include org.neo4j.graphdb.event.TransactionEventHandler
 
@@ -88,18 +112,5 @@ module Neo4j
     def rel_property_changed(rel, key, old_value, new_value)
       @listeners.each {|li| li.on_rel_property_changed(rel, key, old_value, new_value) if li.respond_to?(:on_rel_property_changed)}
     end
-
-    # TODO ?
-    def tx_finished(tx)
-      @listeners.each {|li| li.on_tx_finished(tx) if li.respond_to?(:on_tx_finished)}
-    end
-
-    def neo_started(neo_instance)
-      @listeners.each {|li|  li.on_neo_started(neo_instance)  if li.respond_to?(:on_neo_started)}
-    end
-
-    def neo_stopped(neo_instance)
-      @listeners.each {|li| li.on_neo_stopped(neo_instance) if li.respond_to?(:on_neo_stopped)}
-    end
   end
 end

data/lib/neo4j/index/class_methods.rb

@@ -34,11 +34,12 @@ module Neo4j
       #   class Phone
       #      include Neo4j::NodeMixin
       #      property :phone
-      #      index :phone, :indexer => Person, :via => proc{|node| node.incoming(:phone).first}
+      #      node_indexer Contact  # put index on the Contact class instead
+      #      index :phone
       #   end
       #
       #   # Find an contact with a phone number, this works since they share the same index
-      #   Contact.find('phone: 12345 AND name: 'pelle'')
+      #   Contact.find('phone: 12345').first #=> a phone object !
       #
       # ==== Returns
       # The indexer that should be used to index the given class

data/lib/neo4j/index/indexer.rb

@@ -1,9 +1,9 @@
 module Neo4j
   module Index
-    class Indexer #:nodoc:
+    class Indexer 
       attr_reader :indexer_for, :field_types, :via_relationships
 
-      def initialize(clazz, type)
+      def initialize(clazz, type) #:nodoc:
         # part of the unique name of the index
         @indexer_for       = clazz
 
@@ -19,7 +19,7 @@ module Neo4j
         @parent_indexers   = []
       end
 
-      def inherit_fields_from(parent_index)
+      def inherit_fields_from(parent_index) #:nodoc:
         return unless parent_index
         @field_types.reverse_merge!(parent_index.field_types) if parent_index.respond_to?(:field_types)
         @via_relationships.reverse_merge!(parent_index.via_relationships) if parent_index.respond_to?(:via_relationships)
@@ -30,7 +30,53 @@ module Neo4j
         "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.
+      # Add an index on a field so that it will be automatically updated by neo4j transactional events.
+      #
+      # The index method takes an optional configuration hash which allows you to:
+      #
+      # === Add an index on an a property
+      #
+      # Example:
+      #   class Person
+      #     include Neo4j::NodeMixin
+      #     index :name
+      #   end
+      #
+      # When the property name is changed/deleted or the node created it will keep the lucene index in sync.
+      # You can then perform a lucene query like this: Person.find('name: andreas')
+      #'
+      # === Add index on other nodes.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Neo4j::NodeMixin
+      #     has_n(:friends).to(Contact)
+      #     has_n(:known_by).from(:friends)
+      #     index :user_id, :via => :known_by
+      #   end
+      #
+      # Notice that you *must* specify an incoming relationship with the via key, as shown above.
+      # In the example above an index <tt>user_id</tt> will be added to all Person nodes which has a <tt>friends</tt> relationship
+      # that person with that user_id. This allows you to do lucene queries on your friends properties.
+      #
+      # === Set the type value to index
+      # By default all values will be indexed as Strings.
+      # If you want for example to do a numerical range query you must tell Neo4j.rb to index it as a numeric value.
+      # You do that with the key <tt>type</tt>
+      #
+      # Example:
+      #   class Person
+      #     include Neo4j::NodeMixin
+      #     index :weight, :type => Float
+      #   end
+      #
+      # Supported values for <tt>:type</tt> is <tt>String</tt>, <tt>Float</tt> and <tt>Fixnum</tt>
+      #
+      # === For more information
+      # * See Neo4j::Index::LuceneQuery
+      # * See #find
+      #
       def index(field, conf = {})
         if conf[:via]
           rel_dsl = @indexer_for._decl_rels[conf[:via]]
@@ -48,7 +94,7 @@ module Neo4j
         end
       end
 
-      def remove_index_on_fields(node, props, tx_data)
+      def remove_index_on_fields(node, props, tx_data) #:nodoc:
         @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|
@@ -61,15 +107,15 @@ module Neo4j
         end
       end
 
-      def update_on_deleted_relationship(relationship)
+      def update_on_deleted_relationship(relationship) #:nodoc:
         update_on_relationship(relationship, false)
       end
 
-      def update_on_new_relationship(relationship)
+      def update_on_new_relationship(relationship) #:nodoc:
         update_on_relationship(relationship, true)
       end
 
-      def update_on_relationship(relationship, is_created)
+      def update_on_relationship(relationship, is_created) #:nodoc:
         rel_type = relationship.rel_type
         end_node = relationship._end_node
         # find which via relationship match rel_type
@@ -93,7 +139,7 @@ module Neo4j
         end
       end
 
-      def update_index_on(node, field, old_val, new_val)
+      def update_index_on(node, field, old_val, new_val) #:nodoc:
         if @via_relationships.include?(field)
           dsl = @via_relationships[field]
           to_class = dsl.to_class
@@ -106,42 +152,94 @@ module Neo4j
         update_single_index_on(node, field, old_val, new_val)
       end
 
-      def update_single_index_on(node, field, old_val, new_val)
+      def update_single_index_on(node, field, old_val, new_val) #:nodoc:
         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
 
+      # Returns true if there is an index on the given field.
+      #
       def index?(field)
         @field_types.include?(field.to_s)
       end
 
-      def index_type_for(field)
+      # Returns the type of index for the given field (e.g. :exact or :fulltext)
+      #
+      def index_type_for(field) #:nodoc:
         return nil unless index?(field)
         @field_types[field.to_s]
       end
 
+      # Returns true if there is an index of the given type defined.
       def index_type?(type)
         @field_types.values.include?(type)
       end
 
+      # Adds an index on the given entity
+      # This is normally not needed since you can instead declare an index which will automatically keep
+      # the lucene index in sync. See #index
+      #
       def add_index(entity, field, value)
        	return false unless @field_types.has_key?(field)
+
+        # we might need to know what type the properties are when indexing and querying
+        @decl_props ||= @indexer_for.respond_to?(:_decl_props) && @indexer_for._decl_props
+
+        type = @decl_props && @decl_props[field.to_sym] && @decl_props[field.to_sym][:type]
+        if type
+          raise "Can't index #{type} with value #{value} since it is not a #{type}" unless type === value
+          value = if String != type
+                    org.neo4j.index.impl.lucene.ValueContext.new(value).indexNumeric
+                  else
+                    org.neo4j.index.impl.lucene.ValueContext.new(value)
+                  end
+
+        end
+
         index_for_field(field.to_s).add(entity, field, value)
       	@parent_indexers.each { |i| i.add_index(entity, field, value) }
       end
 
+      # Removes an index on the given entity
+      # This is normally not needed since you can instead declare an index which will automatically keep
+      # the lucene index in sync. See #index
+      #
       def rm_index(entity, field, value)
         return false unless @field_types.has_key?(field)
         index_for_field(field).remove(entity, field, value)
         @parent_indexers.each { |i| i.rm_index(entity, field, value) }
       end
 
+      # Performs a Lucene Query.
+      #
+      # In order to use this you have to declare an index on the fields first, see #index.
+      # Notice that you should close the lucene query after the query has been executed.
+      # You can do that either by provide an block or calling the Neo4j::Index::LuceneQuery#close
+      # method. When performing queries from Ruby on Rails you do not need this since it will be automatically closed
+      # (by Rack).
+      #
+      # === Example, with a block
+      #   
+      #   Person.find('name: kalle') {|query| puts "#{[*query].join(', )"}
+      #
+      # ==== Example
+      #
+      #   query = Person.find('name: kalle')
+      #   puts "First item #{query.first}"
+      #   query.close
+      #
+      # === Return Value
+      # It will return a Neo4j::Index::LuceneQuery object
+      #
+      #
       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)
+        # we might need to know what type the properties are when indexing and querying
+        @decl_props ||= @indexer_for.respond_to?(:_decl_props) && @indexer_for._decl_props
+
+        index = index_for_type(params[:type] || :exact)
+        query = (params[:wrapped].nil? || params[:wrapped]) ? LuceneQuery.new(index, @decl_props, query) : index.query(query)
 
         if block_given?
           begin
@@ -155,7 +253,7 @@ module Neo4j
         end
       end
 
-      # clears the index, if no type is provided clear all types of indexes
+      # delete the index, if no type is provided clear all types of indexes
       def delete_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)
@@ -167,12 +265,14 @@ module Neo4j
         end
       end
 
-      def on_neo4j_shutdown
+      def on_neo4j_shutdown #:nodoc:
         # Since we might start the database again we must make sure that we don't keep any references to
-        # an old lucene index service.
+        # an old lucene index in memory.
         @indexes.clear
       end
 
+      # Removes the cached lucene index, can be useful for some RSpecs which needs to restart the Neo4j.
+      #
       def rm_field_type(type=nil)
         if type
           @field_types.delete_if { |k, v| v == type }
@@ -181,22 +281,22 @@ module Neo4j
         end
       end
 
-      def index_for_field(field)
+      def index_for_field(field) #:nodoc:
         type = @field_types[field]
         @indexes[type] ||= create_index_with(type)
       end
 
-      def index_for_type(type)
+      def index_for_type(type) #:nodoc:
         @indexes[type] ||= create_index_with(type)
       end
 
-      def lucene_config(type)
+      def lucene_config(type) #:nodoc:
         conf = Neo4j::Config[:lucene][type.to_sym]
         raise "unknown lucene type #{type}" unless conf
         conf
       end
 
-      def create_index_with(type)
+      def create_index_with(type) #:nodoc:
         db=Neo4j.started_db
         index_config = lucene_config(type)
         if @type == :node