neo4j 1.0.0.beta.1

data/lib/neo4j.old/neo.rb

@@ -0,0 +1,247 @@
+module Neo4j
+
+  class << self
+    extend Forwardable
+
+    ##
+    # Returns the current version of the database.
+    # This version has been set by running one or more migrations.
+    # The version is stored on the reference node, with property 'db_version'
+    # (Delegates to the Reference Node that includes the MigrationMixin.)
+    #
+    # === See Also
+    # Neo4j::MigrationMixin#db_version
+    #
+    # :singleton-method: db_version
+
+    ##
+    # Force Neo4j.rb to perform migrations
+    #
+    # === See Also
+    # Neo4j::MigrationMixin#migrate!
+    #
+    # :singleton-method: migrate!
+
+    ##
+    # Specifies a single migration.
+    #
+    # === Example
+    # Notice that the reference node is the context in the up and down blocks.
+    #
+    #   Neo4j.migration 1, :create_articles do
+    #    up do
+    #      rels.outgoing(:colours) << Neo4j.new :colour => 'red'  << Neo4j.new :colour => 'blue'
+    #    end
+    #    down do
+    #      rels.outgoing(:colours).each {|n| n.del }
+    #    end
+    #  end
+    #
+    # === See Also
+    # Neo4j::MigrationMixin::ClassMethods#migration
+    # Neo4j::ReferenceNode
+    #
+    # :singleton-method: migration
+
+    ##
+    # Returns all migrations that has been defined.
+    #
+    # === See Also
+    # Neo4j::MigrationMixin::ClassMethods#migrations
+    #
+    # :singleton-method: migrations
+
+    def_delegators :@ref_node, :db_version, :migrate!
+    def_delegators Neo4j::ReferenceNode, :migration, :migrations
+
+
+
+    # Starts neo4j unless it is not already started.
+    # Before using neo4j it has to be started and the location of the Neo database on the file system must
+    # have been configured, Neo4j::Config[:storage_path]. You do not have to call this method since
+    # neo4j will be started automatically when needed.
+    # Registers an at_exit handler that stops neo4j (see Neo4j::stop)
+    #
+    # === Parameters
+    # neo_instance:: optional, an instance of org.neo4j.graphdb.GraphDatabaseService
+    #
+    # === Examples
+    #   Neo4j::Config[:storage_path] = '/var/neo4j-db'
+    #   Neo4j.start
+    #
+    # === Returns
+    # nil
+    #
+    def start(neo_instance=nil)
+      return if running?
+      at_exit do
+        Neo4j.stop
+      end
+      @neo = neo_instance || org.neo4j.kernel.EmbeddedGraphDatabase.new(Neo4j::Config[:storage_path])
+      @ref_node = Neo4j::Transaction.run do
+        ReferenceNode.new(@neo.getReferenceNode())
+      end
+
+      Neo4j::Transaction.run do
+        Neo4j.event_handler.neo_started(self)
+      end
+
+      Neo4j::Transaction.run { @ref_node.migrate!}
+      nil
+    end
+
+    # Return the org.neo4j.kernel.EmbeddedGraphDatabase
+    #
+    #
+    def instance
+      start unless running?
+      @neo
+    end
+
+    # Stops the current instance unless it is not started.
+    #
+    def stop
+      if running?
+        Neo4j::Transaction.finish # just in case
+        @neo.shutdown
+        Neo4j.event_handler.neo_stopped(self)
+      end
+      @neo = nil
+    end
+
+    #
+    # Returns true if neo4j is running
+    #
+    def running?
+      !@neo.nil?
+    end
+
+
+    # Create a Neo4j::Node
+    # This is the same as Neo4j::Node.new.
+    # All nodes are created by this method
+    def create_node(props = {}) # :nodoc:
+      node = instance.createNode
+      props.each_pair{|k,v| node[k] = v}
+      node
+    end
+
+    # Creates a new Relationship
+    # All relationships are created by this method.
+    def create_rel(type, from_node, to_node, props = {}) # :nodoc:
+      rel = from_node.add_rel(type, to_node)
+      props.each_pair {|k,v| rel[k] = v}
+      rel
+    end
+
+    # Return a Neo4j node.
+    #
+    # ==== Parameters
+    # node_id:: the unique neo id for one node, should respond to 'to_i'
+    # raw:: if the raw Java node object should be returned or the Ruby wrapped node, default false.
+    #
+    # ==== Returns
+    # The node object or nil if not found
+    #
+    def load_node(node_id, raw = false)
+      neo_node = @neo.getNodeById(node_id.to_i)
+      if (raw)
+        neo_node
+       else
+        neo_node.wrapper
+      end
+    rescue org.neo4j.graphdb.NotFoundException
+      nil
+    end
+
+
+    # Return a Neo4j relationship.
+    #
+    # ==== Parameters
+    # rel_id<String, to_i>:: the unique neo id for one node
+    # raw<true|false(default)> :: if the raw Java relationship object should be returned or the Ruby wrapped node.
+    #
+    # ==== Returns
+    # The node object or nil if not found
+    #
+    def load_rel(rel_id, raw = false)
+      neo_rel = @neo.getRelationshipById(rel_id.to_i)
+      if (raw)
+        neo_rel
+      else
+        neo_rel.wrapper
+      end
+    rescue org.neo4j.graphdb.NotFoundException
+      nil
+    end
+
+    # Returns all nodes in the node space.
+    # Expects a block that will be yield.
+    #
+    # ==== Parameters
+    # raw<true|false(default)> :: if the raw Java node object should be returned or the Ruby wrapped node.
+    #
+    # ==== Example
+    #
+    #   Neo4j.all_nodes{|node| puts "Node id ${node.neo_id"}
+    #
+    def all_nodes(raw = false)
+      iter = instance.all_nodes.iterator
+      while (iter.hasNext)
+        id = iter.next.neo_id
+        yield load_node(id, raw)
+      end
+    end
+
+    # Returns the reference node, which is a "starting point" in the node space.
+    #
+    # Usually, a client attaches relationships to this node that leads into various parts of the node space.
+    # For more information about common node space organizational patterns, see the design guide at http://neo4j.org/doc.
+    #
+    # ==== Returns
+    # The the Neo4j::ReferenceNode
+    #
+    def ref_node
+      @ref_node
+    end
+
+
+    # Returns an event handler.
+    # This event handler can be used for listen to event such as when the Neo4j is started/stopped or
+    # when a node is created/deleted, a property/relationship is changed.
+    #
+    # ==== Returns
+    # a Neo4j::EventHandler instance
+    #
+    def event_handler
+      @event_handler ||= EventHandler.new
+    end
+
+
+    def number_of_nodes_in_use
+      instance.getConfig().getNeoModule().getNodeManager().getNumberOfIdsInUse(org.neo4j.graphdb.Node.java_class)
+    end
+
+    def number_of_relationships_in_use
+      instance.getConfig().getNeoModule().getNodeManager().getNumberOfIdsInUse(org.neo4j.graphdb.Relationship.java_class)
+    end
+
+    def number_of_properties_in_use
+      instance.getConfig().getNeoModule().getNodeManager().getNumberOfIdsInUse(org.neo4j.kernel.impl.nioneo.store.PropertyStore.java_class)
+    end
+
+    # Prints some info about the database
+    def info
+      puts "Neo4j version:                  #{Neo4j::VERSION}"
+      puts "Neo4j db running                #{running?}"
+      puts "number_of_nodes_in_use:         #{number_of_nodes_in_use}"
+      puts "number_of_relationships_in_use: #{number_of_relationships_in_use}"
+      puts "number_of_properties_in_use:    #{number_of_properties_in_use}"
+      puts "neo db storage location:        #{Neo4j::Config[:storage_path]}"
+      puts "lucene index storage location:  #{Lucene::Config[:storage_path]}"
+      puts "keep lucene index in memory:    #{!Lucene::Config[:store_on_file]}"
+    end
+
+  end
+end
+

data/lib/neo4j.old/node.rb

@@ -0,0 +1,49 @@
+module Neo4j
+
+  org.neo4j.kernel.impl.core.NodeProxy.class_eval do
+    include Neo4j::JavaPropertyMixin
+    include Neo4j::JavaNodeMixin
+    include Neo4j::JavaListMixin
+  end
+
+  # A node in the graph with properties and relationships to other entities. 
+  # Along with relationships, nodes are the core building blocks of the Neo4j data representation model. 
+  # Nodes are created by invoking the Neo4j::Node.new method.
+  #
+  # The new method of this class will return a Java org.neo4j.graphdb.Node
+  #
+  # === Included Mixins
+  # * Neo4j::JavaPropertyMixin (operations that deal with relationships)
+  # * Neo4j::JavaNodeMixin (operations that deal with properties
+  # * Neo4j::JavaListMixin (operations that deals with list/timeline relationships)
+  #
+  # (Those mixin are actually not included in the Neo4j::Node but instead directly included in the java class org.neo4j.graphdb.Node)
+  #
+  # See also the Neo4j::NodeMixin if you want to wrap a node with your own Ruby class.
+  #
+  class Node
+    class << self
+      # Returns a org.neo4j.graphdb.Node java object (!)
+      # Will trigger a event that the node was created.
+      # 
+      # === Parameters
+      # *args :: can be a hash of properties to initialize the node with or empty
+      #
+      # === Returns
+      # org.neo4j.graphdb.Node java object
+      #
+      # === Examples
+      #
+      #  Neo4j::Node.new
+      #  Neo4j::Node.new :name => 'foo', :age => 100
+      #
+      def new(*args)
+        node = Neo4j.create_node(args[0] || {})
+        yield node if block_given?
+        Neo4j.event_handler.node_created(node)
+        node
+      end
+    end
+  end
+
+end

data/lib/neo4j.old/reference_node.rb

@@ -0,0 +1,15 @@
+module Neo4j
+
+  # There is only one reference node in a neo space, which can always been found (Neo4j::Neo#:ref_node).
+  # This is a "starting point" in the node space.
+  # Usually, a client attaches relationships to this node that leads into various parts of the node space.
+  # For more information about common node space organizational patterns, see the design guide at http://neo4j.org/doc.
+  #
+  # You can add your own has_n or has_list, has_one relationship to this node.
+  #
+  class ReferenceNode
+    include Neo4j::NodeMixin
+    include Neo4j::MigrationMixin
+  end
+
+end

data/lib/neo4j.old/relationship.rb

@@ -0,0 +1,85 @@
+module Neo4j
+
+  org.neo4j.kernel.impl.core.RelationshipProxy.class_eval do
+    include Neo4j::JavaPropertyMixin
+    include Neo4j::JavaRelationshipMixin
+
+    def end_node # :nodoc:
+      id = getEndNode.getId
+      Neo4j.load_node(id)
+    end
+
+    def start_node # :nodoc:
+      id = getStartNode.getId
+      Neo4j.load_node(id)
+    end
+
+    def other_node(node) # :nodoc:
+      neo_node = node
+      neo_node = node._java_node if node.respond_to?(:_java_node)
+      id = getOtherNode(neo_node).getId
+      Neo4j.load_node(id)
+    end
+  end
+
+  #
+  # A relationship between two nodes in the graph. A relationship has a start node, an end node and a type.
+  # You can attach properties to relationships with the API specified in Neo4j::JavaPropertyMixin.
+  #
+  # Relationship are created by invoking the << operator on the rels method on the node as follow:
+  #  node.rels.outgoing(:friends) << other_node << yet_another_node
+  #
+  # or using the Neo4j::Relationship#new method (which does the same thing):
+  #  rel = Neo4j::Relationship.new(:friends, node, other_node)
+  #
+  # The fact that the relationship API gives meaning to start and end nodes implicitly means that all relationships have a direction.
+  # In the example above, rel would be directed from node to otherNode.
+  # A relationship's start node and end node and their relation to outgoing and incoming are defined so that the assertions in the following code are true:
+  #
+  #   a = Neo4j::Node.new
+  #   b = Neo4j::Node.new
+  #   rel = Neo4j::Relationship.new(:some_type, a, b)
+  #   # Now we have: (a) --- REL_TYPE ---> (b)
+  #
+  #    rel.start_node # => a
+  #    rel.end_node   # => b
+  #
+  # Furthermore, Neo4j guarantees that a relationship is never "hanging freely,"
+  # i.e. start_node, end_node and other_node are guaranteed to always return valid, non-null nodes.
+  #
+  # See also the Neo4j::RelationshipMixin if you want to wrap a relationship with your own Ruby class.
+  #
+  # === Included Mixins
+  # * Neo4j::JavaPropertyMixin
+  # * Neo4j::JavaRelationshipMixin
+  #
+  # (Those mixin are actually not included in the Neo4j::Relationship but instead directly included in the java class org.neo4j.kernel.impl.core.RelationshipProxy)
+  #
+  class Relationship
+    class << self
+      # Returns a org.neo4j.graphdb.Relationship java object (!)
+      # Will trigger a event that the relationship was created.
+      #
+      # === Parameters
+      # type :: the type of relationship
+      # from_node :: the start node of this relationship
+      # end_node  :: the end node of this relationship
+      # props :: optional properties for the created relationship
+      #
+      # === Returns
+      # org.neo4j.graphdb.Relationship java object
+      #
+      # === Examples
+      #
+      #  Neo4j::Relationship.new :friend, node1, node2, :since => '2001-01-02', :status => 'okey'
+      #
+      def new(type, from_node, to_node, props={})
+        Neo4j.create_rel(type, from_node, to_node, props)
+      end
+    end
+
+  end
+
+end
+
+

data/lib/neo4j.old/relationships/decl_relationship_dsl.rb

@@ -0,0 +1,164 @@
+module Neo4j
+
+  module Relationships
+
+    # A DSL for declared relationships has_n and has_one
+    # This DSL will be used to create accessor methods for relationships.
+    # Instead of using the 'raw' Neo4j::NodeMixin#rels method where one needs to know
+    # the name of relationship and direction one can use the generated accessor methods.
+    #
+    # The DSL can also be used to specify a mapping to a Ruby class for a relationship, see Neo4j::Relationships::DeclRelationshipDsl#relationship
+    #
+    # ==== Example
+    #
+    #   class Folder
+    #      include Neo4j::NodeMixin
+    #      property :name
+    #      # Declaring a Many relationship to any other node
+    #      has_n(:files)
+    #    end
+    #
+    #   class File
+    #     include Neo4j::NodeMixin
+    #     # declaring a incoming relationship from Folder's relationship files
+    #     has_one(:folder).from(Folder, :files)
+    #   end
+    #
+    # The following methods will be generated:
+    # <b>Folder#files</b> ::      returns an Enumerable of outgoing nodes for relationship 'files'
+    # <b>Folder#files_rels</b> :: returns an Enumerable of outgoing relationships for relationship 'files'
+    # <b>File#folder</b> ::       for adding one node for the relationship 'files' from the outgoing Folder node
+    # <b>File#folder_rel</b> ::   for accessing relationship 'files' from the outgoing Folder node
+    # <b>File#folder</b> ::       for accessing nodes from relationship 'files' from the outgoing Folder node
+    #
+    class DeclRelationshipDsl
+
+      attr_reader :to_type, :to_class, :cascade_delete_prop_name, :counter, :rel_id
+      CASCADE_DELETE_PROP_NAMES = { :outgoing => :_cascade_delete_outgoing, :incoming => :_cascade_delete_incoming}
+
+      def initialize(rel_id, params)
+        @outgoing = true
+        @rel_id = rel_id
+        @to_type = rel_id
+        @namespace_type = rel_id
+        @cascade_delete_prop_name = CASCADE_DELETE_PROP_NAMES[params[:cascade_delete]]
+        @counter = params[:counter] == true
+      end
+
+      # If a counter was specified in the dsl for counting number of nodes in this relationship.
+      #
+      def counter?
+        @counter
+      end
+
+      # If cascade delete was specified for this relationship
+      #
+      def cascade_delete?
+        !@cascade_delete_prop_name.nil?
+      end
+
+      def class_and_type_from_args(args)  # :nodoc:
+        if (args.size > 1)
+          return args[0], args[1]
+        else
+          return args[0], @rel_id
+        end
+      end
+
+
+      # The actual relationship type that this DSL will use
+      def namespace_type
+        @to_class.nil? ? @to_type.to_s : "#{@to_class.to_s}##{@to_type.to_s}"
+      end
+
+
+      # The direction of the relationships
+      # ==== Returns
+      # <tt>:outgoing::</tt> or <tt>:incoming</tt> 
+      def direction
+        (outgoing?)? :outgoing : :incoming
+      end
+
+      def outgoing?
+        @outgoing
+      end
+
+
+      # Specifies an outgoing relationship.
+      # The name of the outgoing class will be used as a prefix for the relationship used.
+      #
+      # ==== Arguments
+      # clazz:: to which class this relationship goes
+      # relationship:: optional, the relationship to use
+      #
+      # ==== Example
+      #   class FolderNode
+      #     include Neo4j::NodeMixin
+      #     has_n(:files).to(FileNode)
+      #   end
+      #
+      #  folder = FolderNode.new
+      #  # generate a relationship between folder and file of type 'FileNode#files'
+      #  folder.files << FileNode.new
+      #
+      def to(*args)
+        @outgoing = true
+        @to_class, @to_type = class_and_type_from_args(args)
+        self
+      end
+
+      # Specifies an incoming relationship.
+      # Will use the outgoing relationship given by the from class.
+      #
+      # ==== Example
+      #   class FolderNode
+      #     include Neo4j::NodeMixin
+      #     has_n(:files).to(FileNode)
+      #   end
+      #
+      #  class FileNode
+      #    include Neo4j::NodeMixin
+      #    has_one(:folder).from(FileNode, :files)
+      #  end
+      #
+      #  file = FileNode.new
+      #  # create an outgoing relationship of type 'FileNode#files' from folder node to file
+      #  file.folder = FolderNode.new
+      #
+      def from(*args) #(clazz, type)
+        @outgoing = false
+        @to_class, @to_type = class_and_type_from_args(args)
+        self
+      end
+
+      # Specifies which relationship ruby class to use for the relationship
+      #
+      # ==== Example
+      #
+      #   class OrderLine
+      #     include Neo4j::RelationshipMixin
+      #     property :units
+      #     property :unit_price
+      #   end
+      #
+      #   class Order
+      #     property :total_cost
+      #     property :dispatched
+      #     has_n(:products).to(Product).relationship(OrderLine)
+      #   end
+      #
+      #  order = Order.new
+      #  order.products << Product.new
+      #  order.products_rels.first # => OrderLine
+      #
+      def relationship(rel_class)
+        @relationship = rel_class
+        self
+      end
+
+      def relationship_class # :nodoc:
+        @relationship
+      end
+    end
+  end
+end