Neo4j GORM

Version notes: The most recent version (0.3) of this plugin works with Grails 1.2.x and Grails 1.3.x (where x >=4). Grails 1.3 - 1.3.3 suffer from http://jira.codehaus.org/browse/GRAILS-6427 that will be fixed in the upcomping 1.3.4 release.

The plugin’s goal is to provide an alternative approach for storing Grails domain classes: in the Neo4j database.

Neo4j is a relative new and very interesting approach for persitence in a non-SQLish way. Neo4j is a graph database and uses the concept of

Nodes

A node is the basic building block. It normally represents a “something”, a entity.

Relationships

Relationsships are associations between nodes. Each relationship connects exactly two nodes. Relationsships have a direction: incoming, outgoing or both.

Properties

Each node or relationship might contain a set of properties. A property has a name (String) and a value (primitive datatype). Complex value are not allowed for properties.

This is completely different from the SQL approach. There are no tables, columns, indexes, and other stuff we’ve dealt with for years. Somewhat crucial is the way how to organize the node space. Neo4j gives some advice here.

Neo4j itself uses the AGPL license, the plugin is licensed the WTFPL.

How the plugin works

Using Groovy’s metaprogramming capabilities, the basic CRUD-methods list, save, get and delete are added transparently to each domain class. In addition, each domain instance gets a ‘node’ property referencing the associated Neo4j Node.

For each domain class a subreference node is created related to the reference aka root node. Each domain instance holds a relation to it’s subreference node. For non-primitive properties,

Aside from this, the plugin starts up and closes the Neo4j database. The database’s path is configured using the grails.neo4j.storeDir property in Config.groovy.

Howto use the plugin

The plugin can be used transparently in a Grails application. The only thing you have to do is to install the neo4j plugin:

grails install-plugin neo4j

Add some domain classes and controllers with scaffolding – they should work.

What currently works

• basic CRUD operations on domain classes
• one-to-one, one-to-many, many-to-one and many-to-many relations of domain classes
• the current implementation supports scaffolding

What’s still missing (and hopefully will be added in upcoming releases)

• currently all constraints are ignored
• only a subset of the domain methods are implemented
• dynamic finders have only a very basic support: just DomainClass.findByProperty (+)(value) works so far

New planned features

• SVG controller/views to display the complete object graph, just like Neoclipse does.
• Gant scripts for automatically snapshotting and restoring the database
• Criteria queries implemented using Neo4j traversers

Release history

• 2010-07-30: release 0.3: Grails 1.3.x compatibility + Upgrade Neo4j 1.1
• GRAILSPLUGINS-2302 (+) - "home" link broken in the org.codehaus.groovy.grails.plugins.neo4j.Neo4jController views
• GRAILSPLUGINS-2303 (+) - Problems with annotation Neo4jEntity
• GRAILSPLUGINS-2345 (+) - upgrade to Neo4j 1.1
• GRAILSPLUGINS-2346 (+) - <domainclass>.get() throws exception if id is not invalid
• GRAILSPLUGINS-2347 (+) - <domainClass>.findAllBy<Field>(value) fails
• GRAILSPLUGINS-2349 (+) - provide compatibility for Grails 1.3.x
• 2010-04-02: release 0.2.1
• performance improvement by no longer calling map constructor in createInstanceForNode
• fixed transaction handling by replacing interceptor with a "real" servlet filter
• support for primitve arrays as properties in domain classes
• bugfix: handling of bidirectional many-to-many relationships
• bugfix: setProperties does no longer null out properties that have not been set
• support for encodeAsXXXX methods from CodecsGrailsPlugin. In previous versions encoding did not work, since the node property of the domain classes could not be encoded (it's a neo4j internal class!). Workaround: add getNode()==null method in AST transformation.
• 2010-03-10: release 0.2
• domain classes managed by Neo4j can now co-existing with traditional domain classes (aka mapped by Hibernate)
• Upgrade to Neo4j 1.0
• usage of Grails dependency resolution instead of embedding the jars in /lib directory
• added a seperate controller to inspect the Neo4j node space
• major refactoring using AST transformation, just like in the couchdb plugin
• support for the Neo4j indexer
• support for non-declared properties
• support for traversers
• 2009-10-02: initial release 0.1