neo4jr-social 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Matthew Deiters
+
+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.rdoc

@@ -0,0 +1,88 @@
+= neo4jr-social
+
+Neo4jr-Social is a self contained HTTP REST + JSON interface to the graph database Neo4j. Neo4jr-Social supports simple dynamic node creation, building relationships between nodes and also includes a few common social networking queries out of the box (i.e. linkedin degrees of seperation and facebook friend suggestion) with more to come. Think of Neo4jr-Social is to Neo4j like Solr is to Lucene.
+
+Neo4jr-Social was built in JRuby but is language agnostic and is designed to run under Jetty or Tomcat. 
+
+= Getting Started
+
+=== Prerequisites
+* Java
+* JRuby: http://jruby.org
+
+=== Installing
+* Install Ruby Gem: json_pure
+  jgem install json_pure
+* Install Ruby Gem: sinatra
+  jgem install sinatra
+* Install Ruby Gem: neo4jr-simple
+  jgem install neo4jr-simple
+* Install Ruby Gem: neo4jr-social
+  jgem install neo4jr-simple
+
+=== Starting Neo4jr-Social
+
+After installing the above gems, an executable 'start-neo4jr-social' should be in your path. This will start the service and the database and listen for HTTP requests on localhost at port 8988:
+
+  start-neo4jr-social -p8988
+
+You can also start the service and specify the directory of where the neo4j database is stored or where to create a new database. If you omit this setting a database will be created in your tmp directory and destroyed when you shutdown the server.
+
+  start-neo4jr-social -p8988 -dsome_relative_or_absolute_directory
+  
+Run start-neo4jr-social --help to see all options
+
+=== API Overview
+All results returned will be in JSON
+  
+==== GET /info
+Returns details about the Neo4jr database like the location of the database and the number of nodes.
+  
+==== GET /nodes
+Returns all nodes in the database. Use this method with caution, this could crash your server if you have a database with more then a few thousand nodes.
+  
+==== POST /nodes
+Creates a new node in the neo4jr database. Any parameters based in the body of the POST will be treated as properties for the node and will be stored in the database.
+  
+==== GET /nodes/:node_id
+Returns the properties for the specified node, where :node_id is the numeric id for the node
+  
+==== PUT /nodes/:node_id  
+Updates the properties of the specified node, where :node_id is the numeric id for the node. Any parameters pased in the body of the PUT will be treated as properties for the node. If you add a new parameters (i.e. age=4) which previously were not on the node, neo4jr-social will still add that property to the node.
+  
+==== DELETE /nodes/:node_id
+Deletes the specified node, where :node_id is the numeric id for the node.
+  
+==== POST /nodes/:node_id/relationships
+Creates a relations for the specified node, where :node_id is the numeric id for the node. This is how you designate how two nodes are related to each other.
+  * Required: to - this is the node id of the node you want to make a relationship to. This is a one-way relationship. If you want both nodes to be related to each other you will need to make individual POSTs for each direction of the relationship.
+  * Required: type - this is the type of the relationship, i.e. 'friends'. This can be any string that is sensible in your domain. 
+  * Optional: Any other parameters you supply in the body of the POST will be added as properties to the relationship. For example if you were making 'friend' relationships and wanted to add a date since the friendship started you could pass a 'since' parameter in the POST.
+  
+==== GET /nodes/:node_id/relationships
+Returns relationships to other nodes for the specified node, where :node_id is the numeric id for the node.
+  * Optional: type - Specify a type if only certain relationships are of interest
+  
+==== GET /nodes/:node_id/path
+This returns all the ways two nodes are connected to each other and is similar to LinkedIn's degrees of separation. 
+  * Required: to - the id of the node that your trying to find a path to from the starting node, :node_id
+  * Required: type - the type of relationships between nodes to follow
+  * Optional: depth - maximum degrees of separation to find, the default is 2 degrees. Note: There may be performance impacts if this number is to high.
+  * Optional: direction - What direction of relationships to follow, the default is 'both'
+  
+==== GET /nodes/:node_id/recommendations
+This returns node suggestions for the given :node_id. This is similar to facebook friend suggestions where your friend's friends that your not friends with are suggested to you. 
+  * Required: type - the type of relationships between nodes to follow
+  * Optional: level - the degree of separation that you want recommendations for, the default is 1 degree away which is similar to facebook's behavior
+
+== Contributors
+
+====Matthew Deiters
+* Twitter  : http://twitter.com/mdeiters
+* GitHub   : https://github.com/mdeiters
+* LinkedIn : http://www.linkedin.com/in/matthewdeiters
+* Blog     : http://www.theagiledeveloper.com
+
+== Copyright
+
+Copyright (c) 2009 Matthew Deiters. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,70 @@
+# http://wiki.github.com/technicalpickles/jeweler/customizing-your-projects-gem-specification
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "neo4jr-social"
+    gem.summary = %Q{A self-containted and lightweight REST interface to Neo4j using JRuby.}
+    gem.description = %Q{A self-containted and lightweight REST interface to Neo4j using JRuby.}
+    gem.description = %Q{A self-containted lightweight REST interface to Neo4j using JRuby }
+    gem.email = "matthew_deiters@mckinsey.com"
+    gem.homepage = "http://github.com/mdeiters/neo4jr-social"
+    gem.authors = ["Matthew Deiters"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "rest-client"
+    gem.add_dependency 'neo4jr-simple'
+    gem.add_dependency 'sinatra'
+    gem.add_dependency 'json_pure'
+    
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "neo4jr-social #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :warify do
+  commands = ['rm -rf tmp']
+  commands << 'warble'
+  commands << 'rm jetty-runtime/webapps/neo4jr-social.war'
+  commands << 'mv neo4jr-social.war jetty-runtime/webapps/neo4jr-social.war'
+  commands.each do |command|
+    STDERR.puts("Executing: #{command}")
+    `#{command}`
+  end
+end
+
+namespace :development do
+  task :start => :warify do
+    `bin/start-neo4jr-social`
+  end
+end

data/TODO

@@ -0,0 +1,9 @@
+* Figure out a better way to shebang for start-neo4jr-social
+* Validate requests, check parameters, etc
+* Figure out how we should handle the Neo4j node's classname
+* Query Type: Amazon Recommendations
+* Query Type: Most Popular
+* Query Type: Primitive dynamic querying on all nodes
+* Enable solr type parameters with lt gt eq etc
+* Explore vendor-ize all ruby libs into WEB-INF
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/start-neo4jr-social

@@ -0,0 +1,79 @@
+#!/usr/bin/env jruby-1.4.0
+
+using_gems = false
+begin
+  require 'fileutils'
+  require 'tempfile'
+  require 'tmpdir'
+  require 'optparse'
+rescue LoadError => e
+  if using_gems
+    raise(e)
+  else
+    using_gems = true
+    require 'rubygems'
+    retry
+  end
+end
+
+working_directory = FileUtils.pwd
+neo4j_social_install = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+port        = '8988'
+db_dir      = nil
+log_file    = nil
+log_level   = 'OFF'
+min_memory  = '128m'
+max_memory  = '512m'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: start-neo4jr-social [options]"
+
+  opts.on '-p', '--port=PORT', 'Port on which to run Neo4jr-social (default 8333)' do |p|
+    port = p
+  end
+
+  opts.on '-d', '--database=DIRECTORY', 'directory where the neo4jr database is located' do |d|
+    db_dir = File.expand_path(d)
+  end
+  
+  opts.on '-l', '--log-level=LOG_LEVEL', 'Neo4jr-social logging level' do |l|
+    log_level = l
+  end
+
+  opts.on '--log-file=LOG_FILE', 'Path to Neo4jr-social log file' do |lf|
+    log_file = File.expand_path(lf)
+  end
+  
+  opts.on '--max-memory=MEMORY', 'Specify the maximum size of the memory allocation pool' do |mm|
+    max_memory = mm
+  end
+  
+  opts.on '--min-memory=MEMORY', 'Specify the initial size of the memory allocation pool' do |mm|
+    min_memory = mm
+  end
+end.parse!
+
+def logging_properties( log_file, log_level )
+  temp_file = Tempfile.new 'logging.properties'
+  temp_file << <<PROPERTIES
+.level = #{log_level}
+handlers = java.util.logging.FileHandler
+java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
+java.util.logging.FileHandler.pattern   = #{log_file}
+PROPERTIES
+  temp_file.flush
+  temp_file.close
+  temp_file.path
+end
+
+args = ['java']
+args << "-Xms#{min_memory}"
+args << "-Xmx#{max_memory}"
+args << "-Djetty.port=#{port}" if port
+args << "-Djetty.home=#{File.join(neo4j_social_install, 'jetty-runtime')}"
+args << "-Dneo4jr.database=#{db_dir}" if db_dir
+args << "-Djava.util.logging.config.file=#{logging_properties(log_file, log_level)}" if log_file and log_level != 'OFF'
+args << '-jar' << File.join(neo4j_social_install, 'jetty-runtime', 'start.jar')
+STDERR.puts(args * ' ')
+Kernel.exec(args.join(' '))

data/config.ru

@@ -0,0 +1,3 @@
+require 'lib/neo4jr-social'
+
+run Neo4jr::Service

data/examples/facebook.rb

@@ -0,0 +1,33 @@
+# neo4jr-social start -p8988
+
+require 'rubygems'
+require 'json'
+require 'rest_client'
+
+def create_person(name)
+  JSON.parse RestClient.post( "http://localhost:8988/neo4jr-social/nodes", :name => name  )
+end
+
+def make_mutual_friends(node1, node2)
+  RestClient.post "http://localhost:8988/neo4jr-social/nodes/#{node1['node_id']}/relationships", :to => node2['node_id'], :type => 'friends'
+  RestClient.post "http://localhost:8988/neo4jr-social/nodes/#{node2['node_id']}/relationships", :to => node1['node_id'], :type => 'friends'
+end
+
+def suggestions_for(start_node)
+  JSON.parse RestClient.get("http://localhost:8988/neo4jr-social/nodes/#{start_node['node_id']}/recommendations?type=friends")
+end
+
+johnathan = create_person('Johnathan')
+mark      = create_person('Mark')
+phill     = create_person('Phill')
+mary      = create_person('Mary')
+luke      = create_person('Luke')
+
+make_mutual_friends(johnathan, mark)
+make_mutual_friends(mark, mary)
+make_mutual_friends(mark, phill)
+make_mutual_friends(phill, mary)
+make_mutual_friends(phill, luke)
+
+puts "Johnathan should become friends with #{suggestions_for(johnathan).map{|n| n['name']}.join(', ')}"
+#=> Johnathan should become friends with Mary, Phill

data/examples/linkedin.rb

@@ -0,0 +1,38 @@
+# neo4jr-social start -p8988
+
+require 'rubygems'
+require 'json'
+require 'rest_client'
+
+def create_person(name)
+  response = RestClient.post "http://localhost:8988/neo4jr-social/nodes", :name => name  
+  JSON.parse(response)
+end
+
+def make_mutual_friends(node1, node2)
+  RestClient.post "http://localhost:8988/neo4jr-social/nodes/#{node1['node_id']}/relationships", :to => node2['node_id'], :type => 'friends'
+  RestClient.post "http://localhost:8988/neo4jr-social/nodes/#{node2['node_id']}/relationships", :to => node1['node_id'], :type => 'friends'
+end
+
+def degrees_of_seperation(start_node, destination_node)
+  url = "http://localhost:8988/neo4jr-social/nodes/#{start_node['node_id']}/path?to=#{destination_node['node_id']}&type=friends&depth=3&direction=outgoing"
+  response = RestClient.get(url)
+  JSON.parse(response)
+end
+
+johnathan = create_person('Johnathan')
+mark      = create_person('Mark')
+phill     = create_person('Phill')
+mary      = create_person('Mary')
+
+make_mutual_friends(johnathan, mark)
+make_mutual_friends(mark, mary)
+make_mutual_friends(mark, phill)
+make_mutual_friends(phill, mary)
+
+degrees_of_seperation(johnathan, mary).each do |path|
+  puts path.map{|node| node['name'] || node['type']}.join(' => ') 
+end
+
+# Johnathan => friends => Mark => friends => Phill => friends => Mary
+# Johnathan => friends => Mark => friends => Mary

data/jetty-runtime/etc/jetty.xml

@@ -0,0 +1,212 @@
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
+
+<!-- =============================================================== -->
+<!-- Configure the Jetty Server                                      -->
+<!--                                                                 -->
+<!-- Documentation of this file format can be found at:              -->
+<!-- http://docs.codehaus.org/display/JETTY/jetty.xml                -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+
+
+<Configure id="Server" class="org.mortbay.jetty.Server">
+
+    <!-- Increase the maximum POST size to 1 MB to be able to handle large shard requests -->
+    <Call class="java.lang.System" name="setProperty">
+      <Arg>org.mortbay.jetty.Request.maxFormContentSize</Arg>
+      <Arg>1000000</Arg>
+    </Call>
+
+    <!-- =========================================================== -->
+    <!-- Server Thread Pool                                          -->
+    <!-- =========================================================== -->
+    <Set name="ThreadPool">
+      <!-- Default bounded blocking threadpool 
+      -->
+      <New class="org.mortbay.thread.BoundedThreadPool">
+        <Set name="minThreads">10</Set>
+        <Set name="lowThreads">50</Set>
+        <Set name="maxThreads">10000</Set>
+      </New>
+
+      <!-- Optional Java 5 bounded threadpool with job queue 
+      <New class="org.mortbay.thread.concurrent.ThreadPool">
+        <Arg type="int">0</Arg>
+        <Set name="corePoolSize">10</Set>
+        <Set name="maximumPoolSize">250</Set>
+      </New>
+      -->
+    </Set>
+
+
+
+    <!-- =========================================================== -->
+    <!-- Set connectors                                              -->
+    <!-- =========================================================== -->
+    <!-- One of each type!                                           -->
+    <!-- =========================================================== -->
+
+    <!-- Use this connector for many frequently idle connections
+         and for threadless continuations.
+    <Call name="addConnector">
+      <Arg>
+          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
+            <Set name="port"><SystemProperty name="jetty.port" default="8983"/></Set>
+            <Set name="maxIdleTime">30000</Set>
+            <Set name="Acceptors">2</Set>
+            <Set name="confidentialPort">8443</Set>
+          </New>
+      </Arg>
+    </Call>
+   -->     
+
+    <!-- Use this connector if NIO is not available. -->
+    <!-- This connector is currently being used for Solr because the
+         nio.SelectChannelConnector showed poor performance under WindowsXP
+         from a single client with non-persistent connections (35s vs ~3min)
+         to complete 10,000 requests)
+    -->
+    <Call name="addConnector">
+      <Arg>
+          <New class="org.mortbay.jetty.bio.SocketConnector">
+            <Set name="port"><SystemProperty name="jetty.port" default="8988"/></Set>
+            <Set name="maxIdleTime">50000</Set>
+            <Set name="lowResourceMaxIdleTime">1500</Set>
+          </New>
+      </Arg>
+    </Call>
+
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+    <!-- To add a HTTPS SSL listener                                     -->
+    <!-- see jetty-ssl.xml to add an ssl connector. use                  -->
+    <!-- java -jar start.jar etc/jetty.xml etc/jetty-ssl.xml             -->
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+    
+    <!-- =========================================================== -->
+    <!-- Set up global session ID manager                            -->
+    <!-- =========================================================== -->
+    <!--
+    <Set name="sessionIdManager">
+      <New class="org.mortbay.jetty.servlet.HashSessionIdManager">
+        <Set name="workerName">node1</Set>
+      </New>
+    </Set>
+    -->
+
+    <!-- =========================================================== -->
+    <!-- Set handler Collection Structure                            --> 
+    <!-- =========================================================== -->
+    <Set name="handler">
+      <New id="Handlers" class="org.mortbay.jetty.handler.HandlerCollection">
+        <Set name="handlers">
+         <Array type="org.mortbay.jetty.Handler">
+           <Item>
+             <New id="Contexts" class="org.mortbay.jetty.handler.ContextHandlerCollection"/>
+           </Item>
+           <Item>
+             <New id="DefaultHandler" class="org.mortbay.jetty.handler.DefaultHandler"/>
+           </Item>
+           <Item>
+             <New id="RequestLog" class="org.mortbay.jetty.handler.RequestLogHandler"/>
+           </Item>
+         </Array>
+        </Set>
+      </New>
+    </Set>
+    
+    <!-- =========================================================== -->
+    <!-- Configure the context deployer                              -->
+    <!-- A context deployer will deploy contexts described in        -->
+    <!-- configuration files discovered in a directory.              -->
+    <!-- The configuration directory can be scanned for hot          -->
+    <!-- deployments at the configured scanInterval.                 -->
+    <!--                                                             -->
+    <!-- This deployer is configured to deploy contexts configured   -->
+    <!-- in the $JETTY_HOME/contexts directory                       -->
+    <!--                                                             -->
+    <!-- =========================================================== -->
+    <Call name="addLifeCycle">
+      <Arg>
+        <New class="org.mortbay.jetty.deployer.ContextDeployer">
+          <Set name="contexts"><Ref id="Contexts"/></Set>
+          <Set name="configurationDir"><SystemProperty name="jetty.home" default="."/>/contexts</Set>
+          <Set name="scanInterval">1</Set>
+        </New>
+      </Arg>
+    </Call>
+
+    <!-- =========================================================== -->
+    <!-- Configure the webapp deployer.                              -->
+    <!-- A webapp  deployer will deploy standard webapps discovered  -->
+    <!-- in a directory at startup, without the need for additional  -->
+    <!-- configuration files.    It does not support hot deploy or   -->
+    <!-- non standard contexts (see ContextDeployer above).          -->
+    <!--                                                             -->
+    <!-- This deployer is configured to deploy webapps from the      -->
+    <!-- $JETTY_HOME/webapps directory                               -->
+    <!--                                                             -->
+    <!-- Normally only one type of deployer need be used.            -->
+    <!--                                                             -->
+    <!-- =========================================================== -->
+    <Call name="addLifeCycle">
+      <Arg>
+        <New class="org.mortbay.jetty.deployer.WebAppDeployer">
+          <Set name="contexts"><Ref id="Contexts"/></Set>
+          <Set name="webAppDir"><SystemProperty name="jetty.home" default="."/>/webapps</Set>
+				  <Set name="parentLoaderPriority">false</Set>
+				  <Set name="extract">true</Set>
+				  <Set name="allowDuplicates">false</Set>
+          <Set name="defaultsDescriptor"><SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml</Set>
+        </New>
+      </Arg>
+    </Call>
+
+    <!-- =========================================================== -->
+    <!-- Configure Authentication Realms                             -->
+    <!-- Realms may be configured for the entire server here, or     -->
+    <!-- they can be configured for a specific web app in a context  -->
+    <!-- configuration (see $(jetty.home)/contexts/test.xml for an   -->
+    <!-- example).                                                   -->
+    <!-- =========================================================== -->
+    <Set name="UserRealms">
+      <Array type="org.mortbay.jetty.security.UserRealm">
+        <!--
+        <Item>
+          <New class="org.mortbay.jetty.security.HashUserRealm">
+            <Set name="name">Test Realm</Set>
+            <Set name="config"><SystemProperty name="jetty.home" default="."/>/etc/realm.properties</Set>
+          </New>
+        </Item>
+	-->
+      </Array>
+    </Set>
+
+    <!-- =========================================================== -->
+    <!-- Configure Request Log                                       -->
+    <!-- Request logs  may be configured for the entire server here, -->
+    <!-- or they can be configured for a specific web app in a       -->
+    <!-- contexts configuration (see $(jetty.home)/contexts/test.xml -->
+    <!-- for an example).                                            -->
+    <!-- =========================================================== -->
+    <Ref id="RequestLog">
+      <Set name="requestLog">
+        <!-- New id="RequestLogImpl" class="org.mortbay.jetty.NCSARequestLog">
+          <Arg><SystemProperty name="jetty.logs" default="./logs"/>/yyyy_mm_dd.request.log</Arg>
+          <Set name="retainDays">90</Set>
+          <Set name="append">true</Set>
+          <Set name="extended">false</Set>
+          <Set name="LogTimeZone">GMT</Set>
+        </New -->
+      </Set>
+    </Ref>
+
+    <!-- =========================================================== -->
+    <!-- extra options                                               -->
+    <!-- =========================================================== -->
+    <Set name="stopAtShutdown">true</Set>
+    <!-- ensure/prevent Server: header being sent to browsers        -->
+    <Set name="sendServerVersion">true</Set>
+
+</Configure>
+