To setup the project we created a public github account and began setting up the infrastructure for a spring web project using Maven as build system. So we added the dependencies for the Spring Framework libraries, put the web.xml for the DispatcherServlet and the applicationContext.xml in the webapp directory.

<properties>
    <spring.version>3.0.5.RELEASE</spring.version>
</properties>

<dependencies>
<dependency>
    <groupId>org.springframework</groupId>
    <!-- abbreviated for all the dependencies -->
    <artifactId>spring-(core,context,aop,aspects,tx,webmvc)</artifactId>
    <version>${spring.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>${spring.version}</version>
    <scope>test</scope>
</dependency>
</dependencies>

<build><plugins>
	<plugin>
		<groupId>org.mortbay.jetty</groupId>
		<artifactId>jetty-maven-plugin</artifactId>
		<version>7.1.2.v20100523</version>
		<configuration>
		   <webAppConfig>
		     <contextPath>/</contextPath>
		   </webAppConfig>
		</configuration>
	</plugin>
</plugins></build>

            

<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

<servlet>
    <servlet-name>dispatcherServlet</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>dispatcherServlet</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>
        

With this setup we were ready for the first spike: creating a simple MovieController showing a static view. Check. Next was the setup for Spring Data Graph. We looked at the README at github and then checked it with the manual. Quite a lot of Maven setup for AspectJ but otherwise not so much to add. Time to add a few lines to our Spring configuration.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:tx="http://www.springframework.org/schema/tx"
    xsi:schemaLocation="
	http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
	http://www.springframework.org/schema/tx
	http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
	http://www.springframework.org/schema/context
	http://www.springframework.org/schema/context/spring-context-3.0.xsd">

 <context:annotation-config/>
 <context:spring-configured/>
 <context:component-scan base-package="org.neo4j.cineasts">
     <context:exclude-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
 </context:component-scan>

 <tx:annotation-driven mode="aspectj"/>
</beans>

<mvc:annotation-driven/>
<mvc:resources mapping="/images/**" location="/images/"/>
<mvc:resources mapping="/resources/**" location="/resources/"/>
<context:component-scan base-package="org.neo4j.cineasts.controller"/>

<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver" p:prefix="/WEB-INF/views/" p:suffix=".jsp"/>

<tx:annotation-driven mode="aspectj"/>

We spun up Jetty to see if there were any obvious issues with the config. It all seemed to work just fine. Check.

Next were relationships. Direct relationships didn't require any annotation. Unfortunately we had none of those, because ours had more semantics. So we went for the Role relationship between Movie and Actor. It had to be annotated with @RelationshipEntity and the @StartNode and @EndNode had to be marked. So our Role looked like this:

@RelationshipEntity
class Role {
    @StartNode Actor actor;
    @EndNode Movie movie;
    String role;
}
    

When writing a test for that we tried to create the relationship entity with new, but got an exception saying that this is not allowed. This must be a strange restriction about having only correctly constructed RelationshipEntities. To fix it, we had to recall the relateTo method from the introduced methods on the NodeEntities. After checking it turned out to be exactly what we needed. We then added the method for connecting movies and actors to the actor - which seems a more natural fit.

class Actor {
...
public Role playedIn(Movie movie, String roleName) {
    Role role = relateTo(movie, Role.class, "ACTS_IN");
    role.setRole(roleName);
    return role;
}}
            

What was left? Accessing those relationships. We already had the appropriate fields in both classes. Time to annotate them correctly. For the fields providing access to the entities on the each side of the relationship this was straightforward. Providing the target type again (thanks to Java's type erasure) and the relationship type (learned from the Neo4j lesson before) there was only the direction left. Which defaults to OUTGOING so only for the movie we had to specify it.

@NodeEntity
class Movie {
    @Indexed
    int id;
    String title;
    int year;
    @RelatedTo(elementClass = Actor.class, type = "ACTS_IN", direction = Direction.INCOMING)
    Set<Actor> cast;
}

@NodeEntity
class Actor {
    @Indexed
    int id;
    String name;
    @RelatedTo(elementClass = Movie.class, type = "ACTS_IN")
    Set<Movie> cast;

    public Role playedIn(Movie movie, String roleName) {
        Role role = relateTo(movie, Role.class, "ACTS_IN");
        role.setRole(roleName);
        return role;
    }
}
            

While reading about those relationship-sets we learned that they are handled by managed collections of Spring Data Graph. So whenever we add something to the set or remove it, it automatically reflects that in the underlying relationships. Neat. But this also meant we mustn't initialize the fields. Something we will certainly forget not to do in the future, so watch out for it.

We made sure to add a test for those, so are assured that the collections worked as advertised (and also ran into the intialization problem above).

But we still couldn't access the Role relationships. There was more to read about this. For accessing the relationship in between the nodes there was a separate annotation @RelatedToVia. And we had to declare the field as readonly Iterable<Role>. That should make sure that we never tried to add Roles (which I couldn't create on my own anyway) to this field. Otherwise the annotation attributes were similar to those used for @RelatedTo. So off we went, creating our first real relationship (just kidding).

@NodeEntity
class Movie {
    @Indexed
    int id;
    String title;
    int year;
    @RelatedTo(elementClass = Actor.class, type = "ACTS_IN", direction = Direction.INCOMING)
     Set<Actor> cast;

    @RelatedToVia(elementClass = Role.class, type = "ACTS_IN", direction = Direction.INCOMING)
    Iterable<Roles> roles;
}
        

After the tests proved that those relationship fields really mirrored the underlying relationships in the graph and instantly reflected additions and removals we were pretty satisfied with our domain.

Time to put this on display. But we needed some test data first. So we wrote a small class for populating the database which could be called from our controller. To make it safe to call several times we added index lookups to check for existing entries. A simple /populate endpoint for the controller that called it would be enough for now.

@Service
public class DatabasePopulator {

  @Autowired GraphDatabaseContext ctx;
  @Autowired CineastsRepository repository;

  @Transactional
  public List<Movie> populateDatabase() {
      Actor tomHanks = new Actor("1", "Tom Hanks").persist();
      Movie forestGump = new Movie("1", "Forrest Gump").persist();
      tomHanks.playedIn(forestGump,"Forrest");
      return asList(forestGump);
  }}

@Controller
public class MovieController {

  private DatabasePopulator populator;

  @Autowired
  public MovieController(DatabasePopulator populator) {
      this.populator = populator;
  }

  @RequestMapping(value = "/populate", method = RequestMethod.GET)
  public String populateDatabase(Model model) {
      Collection<Movie> movies=populator.populateDatabase();
      model.addAttribute("movies",movies);
      return "/movies/list";
  }
}

        

<%@ page session="false" %>
<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<c:choose>
  <c:when test="${not empty movie}">
    <h2>${movie.title}</h2>
    <c:if test="${not empty movie.roles}">
    <ul>
    <c:forEach items="${movie.roles}" var="role">
      <li>
        <a href="/actors/${role.actor.id}"><c:out value="${role.actor.name}" /> as <c:out value="${role.name}" /></a><br/>
      </li>
    </c:forEach>
    </ul>
    </c:if>
  </c:when>
  <c:otherwise>
      No Movie with id ${id} found!
  </c:otherwise>
</c:choose>
            

See the misused GET parameter for that (don't do this at home, the REST guys will be upset). This is only for running it from the browser address line. Better use POST and curl for the call. So we called the URI and it showed the single added movie on screen.

The next thing was to allow users to search for some movies. So we needed some fulltext-search capabilities. As the index provider implementation of Neo4j builds on lucene we were delighted to see that fulltext indexes are supported out of the box.

We happily annotated the title field of my Movie class with @Index(fulltext=true) and was told with an exception that we have to specify a separate index name for that. So it became @Indexed(fulltext = true, indexName = "search"). The corresponding graphRepository method is called findAllByQuery. So there was our second repository method for searching movies. To restrict the size of the returned set we just added a limit for now that truncates the result after so many entries.

public void List<Movie> findMovies(String query, int count) {
    List<Movie> movies=new ArrayList<Movie>(count);
    for (Movie movie : movieRepository.findAllByQuery("title", query)) {
        movies.add(movie);
        if (count-- == 0) break;
    }
    return movies;
}

We then used this result in the controller to render a list of movies driven by a search box. The movie properties and the cast was accessed by the getters in the domain classes.

@RequestMapping(value = "/movies", method = RequestMethod.GET, headers = "Accept=text/html")
public String findMovies(Model model, @RequestParam("q") String query) {
    List<Movie> movies = repository.findMovies(query, 20);
    model.addAttribute("movies", movies);
    model.addAttribute("query", query);
    return "/movies/list";
}

<h2>Movies</h2>

<c:choose>
    <c:when test="${not empty movies}">
        <dl class="listings">
        <c:forEach items="${movies}" var="movie">
            <dt>
                <a href="/movies/${movie.id}"><c:out value="${movie.title}" /></a><br/>
            </dt>
            <dd>
                <c:out value="${movie.description}" escapeXml="true" />
            </dd>
        </c:forEach>
        </dl>
    </c:when>
    <c:otherwise>
        No movies found for query &quot;${query}&quot;.
    </c:otherwise>
</c:choose>
            

Here is another teaser, what the final UX would look like for that:

So we took the User class that we'd already coded and made it a full fledged Spring Data Graph member. We added the ability to make friends and to rate movies. With that there was also a simple UserRepository that was able to look up users by id.

@NodeEntity
class User {
    @Indexed
    String login;
    String name;
    String password;
    @RelatedTo(elementClass=Movie.class, type="RATED")
    Set<Rating> ratings;

    @RelatedTo(elementClass=User.class, type="FRIEND")
    Set<User> friends;

    public Rating rate(Movie movie, int stars, String comment) {
        return relateTo(movie, Rating.class, "RATED").rate(stars, comment);
    }
    public void befriend(User user) {
        this.friends.add(user);
    }
}
@RelationshipEntity
class Rating {
    @StartNode User user;
    @EndNode Movie movie;
    int stars;
    String comment;
    public Rating rate(int stars, String comment) {
       this.stars=stars; this.comment = comment;
       return this;
    }
}
            

We extended my DatabasePopulator to add some users and ratings to the initial setup.

@Transactional
public List<Movie> populateDatabase() {
    Actor tomHanks = new Actor("1", "Tom Hanks").persist();
    Movie forestGump = new Movie("1", "Forrest Gump").persist();
    tomHanks.playedIn(forestGump,"Forrest");

    User me = new User("micha", "Micha", "password", User.Roles.ROLE_ADMIN,User.Roles.ROLE_USER).persist();
    Rating awesome = me.rate(forestGump, 5, "Awesome");

    User ollie = new User("ollie", "Olliver", "password",User.Roles.ROLE_USER).persist();
    ollie.rate(forestGump, 2, "ok");
    me.addFriend(ollie);
    return asList(forestGump);
}
            

We also put a ratings field into the movie to be able to show its ratings. And a method to average its star rating.

class Movie {
    @RelatedToVia(elementClass=Rating.class, type="RATED", direction = Direction.INCOMING)
    Iterable<Rating> ratings;

    public int getStars() {
        int stars, int count;
        for (Rating rating : ratings) {
            stars += rating.getStars(); count++;
        }
        return count == 0 ? 0 : stars / count;
    }
}
            

Fortunately our tests highlighted the division by zero error when calculating the stars for a movie without ratings. Next steps were to add this information to the UI of movie and create a user profile page. But for that to happen they must be able to log in.

A graph database is a storage engine that is specialized in storing and retrieving vast networks of data. It efficiently stores nodes and relationships and allows high performance traversal of those structures. With property graphs it is possible to add an arbitrary number of properties to nodes and relationships.

Graph databases are well suited to model most kinds of domains. In almost all domains there are certain things connected to other things. The classes of things are not the most important aspect, rather that each invidual instance is represented correctly (with all its necessary properties) in the domain model. In most other modelling approaches the relationships between things are reduced to a single link without identity and attributes. Graph databases allow to keep the rich relationshiops that originate from the domain equally well represented in the model without resorting to model relationships as "things". So there is no impedance mismatch when putting real life domains into graph databases.

Neo4j is a graph database. It is a fully ACID transactional database that stores data structured as graphs. A graph consists of nodes, connected by relationships. It is a flexible data structure that allows for high query performance on complex data, while being intuitive for the developer.

Neo4j has been in commercial development for 10 years and in production for over 7 years. It is a mature and robust graph database that:

In addition, Neo4j includes the usual database characteristics: ACID transactions, durable persistence, concurrency control, transaction recovery, high availability and everything else you’d expect from an enterprise database. Neo4j is released under a dual free software/commercial license model.

The interface org.neo4j.graphdb.GraphDatabaseService provides access to the storage engine. Its features include creating and retrieving Nodes and Relationships, managing indexes, via an IndexManager, database lifecycle callbacks, transation management and more.

The EmbeddedGraphDatabaseService is an implementation of GraphDatabaseService that is used to embed Neo4j in a Java application. This implmentation is used so as to provide the highest and tightest integration. Besides the embedded mode, the Neo4j server provides access to the graph database via a convenient REST-API.

Using the API of GraphDatabaseService it is easy to create nodes and relate them to each other. Relationships are named. Both nodes and relationships can have properties. Property values can be primitive Java types and Strings, byte arrays for binary data, or arrays of other Java primitives or Strings. Node creation and modification has to happen within a transaction, while reading from the graph store can be achieved with or without a transaction.

GraphDatabaseService graphDb = new EmbeddedGraphDatabase( "helloworld" );
Transaction tx = graphDb.beginTx();
try {

	Node firstNode = graphDb.createNode();
	Node secondNode = graphDb.createNode();
	firstNode.setProperty( "message", "Hello, " );
	secondNode.setProperty( "message", "world!" );

	Relationship relationship = firstNode.createRelationshipTo( secondNode, 
		DynamicRelationshipType.of("KNOWS") );
	relationship.setProperty( "message", "brave Neo4j " );
	tx.success();
} finally {
	tx.finish();
}
			

Getting a single node or relationship and examining it is not the main use case of a graph database. Fast graph traversal and application of graph algorithms are. Neo4j provides means via a concise DSL to define TraversalDescriptions that can then be applied to a start node and will produce a stream of nodes and/or relationships as a lazy result using an Iterable.

TraversalDescription traversalDescription = Traversal.description()
          .depthFirst()
          .relationships( KNOWS )
          .relationships( LIKES, Direction.INCOMING )
          .prune( Traversal.pruneAfterDepth( 5 ) );
for ( Path position : traversalDescription.traverse( myStartNode )) {
    System.out.println( "Path from start node to current position is " + position );
}

The best way for retrieving start nodes for traversals is using Neo4j's index facilities. The GraphDatabaseService provides access to the IndexManager which in turn retrieves named indexes for nodes and relationships. Both can be indexed with property names and values. Retrieval is done by query methods on Index to return an IndexHits iterator.

IndexManager indexManager = graphDb.index();
Index<Node> nodeIndex = indexManager.forNodes("a-node-index");
nodeIndex.add(node, "property","value");
for (Node foundNode = nodeIndex.get("property","value")) {
    assert node.getProperty("property").equals("value");
}

Note: Spring Data Graph provides auto-indexing via the @Indexed annotation, while this still is a manual process when using the Neo4j API.

Behind the scenes Spring Data Graph leverages AspectJ (Chapter 25, AspectJ introduction) aspects to modify the behavior of simple POJO entities to be able to be backed by a graph store. Each node entity is backed by a graph node that holds its properties and relationships to other entities. AspectJ is used to intercept field access and to retrieve the information from the backing node (either its properties or relationships or dynamic traversals starting from the node). For relationship entities the fields are similarly mapped to properties. There are two specially annotated fields for the start and the end node of the relationship.

The aspect introduces some internal fields and some public methods (Section 19.9, “Methods added to entity classes”) to the entities for accessing the backing state via getPersistentState() and creating relationships with relateTo and retrieving relationship entities via getRelationshipTo. It also introduces graphRepository methods like find(Class<? extends NodeEntity>, TraversalDescription) and equals and hashCode delegation.

Spring Data Graph internally uses an abstraction called EntityState that the field access and instantiation advices of the aspect delegate to, keeping the aspect code very small and focused to the pointcuts and delegation code. The EntityState then uses a number of FieldAccessorFactories to create a FieldAccessor instance per field that does the specific handling needed for the concrete field type.

Entities are declared using the @NodeEntity annotation. Relationship entities use the @RelationshipEntity annotation.

// simplest example
@NodeEntity
public class Movie {
String title;
}

@NodeEntity
public class Group {
@GraphTraversal(traversalBuilder = PeopleTraversalBuilder.class,
    elementClass = Person.class, params = "persons")
private Iterable<Person> people;

private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder {
    @Override
    public TraversalDescription build(NodeBacked start, Field field, String...params) {
        return new TraversalDescriptionImpl()
                .relationships(DynamicRelationshipType.withName(params[0]))
                .filter(Traversal.returnAllButStartNode());
    }
}
}

As relationships are first level citizens in Neo4j, associations between Node-Entities are represented by relationships. In general, relationships are categorized by a type and start and end-nodes (which also imply its direction). They can have an arbitrary number of properties. Spring Data Graph has special support to represent Neo4j relationships as Relationship Entities but this is not mandatory.

@NodeEntity
public class Movie {
private Actor topActor;
}

@NodeEntity
public class Person {
@RelatedTo(type = "topActor", direction = Direction.INCOMING)
private Movie wasTopActorIn;
}

@NodeEntity
public class Actor {
@RelatedTo(type = "ACTS_IN", elementClass = Movie.class)
private Set<Movie> movies;
}

@RelationshipEntity
public class Role {
String title;

@StartNode private Actor actor;
@EndNode private Movie movie;
}

@NodeEntity
public class Actor {
@RelatedToVia(type = "ACTS_IN", elementClass = Role.class)
private Iterable<Role> roles;

public Role playedIn(Movie movie, String title) {
    Role role=relateTo(movie,Role.class,"ACTS_IN");
    role.setTitle(title);
    return role;
}
}

The Neo4j graph database can use different index providers for exact lookups and fulltext searches. Lucene is used as default index provider implementation. There is support for distinct indexes for nodes and relationships which can be configured to be of fulltext or exact types.

@NodeEntity
class Person {
    @Indexed(indexName = "people")
    String name;

    // automatically indexed numerically
    @Indexed
    int age;

}

NodeGraphRepository<Person> graphRepository = graphRepositoryFactory.createNodeEntityRepository(Person.class);

// exact graphRepository
Person mark = graphRepository.findByProperyValue("people","name","mark");

// numeric range queries
for (Person middleAgedDeveloper : graphRepository.findAllByRange(null, "age", 20, 40)) {
    Developer developer=middleAgedDeveloper.projectTo(Developer.class);
}

@NodeEntity
class Person {
    @Indexed(indexName = "person-name", fulltext=true)
    String name;
}

NodeGraphRepository<Person> graphRepository = graphRepositoryFactory.createNodeEntityRepository(Person.class);

// exact graphRepository
Person mark = graphRepository.findAllByQuery("people-search","name","ma*");

@Autowired GraphDatabaseContext gdc;

// exact index
Index<Node> personIndex=gdc.getIndex(Person.class,null);
personIndex.add(node,"name","Mark");

Index<Node> namedPersonIndex=gdc.getIndex(Person.class,"people");
namedPersonIndex.get("name","Mark");

// complex range & sort query
namedPersonIndex.query( new QueryContext( NumericRangeQuery.newÍntRange( "age", 20, 40, true, true ) )
                        .sort( new Sort( new SortField( "age", SortField.INT, false ) ) ) );

// fulltext index
Index<Node> personFulltextIndex=gdc.getIndex(Person.class,"person-name",true);
namedPersonIndex.query("name","Ma*");
namedPersonIndex.query("{name:Ma*}");

            

The repositories provided by Spring Data Graph build on the composable repository infrastructure contained in Spring Data Commons. Those repositories allow the interface based composition of the final repository consisting of provided default implementations for certain interfaces and additional custom implementations for other methods.

Spring Data Graph comes with typed repository implementations that provide methods for locating node and relationship entities. There are 3 types of basic repository interfaces and implementations. One CRUD-Repository (CRUDGraphRepository<T>) that provides basic operations, a IndexQueryExecutor that delegates to Neo4j's internal indexing subsystem for executing queries. And last but not least a TraversalQueryExecutor that handles Neo4J Traversals.

CRUDGraphRepository delegates to the configured TypeRepresentationStrategy (Section 19.8, “Storing type information in the graph”) for type based queries.

IndexQueryExecutor works with the indexing subsystem and provides methods to find entities by indexed properties, ranged queries of combination thereof.

TraversalQueryExecutor works with the traversal framework.

The Repository instances are either created manually via a DirectGraphRepositoryFactory to be bound o a concrete node or relationship entity class. The DirectGraphRepositoryFactory is configured in the Spring context and can be injected.

NodeGraphRepository<Person> graphRepository = graphRepositoryFactory.createNodeEntityRepository(Person.class);

Person michael = graphRepository.save(new Person("Michael",36));

Person dave=graphRepository.findOne(123);

Long numberOfPeople = graphRepository.count();

Person mark = graphRepository.findByPropertyValue(null,"name", "mark");

Iterable<Person> devs = graphRepository.findAllByProperyValue(null, "occupation","developer");

Iterable<Person> middleAgedPeople = graphRepository.findAllByRange(null, "age",20,40);

Iterable<Person> aTeam = graphRepository.findAllByQuery(null, "name","A*");

Iterable<Person> davesFriends = graphRepository.findAllByTraversal(dave,
    Traversal.description().pruneAfterDepth(1)
    .relationships(KNOWS).filter(returnAllButStartNode()));

public interface PersonRepository extends NodeGraphRepository<Person>, PersonRepositoryExtension {
}
// alternatively select some of the required repositories individually
public interface PersonRepository extends CRUDGraphRepository<Node,Person>, IndexQueryExecutor<Node,Person>,
            TraversalQueryExecutor<Node,Person>, PersonRepositoryExtension {
}
// provide a custom extension if needed
public interface PersonRepositoryExtension {
    Iterable<Person> findFriends(Person person);
}
public class PersonRepositoryImpl implements PersonRepositoryExtension {

    // optionally inject default repository, or use DirectGraphRepositoryFactory
    @Autowired PersonRepository baseRepository;
    public Iterable<Person> findFriends(Person person) {
        return baseRepository.findAllByTraversal(person, friendsTraversal);
    }
}

// configure the repositories, preferably via the datagraph:repositories namespace (graphDatabaseContext reference is optional)
<datagraph:repositories base-package="org.springframework.data.graph.neo4j" graph-database-context-ref="graphDatabaseContext"/>

// have it injected
@Autowired
PersonRepository personRepository;

    Person michael = personRepository.save(new Person("Michael",36));

    Person dave=personRepository.findOne(123);

    Iterable<Person> devs = personRepository.findAllByProperyValue(null, "occupation","developer");

    Iterable<Person> aTeam = graphRepository.findAllByQuery(null, "name","A*");

    Iterable<Person> friends = personRepository.findFriends(dave);
    

Neo4j is a transactional datastore which only allows modifications within transaction boundaries and fullfills the ACID properties. Reading from the store is also possible outside of transactions.

Spring Data Graph integrates with transaction managers configured using Spring. The simplest scenario of just running the graph database uses a SpringTransactionManager provided by the Neo4j kernel to be used with Spring's JtaTransactionManager. Note: The explicit XML configuration given below is encoded in the Neo4jConfiguration configuration bean that uses Spring's @Configuration functioanlity. This simplifies the configuration. An example is shown further below.

<bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager">
<property name="transactionManager">
    <bean class="org.neo4j.kernel.impl.transaction.SpringTransactionManager">
        <constructor-arg ref="graphDatabaseService"/>
    </bean>
</property>
<property name="userTransaction">
    <bean class="org.neo4j.kernel.impl.transaction.UserTransactionImpl">
        <constructor-arg ref="graphDatabaseService"/>
    </bean>
</property>
</bean>

<tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>

For scenarios running multiple transactional resources there are two options. First of all you can have Neo4j participate in the externally set up transaction manager using the new SpringProvider by enabling the configuration parameter for your graph database. Either via the spring config or the configuration file (neo4j.properties).

<context:annotation-config />
<context:spring-configured/>

<bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager">
<property name="transactionManager">
    <bean id="jotm" class="org.springframework.data.graph.neo4j.transaction.JotmFactoryBean"/>
</property>
</bean>

<bean class="org.neo4j.kernel.EmbeddedGraphDatabase" destroy-method="shutdown">
<constructor-arg value="target/test-db"/>
<constructor-arg>
    <map>
        <entry key="tx_manager_impl" value="spring-jta"/>
    </map>
</constructor-arg>
</bean>

<tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
                

You can configure a stock XA transaction manager to be used with Neo4j and the other resources (e.g. Atomikos, JOTM, App-Server-TM). For a bit less secure but fast 1 phase commit best effort, use the implementation coming with Spring Data Graph (ChainedTransactionManager). It takes a list of transaction-managers as constructor params and will handle them in order for transaction start and commit (or rollback) in the reverse order.

<bean id="transactionManager"
        class="org.springframework.data.graph.neo4j.transaction.ChainedTransactionManager" >
    <constructor-arg>
        <list>
        <bean class="org.springframework.orm.jpa.JpaTransactionManager" id="jpaTransactionManager">
            <property name="entityManagerFactory" ref="entityManagerFactory"/>
        </bean>
        <bean
            class="org.springframework.transaction.jta.JtaTransactionManager">
            <property name="transactionManager">
                <bean class="org.neo4j.kernel.impl.transaction.SpringTransactionManager">
                    <constructor-arg ref="graphDatabaseService" />
                </bean>
            </property>
            <property name="userTransaction">
                <bean  class="org.neo4j.kernel.impl.transaction.UserTransactionImpl">
                    <constructor-arg ref="graphDatabaseService" />
                </bean>
            </property>
        </bean>
        </list>
    </constructor-arg>
</bean>

By default newly created node entities are in a detached state. When persist() is called on the entity it is attached to the graph store and its properties and relationships are persisted as well. Changing an attached entity inside a transaction will write through the changes to the datastore. Whenever an entity is changed outside of a transaction it will be considered detached. The changed data is stored in the entity itself and not written back to the datastore.

All entities that are returned by library functions are initially in an attached state. Changing them outside of a transaction detaches them. For writing the changes back it is necessary to persist() them again.

Persisting an entity not only persists that single entity but will traverse its existing and new relationships and persist the cluster of detached entities that it is part of. The borders of this cluster are formed by attached entities. The persist operation creates its own, implicit transaction. When it is called withina external transaction it participates otherwise it is an atomic operation.

Please keep in mind that the session handling behaviour is still heavily developed. The defaults and also other aspects of the behaviour are likely to change in subsequent releases. At the moment there is no support for the creation of relationships outside of transactions and also more complex operations like creating whole subgraphs outside of transactions is not supported.

@NodeEntity
class Person {
    String name;
}
Person p = new Person().persist();

There are several ways to represent the Java type hierarchy of the data model in the graph. In general, for all node and relationship entities, type information is needed to perform certain repository operations. Some of this type information is saved in the graph database.

Implementations of TypeRepresentationStrategy take care of persisting this information on entity instance creation. They also provide the repository methods that use this type information to perform their operations, like findAll and count.

There are three available implementations for node entities to choose from.

There are two implementations for relationship entities available, same behavior as the corresponding ones above:

Spring Data Graph will by default autodetect which are the most suitable strategies for node and relationship entities. For new data stores, it will always opt for the indexing strategies. If a data store was created with the olderSubReferenceNodeTypeRepresentationStrategy, then it will continue to use that strategy for node entities. It will however in that case use the no-op strategy for relationship entities, which means that the old data stores have no support for searching for relationship entities. The indexing strategies are recommended for all new users.

The node and relationship aspects introduce (via ITD - inter type declaration) several methods to the entities that make common tasks easier.

As the underlying data model of a graph database doesn't imply and enforce strict type constraints like a relational model does, it offers much more flexibility on how to model your domain classes and which of those to use in different contexts.

For instance an order can be used in these contexts: customer, procurement, logistics, billing, fulfillment and many more. Each of those contexts requires its distinct set of attributes and operations. As Java doesn't support mixins one would put the sum of all of those into the entity class and thereby making it very big, brittle and hard to understand. Being able to take a basic order and project it to a different (not related in the inheritance hierarchy or even an interface) order type that is valid in the current context and only offers the attributes and methods needed here would be very benefitial.

Spring Data Graph offers initial support for projecting node and relationship entities to different target types. All instances of this projected entity share the same backing node or relationship, so data changes are reflected immediately.

This could for instance also be used to handle nodes of a traversal with a unified (simpler) type (e.g. for reporting or auditing) and only project them to a concrete, more functional target type when the business logic requires it.

// not related to Person at all
@NodeEntity
class Trainee {
    String name;
    @RelatedTo(elementClass=Training.class);
    Set<Training> trainings;
}

for (Person person : graphRepository.findAllByProperyValue("occupation","developer")) {
    Developer developer = person.projectTo(Developer.class);
    if (developer.isJavaDeveloper()) {
        trainInSpringData(developer.projectTo(Trainee.class));
    }
}

Spring Data Graph supports property based validation support. So, whenever a property is changed, it is checked against the annotated constraints (.e.g @Min, @Max, @Size, etc). Validation errors throw a ValidationException. For evaluating the constraints the validation support that comes with Spring is used. To use it a validator has to be registered with the GraphDatabaseContext, if there is none, no validation will be performed (any registered Validator or (Local)ValidatorFactoryBean will be used).

@NodeEntity
class Person {
    @Size(min = 3, max = 20)
    String name;

    @Min(0)
    @Max(100)
    int age;
}

As stated in the requirements chapter, Spring Data Graph projects are easiest to build with Apache Maven. The main dependencies are Spring Data Graph itself, Spring Data Commons, some parts of the Spring Framework and of course the Neo4j graph database.

<repository>
  <id>spring-maven-milestone</id>
  <name>Springframework Maven Repository</name>
  <url>http://maven.springframework.org/milestone</url>
</repository>
				

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-neo4j</artifactId>
  <version>1.0.0.RC1</version>
</dependency> 

<dependency>
  <groupId>org.aspectj</groupId>
  <artifactId>aspectjrt</artifactId>
  <version>1.6.11.RELEASE</version>
</dependency>
						

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>aspectj-maven-plugin</artifactId>
  <version>1.0</version>
  <dependencies>
    <!-- NB: You must use Maven 2.0.9 or above or these are ignored (see MNG-2972) -->
    <dependency>
      <groupId>org.aspectj</groupId>
      <artifactId>aspectjrt</artifactId>
      <version>1.6.11.RELEASE</version>
    </dependency>
    <dependency>
      <groupId>org.aspectj</groupId>
      <artifactId>aspectjtools</artifactId>
      <version>1.6.11.RELEASE</version>
    </dependency>
  </dependencies>
  <executions>
    <execution>
      <goals>
        <goal>compile</goal>
        <goal>test-compile</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <outxml>true</outxml>
    <aspectLibraries>
      <aspectLibrary>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aspects</artifactId>
      </aspectLibrary>
      <aspectLibrary>
        <groupId>org.springframework.data</groupId>
        <artifactId>spring-datastore-neo4j</artifactId>
      </aspectLibrary>
    </aspectLibraries>
    <source>1.6</source>
    <target>1.6</target>
  </configuration>
</plugin>
						

The concrete configuration for Spring Data Graph is quite verbose as there is no autowiring involved. It sets up the following parts.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:context="http://www.springframework.org/schema/context"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:datagraph="http://www.springframework.org/schema/data/graph"
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/context 
    http://www.springframework.org/schema/context/spring-context-3.0.xsd
    http://www.springframework.org/schema/data/graph 
    http://www.springframework.org/schema/data/graph/datagraph-1.0.xsd
    ">

    <context:annotation-config/>
    <datagraph:config storeDirectory="target/config-test"/>

</beans>
                    

    <context:annotation-config/>

    <bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase" 
      destroy-method="shutdown">
         <constructor-arg index="0" value="target/config-test" />
    </bean>

    <datagraph:config graphDatabaseService="graphDatabaseService"/>
                    

  <context:annotation-config/>

    <datagraph:config storeDirectory="target/config-test"
      entityManagerFactory="entityManagerFactory"/>

    <bean class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"
      id="entityManagerFactory">
        <property name="dataSource" ref="dataSource"/>
        <property name="persistenceXmlLocation" value="classpath:META-INF/persistence.xml"/>
    </bean>
                    

    <beans>
    ...

        <tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
        <bean class="org.springframework.data.graph.neo4j.config.Neo4jConfiguration"/>

        <bean class="org.springframework.context.annotation.ConfigurationClassPostProcessor"/>

        <bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase"
              destroy-method="shutdown" scope="singleton">
            <constructor-arg index="0" value="target/config-test"/>
        </bean>
    ...
    </beans>
                

Partial graph persistence is achieved by restricting the Spring Data Graph aspects to explicitly annotated parts of the entity. Those fields will be made transient by the aspect so that JPA ignores them and won't try to persist those attributes.

A backing node in the graph store is only created when the entity has been assigned a JPA id. Only then will the connection between the two stores be kept. Until the entity has been persisted, its state is just kept inside the POJO (detached state) and flushed to the backing graph store afterwards.

The connection between the two entities is kept via a FOREIGN_ID field in the node that contains the JPA id (currently only single value ids are supported). The entity class can be resolved via the TypeRepresentationStrategy that manages the Java type hierarchy within the graph. With the id and class, you can then retrieve the appropriate JPA entity for a given node.

The other direction is handled by indexing the Node with the FOREIGN_ID index which contains a concatenation of the fully qualified class name of the JPA entity and the id. So it is possible on instantiation of a JPA id via the entity manager (or some other means like creating the POJO and setting its id manually) to find the matching node using the index facilities and reconnect them.

Using those mechanisms and the Spring Data Graph aspects a single POJO can contain fields that are handled by JPA and other fields (which might be relationships as well) that are handled by Spring Data Graph.

The following example is taken from the Spring Data Graph examples, it is contained in the myrestaurant-social project.

	@Entity
	@Table(name = "user_account")
	@NodeEntity(partial = true)
	public class UserAccount {
	    private String userName;
	    private String firstName;
	    private String lastName;

	    @GraphProperty
	    String nickname;

	    @RelatedTo(type = "friends", elementClass = UserAccount.class)
	    Set<UserAccount> friends;

	    @RelatedToVia(type = "recommends", elementClass = Recommendation.class)
	    Iterable<Recommendation> recommendations;

	    @Temporal(TemporalType.TIMESTAMP)
	    @DateTimeFormat(style = "S-")
	    private Date birthDate;

		@ManyToMany(cascade = CascadeType.ALL)
	    private Set<Restaurant> favorites;

		@Id
	    @GeneratedValue(strategy = GenerationType.AUTO)
	    @Column(name = "id")
	    private Long id;

	    @Transactional
	    public void knows(UserAccount friend) {
	        relateTo(friend, "friends");
	    }

		@Transactional
	    public Recommendation rate(Restaurant restaurant, int stars, String comment) {
	        Recommendation recommendation = relateTo(restaurant, Recommendation.class, "recommends");
	        recommendation.rate(stars, comment);
	        return recommendation;
	    }
	    public Iterable<Recommendation> getRecommendations() {
	        return recommendations;
	    }
	}

Configuring cross-store persistence is done similarly to the default Spring Data Graph operations. As soon as you refer to an entityManagerFactory in the xml-namespace it is set up for cross-store persistence.

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:context="http://www.springframework.org/schema/context"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:datagraph="http://www.springframework.org/schema/data/graph"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans 
		http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
		http://www.springframework.org/schema/context 
		http://www.springframework.org/schema/context/spring-context-3.0.xsd
		http://www.springframework.org/schema/data/graph 
		http://www.springframework.org/schema/data/graph/datagraph-1.0.xsd
		">

	<context:annotation-config/>

    <datagraph:config storeDirectory="target/config-test"
        entityManagerFactory="entityManagerFactory"/>

    <bean class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"
      id="entityManagerFactory">
        <property name="dataSource" ref="dataSource"/>
        <property name="persistenceXmlLocation" value="classpath:META-INF/persistence.xml"/>
    </bean>
</beans>

Spring Data Graph comes with a number of samples. The source code of the samples is found on GitHub. The different sample projects are introduced below.

The Hello Worlds sample application is a simple console application with unit tests, that creates some Worlds (entities / nodes) and Rocket Routes (relationships) in a Galaxy (graph) and then reads them back and prints them out.

The unit tests demonstrate some other features of Spring Data Graph. The sample comes with a minimal configuration for Maven and Spring to get up and running quickly.

Executing the application creates the following graph in the Graph Database:

A web application that imports datasets from the Internet Movie Database (IMDB) into the graph database. It allows listings of movies with their actors and actors with their roles in different movies. It also uses graph traversal operations to calculate the Kevin Bacon number (distance to an actor that has acted with Kevin Bacon). This sample application shows the basic usage of Spring Data Graph in a more complex setting with several annotated entities and relationships as well as usage of indices and graph traversal.

See the readme file for instruction on how to compile and run the application.

An excerpt of the data stored in the Graph Database after executing the application:

Simple, JPA based web application for managing users and restaurants, with the ability to add restaurants as favorites to a user.

An extended version of the MyRestaurant sample application that adds social networking functionality to it. It is possible to have friends and to add rated relationships to restaurants. The relationships and some of the properties of the entities are transparently stored in the graph database. There is also a graph traversal that provides a recommendation based on your friends' (and their friends') rating of restaurants.

An excerpt of the data stored in the Graph Database after executing the application:

The focus of Spring Data Graph is to add a convenience layer on top of the native Neo4j API. This should enable developers to get up and running with the graph database very quickly, having their domain objects mapped to the graph. Building on this foundation one can later explore other, more efficient ways to explore and process the graph - if the performance requirements demand it.

Like any other object mapping framework, the domain entities that are created, read or persisted represent only a small fraction of the data stored in the database. This is the set needed for a certain use-case to be displayed, edited or processed in a low throughput fashion. The main advantages of using an object mapper in this case is the ease of use of real domain objects in your business logic and also with existing frameworks and libraries that expect Java POJOs as input or create them as results.

Spring Data Graph was not designed with a major performance focus. It adds some overhead to pure graph operations. Something to keep in mind is, that the access of properties and relationships is a read trough in the attached case. So to avoid multiple read-throughs it is sensible to store the result in a local variable at the scope of use (method, class or jsp for example).

Most of the overhead comes from the use of the Java Reflection API, which is leveraged to provide information about Annotations, Fields and Constructors. Some of the information is already cached by the JVM and the library, so that only the first access gets a performance penalty.

For direct retrieval of nodes and relationships the getReferenceNode, getNode and getRelationship can be used.

There are methods (createNode and createRelationship) for creating nodes and relationships that automatically set provided properties and optionally index certain fields.

Neo4jOperations neo = new Neo4jTemplate(grapDatabase);

Node michael = neo.createNode(_("name","Michael"));
Node mark = neo.createNode(_("name","Mark"));
Node thomas = neo.createNode(_("name","Thomas"));

neo.createRelationship(mark,thomas, WORKS_WITH, _("project","spring-data"));

neo.index("devs",thomas, "name","Thomas");

assert "Mark".equals(neo.query("devs","name","Mark",new NodeNamePathMapper()));

Adding nodes and relationships to an index is achieved using the index method.

Query methods either take a field / value combination to look for exact matches in the index or a lucene query object or string to handle more complex queries. All query methods provide Path results to a PathMapper.

Traversal methods are at the core of graph operations. As such, they are fully supported in the Neo4jTemplate. The traverseNext method traverses to the direct neighbours of the start node filtering the relationships according to its parameters.

The traverse method covers the full traversal operation that takes a powerful TraversalDescription (most probably built from the Traversal.description() DSL) and runs it from the start node. Each path that is returned via the traversal is passed to the PathMapper to be processed accordingly.

For the querying operations Neo4jTemplate unifies the result with the Path abstraction that comes from Neo4j. Much like a resultset a path contains nodes() and relationships() starting at a startNode() and ending with aendNode(), the lastRelationship() is also available separately. The Path abstraction also wraps results that contain just nodes or relationships.

Using implementations of PathMapper<T> and PathMapper.WithoutResult (comparable with RowMapper and RowCallbackHandler) the paths can be converted to arbitrary Java objects.

With EntityPath and EntityMapper there is also support for using annotation based NodeEntities within the Path and PathMapper constructs.

The Neo4jTemplate provides configurable implicit transactions for all its methods. By default it creates a transaction for each call (which is a no-op if there is already a transaction running). If you call the constructor with the useExplicitTransactions parameter set to true, it won't create any transactions so you have to provide them using @Transactional or the TransactionTemplate.

What is the use-case for writing server extensions? The REST API is a pretty generic representation of the Neo4j core API. It is nice for getting started and simple scenarios. For more involved solutions that require high speed and high volume access to the embedded graph database, writing a server extension that is able to process external parameters and return just the relevant information to the calling client is preferrable.

The Neo4j server has two built in extension mechanisms. It is possible to add extensions to existing endpoints like the graph database, nodes or relationships - add new URIs or methods to those. This is achieved by writing Server Plugins.

For complete freedom in your implementation an unmanaged extension might be the right solution. Unmanaged extensions are Jersey resource implementations. The resources constructors or methods can get the GraphDatabaseService injected to execute the necessary operations and return appropriate Representations.

Both kinds of extensions have to be packaged as a jar and added to the Neo4j-Server's plugin directory. Server Plugins are picked up at server startup when they provide the necessary META-INF.services/org.neo4j.server.plugins.ServerPlugin file for Javas service loader mechanism. Unmanaged extensions have to be registered with the Neo4j Server configuration.

org.neo4j.server.thirdparty_jaxrs_classes=com.example.mypackage=/my-context
        

Running Spring Data Graph on the server is easy. You need to tell the server where to find the Spring Context file, and which beans from it to expose, using what type:

public class HelloWorldInitializer extends SpringPluginInitializer {
    public HelloWorldInitializer() {
        super(new String[]{"spring/helloWorldServer-Context.xml"}, 
        		Pair.of("worldRepository", WorldRepository.class),
        		Pair.of("graphRepositoryFactory", GraphRepositoryFactory.class));
    }
}
    

Now, your resources can be annotated with the beans they need, like this:

	@Path( "/path" )
	@POST
	@Produces( MediaType.APPLICATION_JSON )
	public void foo( @Context WorldRepository repo ) {
		...
	}

The SpringPluginInitializer merges the graph database service with the spring configuration and registers the named beans as jersey Injectables. It is still necessary to list the initializer fully qualified class name in a file named META-INF/services/org.neo4j.server.plugins.PluginLifecycle. Then the Neo4j Server can pick up and run the initialization classes before the the extensions are loaded.

Spring Data Graph can use the Java Rest Bindings which come as a drop in replacement for the GraphDatabaseService API. Just by configuring the graphDatabaseService to be a RestGraphDatabaseService pointing to the correct URL, a Neo4j-REST server can be used.

To set up your project to use the REST bindings, add this dependency to your pom.xml:

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-neo4j-rest</artifactId>
  <version>1.0.0.RC1</version>
</dependency>

Now, you set up the normal SDG configuration, but point the database to an URL instead of a local file, like this:

<datagraph:config graphDatabaseService="graphDatabaseService"/>

<bean id="graphDatabaseService" class="org.neo4j.rest.graphdb.RestGraphDatabase">
    <constructor-arg value="http://localhost:7474/db/data/"/>
</bean>

Your project is now set up to work against a remote Neo4j Server.