• compatibility with Grails 1.3.x. Be aware, Grails 1.3 – 1.3.3 are suffering from http://jira.codehaus.org/browse/GRAILS-6427, so either use Grails 1.2.x, or be brave and use a recent git build of Grails 1.3.4.SNAPSHOT.
• usage of Neo4j 1.1 (released today just a few hours ago, so get it while it’s hot).

All changes:

• [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

• 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.

Everyone using the 0.2 release is recommended to upgrade.

The key features / changes of this release are:

• 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

In more detail:

Co-existence with other domain implementations

In the initial 0.1 release there was no possibility to have hibernate-based domain classes and neo4j-bases domain classes within the same application. By massively learning from the implementation of the CouchDB plugin, the neo4j plugin shares now the same principles:

• each domain class annotated with “@Neo4jEntity” is managed by Neo4j
• the @Neo4jEntity  annotation triggers a Groovy AST transformation at compile time. This transformation e.g. injects a reference to the Neo4j node instance in each domain class.
• the plugin class delegates most of its work to a singleton-style plugin support class
• the plugin support class uses Groovy MOP to inject (most of) the GORM methods into the domain classes

Upgrade to Neo4j 1.0

About two weeks ago, the Neo4j team released their 1.0 version. In order to keep pace, the 0.2 version of the plugin upgrades to this version.

Using dependency resolution

In its recent versions Grails provides a powerful dependency resolution DSL. Using this feature, the Neo4j plugin does not contain the neo4j jars itself any longer. Instead they are automatically downloaded upon plugin installation from the Neo4j’s maven repository.

Controller for visualizing the node space

The plugin contains a Neo4jController that provides an easy way to inspect and walk through the nodespace. All the properties and relationships are visible and navigable, see the screenshot.

Aside from navigating through the nodespace, the Neo4jController also provides an action for viewing some statistics: counting nodes an relationship by type, and an inspector for viewing the Grails domain class structure. One word of warning: do not expose this controller to the public! Instead use e.g. the acegi plugin and protect it from public access.

Support for Neo4j Indexer

Since there is no easy way to ask the nodespace questions like “Give me all cars with more than 250 hp?”, Neo4j provides an addon that indexes property values. The plugin supports this in two ways:

• Defining index properties in a domain class by annotating the properties to be indexed with @Neo4jIndexed
• Using the indexer when the GORM methods ‘findBy<prop>’ or ‘findAllBy<prop>’ are called on an indexed property

The following code example will make that clearer:

import grails.plugins.neo4j.*
@Neo4jEntity
class Car {
   String licenseTag // normal, aka non-indexed property
   @Neo4jIndex
   String color  // indexed property
}

Support for non-declared properties

Since Neo4j is a schema-less database, there is no limitation on what properties are allowed for a certain node. A Grails domain model is much more strict on this. To fill this gap, the plugin supports non-declared properties:

def car = new Car(licenseTag:'ABC123', color:'red')
car.save()
assert 'red' == car.color // declared property
assert null = car.numberOfSeats // N.B: numberOfSeats is _not_ declared
car.numberOfSeats = 5
assert '5' == car.numberOfSeats

Using non-declared properties has one limitation: since there’s no type information available, they are stored as String. That’s why the last assert need ‘5′ in quotes.

Support for traversers

A very powerful method to search and find nodes in the nodespace are traversers. The plugin supports them on two levels:

• static:  DomainClass.traverse uses the reference node as starting point and
• instance: <domainClassInstance>.traverse uses the domainClassInstance as starting point.

Both variants come with some overloaded implementations:

traverse(StopEvaluator stopEvaluator, ReturnableEvaluator returnableEvaluator, Object... args)
traverse(Traverser.Order order, StopEvaluator stopEvaluator, ReturnableEvaluator returnableEvaluator, Object... args)
traverse(Closure stopEvaluator, Closure returnableEvaluator, Object... arg)
traverse(Traverser.Order order, Closure stopEvaluator, Closure returnableEvaluator, Object... args)

Note that StopEvaluators and ReturnableEvaluator might be coded in a ‘groovy’ way as closures:

def traverser = car.traverse(
 { true },  // StopEvaluator
 { it.currentNode().getProperty("color",null)=="red"} // ReturnableEvaluator
)

1. Create your sample application:

   grails create-app neo4jtest; cd neo4jtest

2. Add the Neo4j plugin:

   grails install-plugin neo4j

3. create some sample domain classes:

   grails create-domain-class Author
   grails create-domain-class Book

4. create a controller for the domain class

   grails create-controller Author
   grails create-controller Book

5. modify the domain classes:

   import grails.plugins.neo4j.Neo4jEntity
   @Neo4jEntity
   class Author {
       String name
       Date dob
    
       static hasMany = [ books: Book ]
   }

   and

   import grails.plugins.neo4j.Neo4jEntity
   @Neo4jEntity
   class Book {
       String title
       static belongsTo = [author:Author]
   }

6. modify the controller to use dynamic scaffolding:

   class AuthorController {
       def scaffold = true
   }

   class BookController {
       def scaffold = true
   }

7. start up the application:

   grails run-app

8. use it, love it: go to http://localhost:8080/neo4jtest, add some authors and books.
9. to explore the Neo4j node space created with your grails app, check out Neoclipse.

UPDATE: Use Grails 1.2.1

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, either relations to other domain nodes are used or they are converted to strings using the Spring’s PropertyEditor approach.

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 remove the hibernate plugin and install the neo4j plugin:

1
2

grails uninstall-plugin hibernate
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
• Together with the acegi plugin, you can store your user, role and requestmap information in neo4j. Since the default UserDetailsService relies on Hibernate’s SessionFactory you have to use a custom UserDetailsService to get this working.

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.findBy[Property](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

Any feedback is appreciated.