Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
157 lines (102 sloc) 6.95 KB

Indie – A project template for Neo4j Unmanaged Extensions

Unmanaged Extensions provide a way to extend the capabilities of the Neo4j server with the full power of the JDK.

A few use cases for Unmanaged Extensions include:

  • Customizing Neo4j’s default RESTful interface
  • Extending the library of Neo4j’s built-in graph algorithms
  • Integrating Neo4j with other database or messaging systems
  • Maximizing performance of server-side operations
  • Programming graph algorithms in other JVM languages such as Clojure, Scala, and Groovy

The intent of Indie is to act as a starting point for developers new to Unmanaged Extension development.
The project currently includes:

  • An application architecture that separates web request and graph algorithm concerns in the com.example namespace
  • Automatic transaction management using the com.sun.jersey.spi.ClosableService interface
  • A unit and functional test framework that cleans up the database after each test
  • An Ant build script automating testing and distribution
  • An embedded Gremlin console for ease of offline database maintenance

Why Indie?

As a developer, you need to build and test the features you plan to add to your Unmanaged Extension. To do that with
minimal risk, you will want to extensively test and profile your extension. Indie gives you a project structure to do
that. The project assumes that you want to unit test the classes in your extension, package everything up as a jar, copy
the jar to Neo4j, then start the server and test any features you’ve added against a server configured to run similarly
to your production deployment.

If you choose, you can use Indie’s ‘ant dist’ task to package up your tested changes in a tarball suitable for deployment
to your production server. Developers needing only a jar containing their libraries can easily create such an Ant target.

Getting Started

Clone or download Indie.

Download the latest Neo4j release and unpack into the neo4j-server directory.

Open neo4j-server/${neo4j-dist}/conf/, where ${neo4j-dist} is a placeholder for the name of the server
distribution you’ve installed.

Set the following properties:


Run the unit and functional tests. The default ant target is set up to run all units and functional tests:


Indie includes a script that will unpack the dist tarball locally for easy manual testing:


Visit http://localhost:7474/ext/ping to visit the ‘ping’ endpoint, which renders a JSON message to let you know that everything is loaded. If the functional tests pass, this step should work.

After running this script, you’ll want to shut down the server. Do so with:

dist/neo4j*/bin/neo4j stop

If you got this far, you’re ready to start customizing Indie with your own endpoints and traversals; just follow the usage patterns in the com.example namespace.


IDE configuration

Add the jars in the following directories to your IDE’s classpath.

  • neo4j-server/${neo4j-dist}/lib
  • neo4j-server/${neo4j-dist}/system/lib
  • lib/test

The project includes .ipr and .iml files compatible with IntelliJ 11 that you may find helpful.


Install Groovy, and you will have a REPL that you can use to quickly test your application.

CLASSPATH=out groovysh
groovy:000> com.graphutils.indie.test.utils.FileUtils.readServerVersion()
===> /Users/ecpair/dev/opensource/indie/neo4j-server/neo4j

For more information, see the Groovy Documentation

Gremlin is built on Groovy and so can also act as a REPL. A script to start Gremlin is included with the server distribution.

Build and Deployment

A high-level deployment cycle will look something like:

ant dist
cd dist
tar -zxvf indie.tar.gz
# copy your tarball to a server, unpack it, cd into the neo4j* directory
bin/neo4j start

Project structure

The basic lifecycle of a client request to an Indie extension within Neo4j looks like this:

  • A client sends an HTTP request to a URI registered as a JAX_RS extension in Neo4j
  • Neo4j routes the request and passes along parameters to the appropriate Resource using JAX_RS
  • The Resource calls a method on a Handler
  • The Handler calls one or more Traversals to query or manipulate the graph
  • The Handler renders the Response with the appropriate Presenter, if applicable. A Jackson-based JSON Presenter is included to start.
  • The Resource returns the Response to the client.

The project’s com.example package structure reflects these concerns:

├── daos - Data source management
├── exceptions - Custom RuntimeExceptions
├── handlers - POJO request handlers that simplify JAX-RS resource management
├── presenters - JSON, XML, and other view rendering concerns
├── resources - JAX-RS endpoints
├── traversals - Graph queries and manipulation
└── utils - Helpful libraries

Unit and Functional Testing

Indie allows unmanaged extension classes to be tested repeatably and in isolation. The included com.example functional tests demonstrate hitting the extension installed in a running server. The unit tests use Neo4j in embedded mode to run more quickly.

Neo4j Version Compatibility

Indie has been tested with the Community, Advanced, and Enterprise editions of Neo4j 1.6.1 on a Unix-based system.
Indie should be able to work on Windows, but some of the scripts will need to change. Patches welcome!


At the moment, Indie is meant to act as a project template to get people started on their own extensions. The choice of
tools such as Ant are somewhat arbitrary. Would people prefer Gradle? How about Maven? Is there a package structure that
might make more sense?

Once the community validates this structure, we could package up Indie as a executable jar that could generate an
Unmanaged Extension project in a manner similar to Ruby on Rails.

Feedback on these ideas is welcome.


Indie uses an Apache 2.0 license. See the enclosed LICENSE.txt and NOTICE.txt for more information.

More Information

If you’re new to graph databases, Getting started with Gremlin
will help you quickly get up and running with a REPL. Gremlin supports Neo4j out of the box, and the examples in Indie
use Gremlin extensively.

For comprehensive documentation about Neo4j, see the Neo4j Manual.


Discussions about Indie, Neo4j, and Unmanaged Extensions are available on the Neo4j Discussion Group