neo4j-core 0.0.1-java

data/lib/neo4j/neo4j.rb~

@@ -0,0 +1,214 @@
+require 'neo4j-core/database'
+
+# = Neo4j
+#
+# The Neo4j modules is used to interact with an Neo4j Database instance.
+# You can for example start and stop an instance and list all the nodes that exist in the database.
+#
+# === Starting and Stopping Neo4j
+# You don't normally need to start the Neo4j database since it will be automatically started when needed.
+# Before the database is started you should configure where the database is stored, see Neo4j::Config.
+#
+module Neo4j
+
+  # The version of the Neo4j jar files
+  NEO_VERSION = Neo4j::Community::VERSION
+
+  class << self
+    # Start Neo4j using the default database.
+    # This is usally not required since the database will be started automatically when it is used.
+    # If the global variable $NEO4J_SERVER is defined then it will use that as the Java Graph DB. This can
+    # be used if you want to embed neo4j.rb and already got an instance of the Java Neo4j Database service.
+    #
+    # ==== Parameters
+    # config_file :: (optionally) if this is nil or not given use the Neo4j::Config, otherwise setup the Neo4j::Config file using the provided YAML configuration file.
+    # external_db :: (optionally) use this Java Neo4j instead of creating a new neo4j database service
+    def start(config_file=nil, external_db = $NEO4J_SERVER)
+      return if @db && @db.running?
+
+      Neo4j.config.default_file = config_file if config_file
+      if external_db
+        @db ||= Database.new
+        self.db.start_external_db(external_db)
+      else
+        db.start
+      end
+    end
+
+
+    # Sets the Neo4j::Database instance to use
+    # An Neo4j::Database instance wraps both the Neo4j Database and Lucene Database.
+    def db=(my_db)
+      @db = my_db
+    end
+
+    # Returns the database holding references to both the Neo4j Graph Database and the Lucene Database.
+    # Creates a new one if it does not exist, but does not start it.
+    def db
+      @db ||= Neo4j::Core::Database.new
+    end
+
+    def read_only?
+      @db && @db.graph && @db.graph.read_only?
+    end
+
+    # Returns a started db instance. Starts it's not running.
+    # if $NEO4J_SERVER is defined then use that Java Neo4j Database service instead of creating a new one.
+    def started_db
+      start unless db.running?
+      db
+    end
+
+    # Returns the current storage path of a running neo4j database.
+    # If the database is not running it returns nil.
+    def storage_path
+      return nil unless db.running?
+      db.storage_path
+    end
+
+    # Returns the Neo4j::Config class
+    # Same as typing; Neo4j::Config
+    def config
+      Neo4j::Config
+    end
+
+    # Executes a Cypher Query
+    # Check the neo4j http://docs.neo4j.org/chunked/milestone/cypher-query-lang.html
+    # Returns an enumerable of hash values.
+    #
+    # === Usage
+    #
+    #  q = Neo4j.query("START n=node({node}) RETURN n", 'node' => @node.neo_id)
+    #  q.first['n'] #=> the @node
+    #  q.columns.first => 'n'
+    #
+    def query(query, params = {})
+      engine = org.neo4j.cypher.javacompat.ExecutionEngine.new(db)
+      engine.execute(query, params)
+    end
+
+
+    # Returns the logger used by neo4j.
+    # If not specified (with Neo4j.logger=) it will use the standard Ruby logger.
+    # You can change standard logger threshold by configuration :logger_level.
+    #
+    # You can also specify which logger class should take care of logging with the
+    # :logger configuration.
+    #
+    # ==== Example
+    #
+    #  Neo4j::Config[:logger] = Logger.new(STDOUT)
+    #  Neo4j::Config[:logger_level] = Logger::ERROR
+    #
+    def logger
+      @logger ||= Neo4j::Config[:logger] || default_logger
+    end
+
+    # Sets which logger should be used.
+    # If this this is not called then the standard Ruby logger will be used.
+    def logger=(logger)
+      @logger = logger
+    end
+
+    def default_logger #:nodoc:
+      require 'logger'
+      logger = Logger.new(STDOUT)
+      logger.sev_threshold = Neo4j::Config[:logger_level] || Logger::INFO
+      logger
+    end
+
+
+    # Returns an unstarted db instance
+    #
+    # This is typically used for configuring the database, which must sometimes
+    # be done before the database is started
+    # if the database was already started an exception will be raised
+    def unstarted_db
+      @db ||= Database.new
+      raise "database was already started" if @db.running?
+      @db
+    end
+
+    # returns true if the database is running
+    def running?
+      @db && @db.running?
+    end
+
+
+    # Stops this database
+    # There are Ruby hooks that will do this automatically for you.
+    #
+    def shutdown(this_db = @db)
+      this_db.shutdown if this_db
+    end
+
+
+    # Returns the default reference node, which is a "starting point" in the node space.
+    #    
+    def default_ref_node(this_db = self.started_db)
+      this_db.graph.reference_node
+    end
+
+    # Returns the reference node, which is a "starting point" in the node space.
+    # In case the ref_node has been assigned via the threadlocal_ref_node method, then that node will be returned instead.
+    #
+    # 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://wiki.neo4j.org/content/Design_Guide
+    #
+    def ref_node(this_db = self.started_db)
+      return Thread.current[:local_ref_node] if Thread.current[:local_ref_node]
+      default_ref_node(this_db)
+    end
+
+    # Changes the reference node on a threadlocal basis.
+    # This can be used to achieve multitenancy. All new entities will be attached to the new ref_node,
+    # which effectively partitions the graph, and hence scopes traversals.
+    def threadlocal_ref_node=(reference_node)
+      Thread.current[:local_ref_node] = reference_node.nil? ? nil : reference_node._java_node
+    end
+
+    # Returns a Management JMX Bean.
+    #
+    # Notice that this information is also provided by the jconsole Java tool, check http://wiki.neo4j.org/content/Monitoring_and_Deployment
+    # and http://docs.neo4j.org/chunked/milestone/operations-monitoring.html
+    #
+    # By default it returns the Primitivies JMX Bean that can be used to find number of nodes in use.
+    #
+    # ==== Example Neo4j Primititives
+    #
+    #   Neo4j.management.get_number_of_node_ids_in_use
+    #   Neo4j.management.getNumberOfPropertyIdsInUse
+    #   Neo4j.management.getNumberOfRelationshipIdsInUse
+    #   Neo4j.management.get_number_of_relationship_type_ids_in_use
+    #
+    # ==== Example Neo4j HA Cluster Info
+    #
+    # Neo4j.management(org.neo4j.management.HighAvailability).isMaster
+    #
+    # ==== Arguments
+    #
+    # jmx_clazz :: http://api.neo4j.org/current/org/neo4j/management/package-summary.html
+    # this_db :: default currently runnig instance or a newly started neo4j db instance
+    #
+    def management(jmx_clazz = org.neo4j.jmx.Primitives, this_db = self.started_db)
+      this_db.management(jmx_clazz)
+    end
+
+    # Returns an Enumerable object for all nodes in the database
+    def all_nodes(this_db = self.started_db)
+      Enumerator.new(this_db, :each_node)
+    end
+
+    # Same as #all_nodes but does not return wrapped nodes but instead raw java node objects.
+    def _all_nodes(this_db = self.started_db)
+      Enumerator.new(this_db, :_each_node)
+    end
+
+    # Returns the Neo4j::EventHandler
+    #
+    def event_handler(this_db = db)
+      this_db.event_handler
+    end
+
+  end
+end

data/lib/neo4j/node.rb

@@ -0,0 +1,39 @@
+module Neo4j
+  # 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.
+  # Node has three major groups of operations: operations that deal with relationships, operations that deal with properties and operations that traverse the node space.
+  # The property operations give access to the key-value property pairs.
+  # Property keys are always strings. Valid property value types are the primitives (<tt>String</tt>, <tt>Fixnum</tt>, <tt>Float</tt>, <tt>Boolean</tt>), and arrays of those primitives.
+  #
+  # The Neo4j::Node#new method does not return a new Ruby instance (!). Instead it will call the Neo4j Java API which will return a
+  # *org.neo4j.kernel.impl.core.NodeProxy* object. This java object includes the same mixin as this class. The #class method on the java object
+  # returns Neo4j::Node in order to make it feel like an ordinary Ruby object.
+  #
+  class Node
+    extend Neo4j::Core::Node::ClassMethods
+
+    include Neo4j::Core::Property
+    include Neo4j::Core::Rels
+    include Neo4j::Core::Traversal
+    include Neo4j::Core::Equal
+    include Neo4j::Core::Node
+
+    class << self
+
+
+      # This method is used to extend a Java Neo4j class so that it includes the same mixins as this class.
+      def extend_java_class(java_clazz)
+        java_clazz.class_eval do
+          include Neo4j::Core::Property
+          include Neo4j::Core::Rels
+          include Neo4j::Core::Traversal
+          include Neo4j::Core::Equal
+          include Neo4j::Core::Node
+        end
+      end
+    end
+  end
+
+  Neo4j::Node.extend_java_class(Java::OrgNeo4jKernelImplCore::NodeProxy)
+
+end

data/lib/neo4j/relationship.rb

@@ -0,0 +1,61 @@
+module Neo4j
+
+
+  # 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 like Neo4j::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:
+  #
+  # 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-nil nodes.
+  #
+  # === Wrapping
+  #
+  # Notice that the Neo4j::Relationship.new does not create a Ruby object. Instead, it returns a Java
+  # Java::OrgNeo4jGraphdb::Relationship object which has been modified to feel more rubyish (like Neo4j::Node).
+  #
+  # @example
+  #   a = Neo4j::Node.new
+  #   b = Neo4j::Node.new
+  #   rel = Neo4j::Relationship.new(:friends, a, b)
+  #   # Now we have: (a) --- friends ---> (b)
+  #
+  #   rel.start_node # => a
+  #   rel.end_node   # => b
+  #
+  # @example using the << operator on the Neo4j::Node relationship methods
+  #
+  #   node.outgoing(:friends) << other_node << yet_another_node
+  #
+  # @see http://api.neo4j.org/current/org/neo4j/graphdb/Relationship.html
+  #
+  class Relationship
+    extend Neo4j::Core::Relationship::ClassMethods
+    include Neo4j::Core::Property
+    include Neo4j::Core::Equal
+    include Neo4j::Core::Relationship
+
+    # (see Neo4j::Core::Relationship::ClassMethods#new)
+    def initialize(rel_type, start_node, end_node, props={})
+    end
+
+
+    class << self
+      def extend_java_class(java_clazz) #:nodoc:
+        java_clazz.class_eval do
+          include Neo4j::Core::Property
+          include Neo4j::Core::Equal
+          include Neo4j::Core::Relationship
+        end
+      end
+
+      Neo4j::Relationship.extend_java_class(Java::OrgNeo4jKernelImplCore::RelationshipProxy)
+    end
+
+  end
+
+end
+
+

data/lib/neo4j/transaction.rb

@@ -0,0 +1,86 @@
+module Neo4j
+  #
+  # All modifying operations that work with the node space must be wrapped in a transaction. Transactions are thread confined.
+  # Neo4j does not implement true nested transaction, instead it uses flat nested transactions
+  #
+  # @see http://docs.neo4j.org/chunked/milestone/transactions.html
+  class Transaction
+
+    # Acquires a write lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
+    # There is no implementation for this here because it's an java method
+    #
+    # @param [Neo4j::Relationship, Neo4j::Node] java_entity the entity to acquire a lock for. If another transaction currently holds a write lock to that entity this call will wait until it's released.
+    # @return [Java::OrgNeo4jGraphdb::Lock] a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released with the transaction finishes.
+    # @see http://api.neo4j.org/current/org/neo4j/graphdb/Transaction.html#acquireWriteLock(Java::OrgNeo4jGraphdb::PropertyContainer)
+    # @see http://api.neo4j.org/current/org/neo4j/graphdb/Lock.html
+    def acquire_write_lock(java_entity)
+    end
+
+    # Acquires a read lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
+    # There is no implementation for this here because it's an java method
+    # @param [Neo4j::Relationship, Neo4j::Node] java_entity the entity to acquire a lock for. If another transaction currently hold a write lock to that entity this call will wait until it's released.
+    # @return [Java::OrgNeo4jGraphdb::Lock]  a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released with the transaction finishes.
+    # @see http://api.neo4j.org/current/org/neo4j/graphdb/Transaction.html#acquireReadLock(Java::OrgNeo4jGraphdb::PropertyContainer)
+    # @see http://api.neo4j.org/current/org/neo4j/graphdb/Lock.html
+    def acquire_read_lock(java_entity)
+    end
+
+    # Starts a new Neo4j Transaction
+    # @return [Java::OrgNeo4jGraphdb::Transaction] a Java Neo4j Transaction object
+    # @see http://api.neo4j.org/current/org/neo4j/graphdb/Transaction.html
+    #
+    # @example
+    #  tx = Neo4j::Transaction.new
+    #  # modify something
+    #  tx.success
+    #  tx.finish
+    def self.new(instance = Neo4j.started_db)
+      instance.begin_tx
+    end
+
+    # Runs a block in a Neo4j transaction
+    #
+    # Many operations on neo requires an transaction. You will get much better performance if
+    # one transaction is wrapped around several neo operation instead of running one transaction per
+    # neo operation.
+    # If one transaction is already running then a 'placebo' transaction will be created.
+    # Performing a finish on a placebo transaction will not finish the 'real' transaction.
+    #
+    # If an exception occurs inside the block the transaction will rollback automatically.
+    #
+    # @example
+    #
+    #  Neo4j::Transaction.run { node = PersonNode.new }
+    #
+    # @example access to the transaction and rollback
+    #
+    #   Neo4j::Transaction.run do |t|
+    #     # something failed
+    #     t.failure # will cause a rollback
+    #   end
+    #
+    # @yield the block which should be run under one transaction
+    # @yieldparam [Neo4j::Transaction]
+    # @return The value of the evaluated provided block
+    #
+    def self.run
+      raise ArgumentError.new("Expected a block to run in Transaction.run") unless block_given?
+
+      begin
+        tx = Neo4j::Transaction.new
+        ret = yield tx
+        tx.success
+      rescue Exception => e
+        if Neo4j::Config[:debug_java] && e.respond_to?(:cause)
+          puts "Java Exception in a transaction, cause: #{e.cause}"
+          e.cause.print_stack_trace
+        end
+        tx.failure unless tx.nil?
+        raise
+      ensure
+        tx.finish unless tx.nil?
+      end
+      ret
+    end
+  end
+end

data/lib/neo4j/type_converters/type_converters.rb

@@ -0,0 +1,287 @@
+module Neo4j
+
+  # Responsible for converting values from and to Java Neo4j and Lucene.
+  # You can implement your own converter by implementing the method <tt>convert?</tt>
+  # <tt>to_java</tt> and <tt>to_ruby</tt> in this module.
+  #
+  # There are currently three default converters that are triggered when a Time, Date or a DateTime is read or written
+  # if there is a type declared for the property.
+  #
+  # ==== Example
+  #
+  # Example of writing your own marshalling converter:
+  #
+  #  class Foo
+  #     include Neo4j::NodeMixin
+  #     property :thing, :type => MyType
+  #  end
+  #
+  #  module Neo4j::TypeConverters
+  #    class MyTypeConverter
+  #      class << self
+  #        def convert?(type)
+  #          type == MyType
+  #        end
+  #
+  #        def to_java(val)
+  #          "silly:#{val}"
+  #        end
+  #
+  #        def to_ruby(val)
+  #          val.sub(/silly:/, '')
+  #        end
+  #      end
+  #    end
+  #  end
+  #
+  module TypeConverters
+
+    # The default converter to use if there isn't a specific converter for the type
+    class DefaultConverter
+      class << self
+
+        def to_java(value)
+          value
+        end
+
+        def to_ruby(value)
+          value
+        end
+      end
+    end
+
+
+    class BooleanConverter
+      class << self
+
+        def convert?(class_or_symbol)
+          :boolean == class_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          !!value && value != '0'
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          !!value && value != '0'
+        end
+      end
+    end
+
+    class SymbolConverter
+      class << self
+
+        def convert?(class_or_symbol)
+          :symbol == class_or_symbol || Symbol == class_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          value.to_s
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          value.to_sym
+        end
+      end
+    end
+
+
+    class StringConverter
+      class << self
+
+        def convert?(class_or_symbol)
+          [String, :string, :text].include? class_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          value.to_s
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          value.to_s
+        end
+      end
+    end
+
+
+
+    class FixnumConverter
+      class << self
+
+        def convert?(class_or_symbol)
+          Fixnum == class_or_symbol || :fixnum == class_or_symbol || :numeric == class_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          value.to_i
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          value.to_i
+        end
+      end
+    end
+
+    class FloatConverter
+      class << self
+
+        def convert?(clazz_or_symbol)
+          Float == clazz_or_symbol || :float == clazz_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          value.to_f
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          value.to_f
+        end
+      end
+    end
+
+    # Converts Date objects to Java long types. Must be timezone UTC.
+    class DateConverter
+      class << self
+
+        def convert?(clazz_or_symbol)
+          Date == clazz_or_symbol || :date == clazz_or_symbol
+        end
+
+        def to_java(value)
+          return nil if value.nil?
+          Time.utc(value.year, value.month, value.day).to_i
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          Time.at(value).utc.to_date
+        end
+      end
+    end
+
+    # Converts DateTime objects to and from Java long types. Must be timezone UTC.
+    class DateTimeConverter
+      class << self
+
+        def convert?(clazz_or_symbol)
+          DateTime == clazz_or_symbol || :datetime == clazz_or_symbol
+        end
+
+        # Converts the given DateTime (UTC) value to an Fixnum.
+        # Only utc times are supported !
+        def to_java(value)
+          return nil if value.nil?
+          if value.class == Date
+            Time.utc(value.year, value.month, value.day, 0, 0, 0).to_i
+          else
+            Time.utc(value.year, value.month, value.day, value.hour, value.min, value.sec).to_i
+          end
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          t = Time.at(value).utc
+          DateTime.civil(t.year, t.month, t.day, t.hour, t.min, t.sec)
+        end
+      end
+    end
+
+    class TimeConverter
+      class << self
+
+        def convert?(clazz_or_symbol)
+          Time == clazz_or_symbol || :time == clazz_or_symbol
+        end
+
+        # Converts the given DateTime (UTC) value to an Fixnum.
+        # Only utc times are supported !
+        def to_java(value)
+          return nil if value.nil?
+          if value.class == Date
+            Time.utc(value.year, value.month, value.day, 0, 0, 0).to_i
+          else
+            value.utc.to_i
+          end
+        end
+
+        def to_ruby(value)
+          return nil if value.nil?
+          Time.at(value).utc
+        end
+      end
+    end
+
+    class << self
+
+      # Mostly for testing purpose, You can use this method in order to
+      # add a converter while the neo4j has already started.
+      def converters=(converters)
+        @converters = converters
+      end
+      
+      # Always returns a converter that handles to_ruby or to_java
+      # if +enforce_type+ is set to false then it will raise in case of unknown type
+      # otherwise it will return the DefaultConverter.
+      def converter(type = nil, enforce_type = true)
+        return DefaultConverter unless type
+        @converters ||= begin
+          Neo4j::TypeConverters.constants.find_all do |c|
+            Neo4j::TypeConverters.const_get(c).respond_to?(:convert?)
+          end.map do  |c|
+            Neo4j::TypeConverters.const_get(c)
+          end
+        end
+        found = @converters.find {|c| c.convert?(type) }
+        raise "The type #{type.inspect} is unknown. Use one of #{@converters.map{|c| c.name }.join(", ")} or create a custom type converter." if !found && enforce_type
+        found or DefaultConverter
+      end
+
+      # Converts the given value to a Java type by using the registered converters.
+      # It just looks at the class of the given value unless an attribute name is given.
+      def convert(value, attribute = nil, klass = nil, enforce_type = true)
+        converter(attribute_type(value, attribute, klass), enforce_type).to_java(value)
+      end
+
+      # Converts the given property (key, value) to Java if there is a type converter for given type.
+      # The type must also be declared using Neo4j::NodeMixin#property property_name, :type => clazz
+      # If no Converter is defined for this value then it simply returns the given value.
+      def to_java(clazz, key, value)
+        type = clazz._decl_props[key.to_sym] && clazz._decl_props[key.to_sym][:type]
+        converter(type).to_java(value)
+      end
+
+      # Converts the given property (key, value) to Ruby if there is a type converter for given type.
+      # If no Converter is defined for this value then it simply returns the given value.
+      def to_ruby(clazz, key, value)
+        type = clazz._decl_props[key.to_sym] && clazz._decl_props[key.to_sym][:type]
+        converter(type).to_ruby(value)
+      end
+
+      private
+      def attribute_type(value, attribute = nil, klass = nil)
+        type = (attribute && klass) ? attribute_type_from_attribute_and_klass(value, attribute, klass) : nil
+        type || attribute_type_from_value(value)
+      end
+
+      def attribute_type_from_attribute_and_klass(value, attribute, klass)
+        if klass.respond_to?(:_decl_props)
+          (klass._decl_props.has_key?(attribute) && klass._decl_props[attribute][:type]) ? klass._decl_props[attribute][:type] : nil
+        end
+      end
+
+      def attribute_type_from_value(value)
+        value.class
+      end
+    end
+  end
+end