neography 0.0.31 → 1.0.0

data/.gitignore

@@ -1,3 +1,4 @@
+Gemfile.lock
 .idea
 *.iml
 neo4j
@@ -5,3 +6,5 @@ pkg/*
 *.gem
 .bundle
 log/*
+.rvmrc
+Gemfile.lock

data/.travis.yml

@@ -1,4 +1,4 @@
-script: "bundle exec rake neo4j:install['enterprise','1.8.M06'] neo4j:start spec --trace"
+script: "bundle exec rake neo4j:install['enterprise','1.8'] neo4j:start spec --trace"
 language: ruby
 rvm:
   - 1.9.3

data/CONTRIBUTORS

@@ -14,4 +14,5 @@ Contributors:
 * Nick Reavill
 * Marcel Sherf
 * David Pitman
-* Garrett Heaver
+* Garrett Heaver
+* Roel van Dijk

data/README.md

@@ -0,0 +1,247 @@
+[![Build Status](https://secure.travis-ci.org/maxdemarzi/neography.png?branch=master)](http://travis-ci.org/maxdemarzi/neography)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/maxdemarzi/neography)
+
+## Welcome to Neography 
+
+Neography is a thin Ruby wrapper to the Neo4j Rest API, for more information:
+
+* [Getting Started with Neo4j Server](http://neo4j.org/community/)
+* [Neo4j Rest API Reference](http://docs.neo4j.org/chunked/milestone/rest-api.html)
+
+If you want to the full power of Neo4j, you will want to use JRuby and the excellent Neo4j.rb gem at https://github.com/andreasronge/neo4j by Andreas Ronge
+
+
+## Installation
+
+### Gemfile
+
+Add `neography` to your Gemfile:
+
+```ruby
+gem 'neography'
+```
+
+And run Bundler:
+
+```sh
+$ bundle
+```
+
+### Manually:
+
+Or install `neography` manually:
+
+```sh
+$ gem install 'neography'
+```
+
+And require the gem in your Ruby code:
+
+```ruby
+require 'rubygems'
+require 'neography'
+```
+
+Read the wiki for information about [dependencies](https://github.com/maxdemarzi/neography/wiki/Dependencies).
+
+[Rake tasks](https://github.com/maxdemarzi/neography/wiki/Rake-tasks) are available for downloading, installing and running Neo4j.
+
+
+## Usage
+
+### Configuration and initialization
+
+Configure Neography as follows:
+
+```ruby
+# these are the default values:
+Neography.configure do |config|
+  config.protocol       = "http://"
+  config.server         = "localhost"
+  config.port           = 7474
+  config.directory      = ""  # prefix this path with '/' 
+  config.cypher_path    = "/cypher"
+  config.gremlin_path   = "/ext/GremlinPlugin/graphdb/execute_script"
+  config.log_file       = "neography.log"
+  config.log_enabled    = false
+  config.max_threads    = 20
+  config.authentication = nil  # 'basic' or 'digest'
+  config.username       = nil
+  config.password       = nil
+  config.parser         = {:parser => MultiJsonParser}
+end
+```
+
+Then initialize a `Rest` instance:
+
+```ruby
+@neo = Neography::Rest.new
+```
+
+For overriding these default and other initialization methods, see the
+[configuration and initialization](https://github.com/maxdemarzi/neography/wiki/Configuration-and-initialization) page in the Wiki.
+
+
+### REST API
+
+Neography supports the creation and retrieval of nodes and relationships through the Neo4j REST interface.
+It supports indexes, Gremlin scripts, Cypher queries and batch operations.
+
+Some of this functionality is shown here, but all of it is explained in the following Wiki pages:
+
+* [Nodes](https://github.com/maxdemarzi/neography/wiki/Nodes) - Create, get and delete nodes.
+* [Node properties](https://github.com/maxdemarzi/neography/wiki/Node-properties) - Set, get and remove node properties.
+* [Node relationships](https://github.com/maxdemarzi/neography/wiki/Node-relationships) - Create and get relationships between nodes.
+* [Relationship](https://github.com/maxdemarzi/neography/wiki/Relationships) - Get and delete relationships.
+* [Relationship properties](https://github.com/maxdemarzi/neography/wiki/Relationship-properties) - Create, get and delete relationship properties.
+* [Node indexes](https://github.com/maxdemarzi/neography/wiki/Node-indexes) - List and create node indexes. Add, remove, get and search nodes in indexes.
+* [Relationship indexes](https://github.com/maxdemarzi/neography/wiki/Relationship-indexes) - List and create relationships indexes. Add, remove, get and search relationships in indexes.
+* [Auto indexes](https://github.com/maxdemarzi/neography/wiki/Auto-indexes) - Get, set and remove auto indexes.
+* [Scripts and queries](https://github.com/maxdemarzi/neography/wiki/Scripts-and-queries) - Run Gremlin scripts and Cypher queries.
+* [Paths and traversal](https://github.com/maxdemarzi/neography/wiki/Paths-and-traversal) - Paths between nodes and path traversal.
+* [Batch](https://github.com/maxdemarzi/neography/wiki/Batch) - Execute multiple calls at once.
+* [Errors](https://github.com/maxdemarzi/neography/wiki/Errors) - Errors raised if REST API calls fail.
+
+
+Some example usage:
+
+```ruby
+# Node creation:
+node1 = @neo.create_node("age" => 31, "name" => "Max")
+node2 = @neo.create_node("age" => 33, "name" => "Roel")
+
+# Node properties:
+@neo.set_node_properties(node1, {"weight" => 200})
+
+# Relationships between nodes:
+@neo.create_relationship("coding_buddies", node1, node2)
+
+# Get node relationships:
+@neo.get_node_relationships(node2, "in", "coding_buddies")
+
+# Use indexes:
+@neo.add_node_to_index("people", "name", "max", node1)
+@neo.get_node_index("people", "name", "max")
+
+# Cypher queries:
+@neo.execute_query("start n=node(0) return n")
+
+# Batches:
+@neo.batch [:create_node, {"name" => "Max"}],
+           [:create_node, {"name" => "Marc"}]
+```
+
+This is just a small sample of the full API, see the [Wiki documentation](https://github.com/maxdemarzi/neography/wiki) for the full API.
+
+Neography raises REST API errors as Ruby errors, see the wiki page about [errors](https://github.com/maxdemarzi/neography/wiki/Errors).
+(**Note**: older versions of Neography did not raise any errors!)
+
+
+## *Phase 2*
+
+Trying to mimic the [Neo4j.rb API](https://github.com/andreasronge/neo4j/wiki/Neo4j%3A%3ACore-Nodes-Properties-Relationships).
+
+Now we are returning full objects. The properties of the node or relationship can be accessed directly (`node.name`).
+The Neo4j ID is available by using `node.neo_id`.
+
+Some of this functionality is shown here, but all of it is explained in the following Wiki pages:
+
+* [Nodes](https://github.com/maxdemarzi/neography/wiki/Phase-2-Nodes) - Create, load and delete nodes.
+* [Node properties](https://github.com/maxdemarzi/neography/wiki/Phase-2-Node-properties) - Add, get and remove node properties.
+* [Node relationships](https://github.com/maxdemarzi/neography/wiki/Phase-2-Node-relationships) - Create and retrieve node relationships.
+* [Node paths](https://github.com/maxdemarzi/neography/wiki/Phase-2-Node-paths) - Gets paths between nodes.
+
+
+```ruby
+# create two nodes:
+n1 = Neography::Node.create("age" => 31, "name" => "Max")
+n2 = Neography::Node.create("age" => 33, "name" => "Roel")
+
+n1.exist? # => true
+
+# get and change some properties:
+n1[:age]         # => 31
+n1.name          # => "Max"
+n1[:age]  = 32   # change property
+n1.weight = 190  # new property
+n1.age    = nil  # remove property
+
+# add a relationship between nodes:
+new_rel = Neography::Relationship.create(:coding_buddies, n1, n2)
+
+# remove a relationship:
+new_rel.del
+
+# add a relationship on nodes:
+n1.outgoing(:coding_buddies) << n2
+
+# more advanced relationship traversal:
+n1.outgoing(:friends)                                                # Get nodes related by outgoing friends relationship
+n1.outgoing(:friends).depth(2).include_start_node                    # Get n1 and nodes related by friends and friends of friends
+
+n1.rel?(:outgoing, :friends)                                         # Has outgoing friends relationship
+n1.rels(:friends,:work).outgoing                                     # Get outgoing friends and work relationships
+
+n1.all_paths_to(n2).incoming(:friends).depth(4)                      # Gets all paths of a specified type
+n1.shortest_path_to(n2).incoming(:friends).depth(4).nodes            # Gets just nodes in path
+```
+
+This is just a small sample of the full API, see the [Wiki documentation](https://github.com/maxdemarzi/neography/wiki) for the full API.
+
+## More
+
+### Examples
+
+Some [example code](https://github.com/maxdemarzi/neography/wiki/Examples).
+
+
+### Testing
+
+Some [tips about testing](https://github.com/maxdemarzi/neography/wiki/Testing).
+
+
+### Related Neo4j projects
+
+Complement to Neography are the:
+
+* [Neo4j Active Record Adapter](https://github.com/yournextleap/activerecord-neo4j-adapter) by Nikhil Lanjewar
+* [Neology](https://github.com/lordkada/neology) by Carlo Alberto Degli Atti
+* [Neoid](https://github.com/elado/neoid) by Elad Ossadon
+
+An alternative to Neography is [Architect4r](https://github.com/namxam/architect4r) by Maximilian Schulz
+
+
+### Neography in the Wild
+
+* [Vouched](http://getvouched.com)
+* [Neovigator](http://neovigator.herokuapp.com) fork it at https://github.com/maxdemarzi/neovigator
+* [Neoflix](http://neoflix.herokuapp.com) fork it at  https://github.com/maxdemarzi/neoflix
+
+
+### Getting started with Neography
+
+* [Getting Started with Ruby and Neo4j](http://maxdemarzi.com/2012/01/04/getting-started-with-ruby-and-neo4j/)
+* [Graph visualization with Neo4j](http://maxdemarzi.com/2012/01/11/graph-visualization-and-neo4j/)
+* [Neo4j on Heroku](http://maxdemarzi.com/2012/01/13/neo4j-on-heroku-part-one/)
+
+
+## Contributing
+
+Please create a [new issue](https://github.com/maxdemarzi/neography/issues) if you run into any bugs.
+
+Contribute patches via [pull requests](https://github.com/maxdemarzi/neography/pulls).
+
+
+## Help
+
+If you are just starting out, or need help send me an e-mail at maxdemarzi@gmail.com.
+
+Check you my blog at http://maxdemarzi.com where I have more Neography examples.
+
+
+## Licenses
+
+* Neography - MIT, see the LICENSE file http://github.com/maxdemarzi/neography/tree/master/LICENSE.
+* Lucene -  Apache, see http://lucene.apache.org/java/docs/features.html
+* Neo4j - Dual free software/commercial license, see http://neo4j.org
+

data/Rakefile

@@ -6,10 +6,9 @@ require 'neography/tasks'
 
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = "--color"
-  t.pattern = "spec/integration/*_spec.rb"
+  t.pattern = "spec/**/*_spec.rb"
 end
 
 desc "Run Tests"
 task :default => :spec
 
-

data/lib/neography/config.rb

@@ -1,20 +1,52 @@
 module Neography
-  class Config 
-    class << self; attr_accessor :protocol, :server, :port, :directory, :cypher_path, :gremlin_path, :log_file, :log_enabled, :logger, :max_threads, :authentication, :username, :password, :parser end
+  class Config
+
+    attr_accessor :protocol, :server, :port, :directory,
+      :cypher_path, :gremlin_path,
+      :log_file, :log_enabled,
+      :max_threads,
+      :authentication, :username, :password,
+      :parser
+
+    def initialize
+      set_defaults
+    end
+
+    def to_hash
+      {
+        :protocol       => @protocol,
+        :server         => @server,
+        :port           => @port,
+        :directory      => @directory,
+        :cypher_path    => @cypher_path,
+        :gremlin_path   => @gremlin_path,
+        :log_file       => @log_file,
+        :log_enabled    => @log_enabled,
+        :max_threads    => @max_threads,
+        :authentication => @authentication,
+        :username       => @username,
+        :password       => @password,
+        :parser         => @parser
+      }
+    end
+
+    private
+
+    def set_defaults
+      @protocol       = "http://"
+      @server         = "localhost"
+      @port           = 7474
+      @directory      = ""
+      @cypher_path    = "/cypher"
+      @gremlin_path   = "/ext/GremlinPlugin/graphdb/execute_script"
+      @log_file       = "neography.log"
+      @log_enabled    = false
+      @max_threads    = 20
+      @authentication = nil
+      @username       = nil
+      @password       = nil
+      @parser         = {:parser => MultiJsonParser}
+    end
 
-    @protocol       = 'http://'
-    @server         = 'localhost'
-    @port           = 7474 
-    @directory      = ''
-    @cypher_path    = '/cypher'
-    @gremlin_path   = '/ext/GremlinPlugin/graphdb/execute_script'
-    @log_file       = 'neography.log'
-    @log_enabled    = false
-    @logger         = Logger.new(@log_file) if @log_enabled
-    @max_threads    = 20
-    @authentication = {}
-    @username       = nil
-    @password       = nil
-    @parser         = {:parser => MultiJsonParser}
   end
 end

data/lib/neography/connection.rb

@@ -0,0 +1,151 @@
+module Neography
+  class Connection
+
+    USER_AGENT = "Neography/#{Neography::VERSION}"
+
+    attr_accessor :protocol, :server, :port, :directory,
+      :cypher_path, :gremlin_path,
+      :log_file, :log_enabled, :logger,
+      :max_threads,
+      :authentication, :username, :password,
+      :parser
+
+    def initialize(options = ENV['NEO4J_URL'] || {})
+      config = merge_configuration(options)
+      save_local_configuration(config)
+    end
+
+    def configure(protocol, server, port, directory)
+      @protocol = protocol
+      @server = server
+      @port = port
+      @directory = directory
+    end
+
+    def configuration
+      "#{@protocol}#{@server}:#{@port}#{@directory}/db/data"
+    end
+
+    def merge_options(options)
+      merged_options = options.merge!(@authentication).merge!(@parser)
+      merged_options[:headers].merge!(@user_agent) if merged_options[:headers]
+      merged_options
+    end
+
+    def get(path, options={})
+      evaluate_response(HTTParty.get(configuration + path, merge_options(options)))
+    end
+
+    def post(path, options={})
+      evaluate_response(HTTParty.post(configuration + path, merge_options(options)))
+    end
+
+    def put(path, options={})
+      evaluate_response(HTTParty.put(configuration + path, merge_options(options)))
+    end
+
+    def delete(path, options={})
+      evaluate_response(HTTParty.delete(configuration + path, merge_options(options)))
+    end
+
+    private
+
+    def merge_configuration(options)
+      options = parse_string_options(options) unless options.is_a? Hash
+      config = Neography.configuration.to_hash
+      config.merge(options)
+    end
+
+    def save_local_configuration(config)
+      @protocol       = config[:protocol]
+      @server         = config[:server]
+      @port           = config[:port]
+      @directory      = config[:directory]
+      @cypher_path    = config[:cypher_path]
+      @gremlin_path   = config[:gremlin_path]
+      @log_file       = config[:log_file]
+      @log_enabled    = config[:log_enabled]
+      @max_threads    = config[:max_threads]
+      @parser         = config[:parser]
+
+      @user_agent     = { "User-Agent" => USER_AGENT }
+
+      @authentication = {}
+      if config[:authentication]
+        @authentication = {
+          "#{config[:authentication]}_auth".to_sym => {
+            :username => config[:username],
+            :password => config[:password]
+          }
+        }
+      end
+
+      if @log_enabled
+        @logger = Logger.new(@log_file)
+      end
+    end
+
+    def evaluate_response(response)
+      code = response.code
+      body = response.body
+      case code
+      when 200
+        @logger.debug "OK" if @log_enabled
+        response.parsed_response
+      when 201
+        @logger.debug "OK, created #{body}" if @log_enabled
+        response.parsed_response
+      when 204
+        @logger.debug "OK, no content returned" if @log_enabled
+        nil
+      when 400...500
+        handle_4xx_response(code, body)
+        nil
+      end
+    end
+
+    def handle_4xx_response(code, body)
+      parsed_body = JSON.parse(body)
+      message = parsed_body["message"]
+      stacktrace = parsed_body["stacktrace"]
+
+      @logger.error "#{code} error: #{body}" if @log_enabled
+
+      case code
+      when 400, 404
+        case parsed_body["exception"]
+        when "SyntaxException"               ; raise SyntaxException.new(message, code, stacktrace)
+        when "PropertyValueException"        ; raise PropertyValueException.new(message, code, stacktrace)
+        when "BadInputException"             ; raise BadInputException.new(message, code, stacktrace)
+        when "NodeNotFoundException"         ; raise NodeNotFoundException.new(message, code, stacktrace)
+        when "NoSuchPropertyException"       ; raise NoSuchPropertyException.new(message, code, stacktrace)
+        when "RelationshipNotFoundException" ; raise RelationshipNotFoundException.new(message, code, stacktrace)
+        when "NotFoundException"             ; raise NotFoundException.new(message, code, stacktrace)
+        else
+          raise NeographyError.new(message, code, stacktrace)
+        end
+      when 401
+        raise UnauthorizedError.new(message, code, stacktrace)
+      when 409
+        raise OperationFailureException.new(message, code, stacktrace)
+      else
+        raise NeographyError.new(message, code, stacktrace)
+      end
+    end
+
+    def parse_string_options(options)
+      url = URI.parse(options)
+      options = {
+        :protocol  => url.scheme + "://",
+        :server    => url.host,
+        :port      => url.port,
+        :directory => url.path,
+        :username  => url.user,
+        :password  => url.password
+      }
+      options[:authentication] = 'basic' unless url.user.nil?
+      options
+    end
+
+  end
+end

data/lib/neography/errors.rb

@@ -0,0 +1,42 @@
+module Neography
+
+  class NeographyError < StandardError
+    attr_reader :message, :code, :stacktrace
+
+    def initialize(message = nil, code = nil, stacktrace = nil)
+      @message    = message
+      @code       = code
+      @stacktrace = stacktrace
+    end
+  end
+
+  # HTTP Authentication error
+  class UnauthorizedError < NeographyError; end
+
+  # the Neo4j server Exceptions returned by the REST API:
+
+  # A node could not be found
+  class NodeNotFoundException < NeographyError; end
+
+  # A node cannot be deleted because it has relationships
+  class OperationFailureException < NeographyError; end
+
+  # Properties can not be null
+  class PropertyValueException < NeographyError; end
+
+  # Trying to a delete a property that does not exist
+  class NoSuchPropertyException < NeographyError; end
+
+  # A relationship could not be found
+  class RelationshipNotFoundException < NeographyError; end
+
+  # Error during valid Cypher query
+  class BadInputException < NeographyError; end
+
+  # Invalid Cypher query syntax
+  class SyntaxException < NeographyError; end
+
+  # A path could not be found by node traversal
+  class NotFoundException < NeographyError; end
+
+end

data/lib/neography/node.rb

@@ -9,24 +9,22 @@ module Neography
     attr_accessor :neo_server
 
     class << self
-      def create(*args)
-        # the arguments can be an hash of properties to set or a rest instance
-        props = (args[0].respond_to?(:each_pair) && args[0]) || args[1]
-        db = (args[0].is_a?(Neography::Rest) && args[0]) || args[1] || Neography::Rest.new
+      def create(props = nil, db = Neography::Rest.new)
+        raise ArgumentError.new("syntax deprecated") if props.is_a?(Neography::Rest)
+
         node = self.new(db.create_node(props))
         node.neo_server = db
         node
       end
 
-      def load(*args)
-        # the first argument can be an hash of properties to set
-        node = !args[0].is_a?(Neography::Rest) && args[0] || args[1]
+      def load(node, db = Neography::Rest.new)
+        raise ArgumentError.new("syntax deprecated") if node.is_a?(Neography::Rest)
 
-        # a db instance can be given, it is the first argument or the second
-        db = (args[0].is_a?(Neography::Rest) && args[0]) || args[1] || Neography::Rest.new
         node = db.get_node(node)
-        node = self.new(node) unless node.nil?
-        node.neo_server = db unless node.nil?
+        if node
+          node = self.new(node)
+          node.neo_server = db
+        end
         node
       end
 
@@ -34,12 +32,17 @@ module Neography
     end
 
     def del
-      self.neo_server.delete_node!(self.neo_id)
+      neo_server.delete_node!(self.neo_id)
     end
 
     def exist?
-      !self.neo_server.get_node(self.neo_id).nil?
+      begin
+        neo_server.get_node(self.neo_id)
+        true
+      rescue NodeNotFoundException
+        false
+      end
     end
 
   end
-end
+end

data/lib/neography/node_relationship.rb

@@ -1,6 +1,8 @@
 module Neography
   module NodeRelationship
 
+    DIRECTIONS = ["incoming", "in", "outgoing", "out", "all", "both"]
+
     def outgoing(types=nil)
       NodeTraverser.new(self).outgoing(types)
     end
@@ -32,4 +34,4 @@ module Neography
     end
 
   end
-end
+end