neo4j_ancestry 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 41f4f1d28904e2ce9f72234d37fa139a1d3145ba
+  data.tar.gz: 172c0d6e21aa0053312c9a2ccdbd9bd3ae205ba5
+SHA512:
+  metadata.gz: 8ef1393a7263e2bf86610d6e7f37e8ce74c62a7c2bbcae3d3de58328346b065328bd61c5242605d1250c75115239fb23acb2dea3c53f49fa810198e9ba306f54
+  data.tar.gz: c30f176d2e86e34cce179ed68fa0783b6b3b62bdd79e4d2b41f24d09b26a0b33e550968d52e001ef0a284d6b7b946127ef6312301b8f2cdefa17eff30447cb5a

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# neo4j database of the dummy app
+spec/dummy-rails4/db/neo4j
+spec/dummy-rails3/db/neo4j
+spec/dummy-rails4/neo4j
+spec/dummy-rails3/neo4j

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+gemfile:
+  - rails3.2.Gemfile
+  - rails4.Gemfile
+before_script:
+  - bundle exec rake neo4j_ancestry:db:test:prepare
+after_script:
+  - bundle exec rake neo4j:stop

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Neo4jAncestry Changelog
+
+* v0.0.1 - Initial Release with basic functionality.
+ * Rake tasks for installation and setup of neo4j.
+ * Basic traversing methods, such as `parents`, `children`, `ancestors`, `descendants`, `siblings`.

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Testing for Rails 4
+gem 'rails', '~> 4'
+
+# Specify your gem's dependencies in neo4j_ancestry.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,24 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cli: "--color" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml|\.slim)$})          { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara features specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml|slim)$})     { |m| "spec/features/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Sebastian Fiedlschuster
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# Neo4jAncestry 
+
+[![Build Status](https://travis-ci.org/fiedl/neo4j_ancestry.png?branch=master)](https://travis-ci.org/fiedl/neo4j_ancestry)
+
+This ruby on rails gem makes it easy to store polymorphic structure information --- `parents`, `children`, `ancestors`, `descendants`, ... --- in a [neo4j graph database](http://www.neo4j.org) parallel to using ActiveRecord.
+
+All relevant information is stored in your default ActiveRecord database, including the parent-child relationships. But, in addition, the structure information is also stored in a neo4j graph database in order to use its power of fast graph traversing queries.
+
+## Usage
+
+TODO: Write usage instructions here
+
+
+## Installation
+
+Add the gem to your application's `Gemfile`:
+
+    # Gemfile
+    # ...
+    gem 'neo4j_ancestry'
+
+And then execute:
+
+    # bash
+    bundle install
+
+  Install the neo4j database `db` directory and start the deamon:
+
+    # bash
+    bundle exec rake neo4j:install neo4j:setup neo4j:start
+    
+Next, migrate the database in order to add the neccessary tables.
+
+    # bash
+    bundle exec rake neo4j_ancestry:install:migrations
+    bundle exec rake db:migrate
+    
+
+## Underlying Technology
+
+* The [neo4j graph database](http://www.neo4j.org)
+* The [neography gem](https://github.com/maxdemarzi/neography) is used as datbase interface.
+* The [neoid gem](https://github.com/elado/neoid) is used for database abstraction in parallel to ActiveRecord.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### Running the Gem's Specs Locally
+
+Symlink the `Gemfile` according to the Rails version you would like to use:
+
+    # bash
+    rm Gemfile Gemfile.lock
+    ln -s rails3.2.Gemfile Gemfile   # for Rails 3
+    ln -s rails4.Gemfile Gemfile     # for Rails 4  (default)
+
+Next, install the dependencies and run the specs.
+
+    # bash
+    bundle install
+    bundle exec rake neo4j_ancestry:db:test:prepare
+    bundle exec rake
+
+## Author, License
+
+(c) 2013, Sebastian Fiedlschuster
+
+Released under the [MIT License](./MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,15 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require "bundler/gem_tasks"
+Bundler::GemHelper.install_tasks
+
+load "lib/tasks/db_test_prepare.rake"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/config/initializers/001_neo4j.rb

@@ -0,0 +1,39 @@
+# This initializers estableshes the connection to the neo4j graph database.
+# The settings for this connection are stored in 
+# 
+#    # TODO
+#
+# For further information how this connection works, have a look at:
+# 
+#    https://github.com/elado/neoid#usage
+#
+
+if Rails.env.development?
+  neo4j_url = "http://localhost:7474"
+elsif Rails.env.test?
+  neo4j_url = "http://localhost:7574"
+elsif Rails.env.production?
+  raise 'TODO: read the neo4j server connection from config file.'
+end
+
+uri = URI.parse(neo4j_url)
+
+$neo = Neography::Rest.new(uri.to_s)
+
+Neography.configure do |c|
+  c.server = uri.host
+  c.port = uri.port
+
+  if uri.user && uri.password
+    c.authentication = 'basic'
+    c.username = uri.user
+    c.password = uri.password
+  end
+end
+
+Neoid.db = $neo
+
+Neoid.configure do |c|
+  # should Neoid create sub-reference from the ref node (id#0) to every node-model? default: true
+  c.enable_subrefs = false
+end

data/db/migrate/20131102235736_create_links.rb

@@ -0,0 +1,10 @@
+class CreateLinks < ActiveRecord::Migration
+  def change
+    create_table :neo4j_ancestry_links do |t|
+      t.integer :parent_id
+      t.string :parent_type
+      t.integer :child_id
+      t.string :child_type
+    end
+  end
+end

data/lib/models/neo4j_ancestry/active_record_additions.rb

@@ -0,0 +1,111 @@
+module Neo4jAncestry
+  module ActiveRecordAdditions
+    require 'neo4j_ancestry/railtie' if defined?(Rails)
+    
+    # Example options:
+    #   parent_class_names: %w(Group), 
+    #   child_class_names: %w(Group User)
+    #
+    def has_neo4j_ancestry(options)
+      
+      link_class_name = 'Neo4jAncestry::Link'
+      
+      # Links (direct relationships between objects) are stored
+      # via ActiveRecord in the mysql database. (The neo4j database contains only 
+      # redundant information and is used for fast queries.)
+      #
+      has_many :links_as_parent, foreign_key: :parent_id, class_name: link_class_name
+      has_many :links_as_child, foreign_key: :child_id, class_name: link_class_name
+      
+      parent_class_names = options[:parent_class_names] || []
+      child_class_names = options[:child_class_names] || []
+      
+      # links_as_child for specific parent object classes and
+      # links_as_parent for specific child object classes, e.g.
+      #   group.links_as_child_for_groups
+      #   group.links_as_parent_for_groups
+      #   group.links_as_parent_for_users
+      #
+      parent_class_names.each do |parent_class_name|
+        has_many_for_rails_3_and_4(
+          "links_as_child_for_#{parent_class_name.underscore.pluralize}".to_sym,
+          { parent_type: parent_class_name },
+          { as: :child, class_name: link_class_name } )
+      end
+      child_class_names.each do |child_class_name|
+        has_many_for_rails_3_and_4( 
+          "links_as_parent_for_#{child_class_name.underscore.pluralize}".to_sym, 
+          { child_type: child_class_name },
+          { as: :parent, class_name: link_class_name } )
+      end
+      
+      # parent and child associations for specific object classes, e.g.
+      #   group.parent_groups
+      #   group.child_groups
+      #   group.child_users
+      #
+      parent_class_names.each do |parent_class_name|
+        has_many( 
+          "parent_#{parent_class_name.underscore.pluralize}".to_sym, 
+          through: "links_as_child_for_#{parent_class_name.underscore.pluralize}".to_sym, 
+          as: :structureable, 
+          foreign_key: :parent_id, source: 'parent', 
+          source_type: parent_class_name )
+      end
+      child_class_names.each do |child_class_name|
+        has_many( 
+          "child_#{child_class_name.underscore.pluralize}".to_sym, 
+          through: "links_as_parent_for_#{child_class_name.underscore.pluralize}".to_sym, 
+          as: :structureable, 
+          foreign_key: :child_id, source: 'child', 
+          source_type: child_class_name )
+      end
+      
+      # Use the neoid gem to have this object represented as node
+      # in the neo4j graph database.
+      # 
+      include Neoid::Node
+      
+      # Copy the name attribute to the neo4j nodes.
+      # Other attributes can be copied as well by using the 'attributes_to_copy_to_neo4j'.
+      # 
+      attributes_to_copy_to_neo4j do |c|
+        c.field :name
+      end
+      
+      # Include the instance methods for interaction with the neo4j graph.
+      #
+      include Neo4jAncestry::NodeInstanceMethods
+      
+    end
+    
+    # Attributes to copy over to the neo4j database.
+    # This is just a wrapper for the 'neoidable' method of the neoid gem.
+    #   https://github.com/elado/neoid
+    # 
+    # Example:
+    #   attributes_to_copy_to_neo4j do |c|
+    #     c.field :name
+    #     c.field :name_length do 
+    #       self.name.length
+    #     end
+    #   end
+    # 
+    def attributes_to_copy_to_neo4j(&block)
+      neoidable(&block)
+    end
+    
+    # The has_many method changes from Rails 3 to Rails 4.
+    # Since this gem supports both rails versions, this method
+    # is a wrapper.
+    #
+    def has_many_for_rails_3_and_4(association_name, conditions_hash, options)
+      if Rails.version.start_with? "4"
+        has_many(association_name, -> { where conditions_hash }, options)
+      elsif Rails.version.start_with? "3"
+        has_many(association_name, options.merge({conditions: conditions_hash}))
+      end
+    end
+    
+  end
+end

data/lib/models/neo4j_ancestry/link.rb

@@ -0,0 +1,28 @@
+module Neo4jAncestry
+  def self.table_name_prefix
+    'neo4j_ancestry_'
+  end
+  
+  class Link < ActiveRecord::Base
+    
+    # ActiveRecord database columns
+    # 
+    #     create_table :neo4j_ancestry_links do |t|
+    #       t.integer :parent_id
+    #       t.string :parent_type
+    #       t.integer :child_id
+    #       t.integer :child_type
+    #     end
+    #
+    
+    belongs_to :parent, polymorphic: true
+    belongs_to :child, polymorphic: true
+    
+    include Neoid::Relationship
+  
+    neoidable do |c|
+      c.relationship start_node: :parent, end_node: :child, type: :is_parent_of
+    end
+    
+  end
+end 

data/lib/models/neo4j_ancestry/node_instance_methods.rb

@@ -0,0 +1,93 @@
+module Neo4jAncestry
+  module NodeInstanceMethods
+
+    # The neoid gem provides a neo_node method, which returns an object
+    # representing the node in the neo4j database that corresponds to this
+    # object.
+    # 
+    # Overriding the neo_node method ensures that for STI the same neo_node
+    # is returned for the same object regardless of the subclass.
+    # 
+    # That means: group.neo_node == group.becomes(SpecialGroup).neo_node
+    #
+    def neo_node
+      super || self.becomes(self.class.base_class).neo_node
+    end
+    
+    # The unique id of the neo4j node that corresponds to this object.
+    #
+    def neo_id
+      neo_node.try(:neo_id)
+    end
+    
+    # Methods to query the neo4j database for parents, children,
+    # ancestors, descendants and siblings.
+    def parents
+      find_related_nodes_via_cypher("
+        match (parents)-[:is_parent_of]->(self)
+        return parents
+      ")
+    end
+    def children
+      find_related_nodes_via_cypher("
+        match (self)-[:is_parent_of]->(children)
+        return children
+      ")
+    end
+    def ancestors
+      find_related_nodes_via_cypher("
+        match (ancestors)-[:is_parent_of*1..100]->(self)
+        return ancestors
+      ").uniq
+    end
+    def descendants
+      find_related_nodes_via_cypher("
+        match (self)-[:is_parent_of*1..100]->(descendants)
+        return descendants
+      ").uniq
+    end
+    def siblings
+      find_related_nodes_via_cypher("
+        match (self)<-[:is_parent_of]-(parent)-[:is_parent_of]->(siblings)
+        return siblings
+      ").uniq
+    end
+    
+    # This method returns all ActiveRecord objects found by a cypher
+    # neo4j query defined through the given query_string.
+    # 
+    # Within the query_string, no START expression is needed, 
+    # because the start node is given by the neo_node of this
+    # structureable object. It is referred to just by 'self'. 
+    #
+    # Example:
+    #   group.find_related_nodes_via_cypher("
+    #     match (self)-[:is_parent_of]->(children)
+    #     return children
+    #   ")  # =>  [child_group1, child_group2, ...]
+    #
+    def find_related_nodes_via_cypher(query_string)
+      query_string = "
+        start self=node(#{neo_id})
+        #{query_string}
+      "
+      cypher_results_to_objects(
+        Neoid.db.execute_query(query_string)
+      )
+    end
+    
+    # This method returns the ActiveRecord objects that match the
+    # given cypher query result. 
+    # 
+    # For an example, have a look at the method
+    #   find_related_nodes_via_cypher.
+    #
+    def cypher_results_to_objects(cypher_results)
+      cypher_results["data"].collect do |result|
+        result.first["data"]["ar_type"].constantize.find(result.first["data"]["ar_id"])
+      end
+    end
+    private :cypher_results_to_objects
+    
+  end
+end