To set up the project we created a public github account and began setting up the infrastructure for a spring web project using Maven as the build system. So we added the dependencies for the Spring Framework libraries, added 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 in place we were ready for the first spike: creating a simple MovieController showing a static view. See the Spring Framework documentation for information on doing this.

<?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 by doing mvn jetty:run to see if there were any obvious issues with the config. It all seemed to work just fine.

Relationships without properties ("anonymous" relationships) don't require any @RelationshipEntity classes. Unfortunately we had none of those, because our relationships were richer. Therefore we went with 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 the new keyword, but we got an exception saying that it was not allowed. At first this surprised us, but then we realized that a relationship entity must have a starting entity and ending entity. It turned out that the aspect had introduced a entity.relateTo method in the node entities. It turned out to be exactly what we needed. We simply added a method to the Actor class, connecting it to movies.

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

Now we wanted to find connected entities. We already had fields for the relationships in both classes. Now it was time to annotate them correctly. It turned out that we needed to provide the target type of the fields again, due to Java's type erasure. The Neo4j relationship type and direction were easy to figure out. The direction even defaulted to outgoing, so we only had to specify it for the movie.

@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> movies;

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

While reading about these relationship collections, we learned that they are actually Spring Data Graph-managed sets. So whenever we add or remove something from the set, it automatically gets reflected in the underlying relationships. That's neat! But this also meant we did not need to initialize the fields. That could be easy to forget.

We made sure to add a test for those, so we were assured that the collections worked as advertised.

But we still couldn't access the Role relationships. It turned out that there was a separate annotation @RelatedToVia for accessing the actual relationship entities . And we had to declare the field as an Iterable<Role>, with read-only semantics. This appeared to mean that we were not able to add new roles though the field. Adding relationship entities seemed like it had to be done by using entity.relateTo(). 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 watching the tests pass, we were confident that the relationship fields really mirrored the underlying relationships in the graph. We were pretty satisfied with our domain.

Before we opened the gates we needed to add some movie data. 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>

Accessing the URI showed the single added movie on screen.

Being the geeks we are, we also wanted to inspect the raw data in the database. Reading the Neo4j docs, there were a couple of different ways of going about this.

10.2.1. Neoclipse visualization

First we tried Neoclipse, an Eclipse RCP application/plugin that opens an existing graph store and visualizes its content. After getting an exception about concurrent access, we learned that we have to use Neoclipse in read-only mode when our webapp was still running. Good to know.

neo4j-shell -readonly -path data/graph.db

neo4j-sh[readonly] (0)$ help
Available commands: index dbinfo ls rm alias set eval mv gsh env rmrel mkrel
                    trav help pwd paths ... man cd
Use man <command> for info about each command.

neo4j-sh[readonly] (0)$ index --cd -g User login micha

neo4j-sh[readonly] (Micha,1)$ ls
*__type__ =[org.neo4j.cineasts.domain.User]
*login    =[micha]
*name     =[Micha]
*roles    =[ROLE_ADMIN,ROLE_USER]
(me) --[FRIEND]-> (Olliver,2)
(me) --[RATED]-> (The Matrix,3)

neo4j-sh[readonly] (Micha,1)$ ls 2
*__type__ =[org.neo4j.cineasts.domain.User]
*login    =[ollie]
*name     =[Olliver]
*roles    =[ROLE_USER]
(Olliver,2) <-[FRIEND]-- (me)

neo4j-sh[readonly] (Micha,1)$ cd 3

neo4j-sh[readonly] (The Matrix,3)$ ls
*__type__     =[org.neo4j.cineasts.domain.Movie]
*description  =[Neo is a young software engineer and part-time hacker who is singled  ...]
*genre        =[Action]
*homepage     =[http://whatisthematrix.warnerbros.com/]
...
*studio       =[Warner Bros. Pictures]
*tagline      =[Welcome to the Real World.]
*title        =[The Matrix]
*trailer      =[http://www.youtube.com/watch?v=UM5yepZ21pI]
*version      =[324]
(me) <-[ACTS_IN]-- (Marc Aden,19)
(me) <-[ACTS_IN]-- (David Aston,18)
...
(me) <-[ACTS_IN]-- (Keanu Reeves,6)
(me) <-[DIRECTED]-- (Andy Wachowski,5)
(me) <-[DIRECTED]-- (Lana Wachowski,4)
(me) <-[RATED]-- (Micha,1)
            

The next thing was to allow users to search for movies, so we needed some fulltext search capabilities. As the index provider implementation of Neo4j is based on Apache Lucene, we were delighted to see that fulltext indexes were supported out of the box.

We happily annotated the title field of the Movie class with @Indexed(fulltext = true). We got an exception back telling us that we have to specify a separate index name. So we simply changed it to @Indexed(fulltext = true, indexName = "search"). The corresponding repository method is called findAllByQuery. To restrict the size of the returned set we simply added a limit that truncates the result.

public class CineastRepository {
    ....
    public void List<Movie> findMovies(String query, int count) {
        List<Movie> movies=new ArrayList<Movie>(count);
        ClosableIterable<Movie> searchResults = movieRepository.findAllByQuery("title", query);
        for (Movie movie : searchResults) {
            movies.add(movie);
            if (count-- == 0) break;
        }
        searchResults.close();
        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 were accessible through 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>
            

The UI now looked like this:

So we started out by taking the User class that we'd already coded and made it a full-fledged Spring Data Graph entity. We added the ability to make friends and to rate movies. With that we also added a simple UserRepository that was able to look up users by ID.

@NodeEntity
class User {
    @Indexed String login;
    String name;
    String password;

    @RelatedToVia(elementClass = Rating.class, type = RATED)
    Iterable<Rating> ratings;

    @RelatedTo(elementClass = User.class, type = "FRIEND", direction=Direction.BOTH)
    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 the 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 class to be able to get a movie's ratings, and also 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 = 0, count = 0;
        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. The next steps were to add this information to the movie presentation in the UI, and creating a user profile page. But for that to happen, users must first 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. Properties can be added to nodes and relationships.

Graph databases are well suited for storing most kinds of domain models. In almost all domain models, there are certain things connected to other things. In most other modeling approaches, the relationships between things are reduced to a single link without identity and attributes. Graph databases allow one to keep the rich relationships that originate from the domain, equally well-represented in the database without resorting to also modeling the relationships as "things". There is very little "impedance mismatch" when putting real-life domains into a graph database.

Neo4j is a graph database. It is a fully transactional database (ACID) that stores data structured as graphs. A graph consists of nodes, connected by relationships. Inspired by the structure of the human brain, it allows for high query performance on complex data, while remaining intuitive and simple for the developer.

Neo4j has been in commercial development for 10 years and in production for over 7 years. Most importantly it has a helpful and contributing community surrounding it, but it also:

In addition, Neo4j has ACID transactions, durable persistence, concurrency control, transaction recovery, high availability, and more. 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 the IndexManager), database life cycle callbacks, transaction management, and more.

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

Using the API of GraphDatabaseService, it is easy to create nodes and relate them to each other. Relationships are typed. Both nodes and relationships can have properties. Property values can be primitive Java types and Strings, or arrays of Java primitives or Strings. Node creation and modification has to happen within a transaction, while reading from the graph store can be done 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 a DSL for defining TraversalDescriptions that can then be applied to a start node and will produce a lazy java.lang.Iterable result of nodes and/or relationships.

TraversalDescription traversalDescription = Traversal.description()
        .depthFirst()
        .relationships(KNOWS)
        .relationships(LIKES, Direction.INCOMING)
        .evaluator(Evaluators.toDepth(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 by using Neo4j's integrated index facilities. The GraphDatabaseService provides access to the IndexManager which in turn provides named indexes for nodes and relationships. Both can be indexed with property names and values. Retrieval is done with query methods on indexes, returning an IndexHits iterator.

Spring Data Graph provides automatic indexing via the @Indexed annotation, eliminating the need for manual index management.

IndexManager indexManager = graphDb.index();
Index<Node> nodeIndex = indexManager.forNodes("a-node-index");
Node node = ...;
Transaction tx = graphDb.beginTx();
try {
    nodeIndex.add(node, "property","value");
    tx.success();
} finally {
    tx.finish();
}
for (Node foundNode : nodeIndex.get("property","value")) {
    // found node
}

Behind the scenes, Spring Data Graph leverages AspectJ aspects to modify the behavior of simple annotated POJO entities (see Chapter 25, AspectJ details). Each node entity is backed by a graph node that holds its properties and relationships to other entities. AspectJ is used for intercepting field access, so that Spring Data Graph can retrieve the information from the entity's backing node or relationship in the database.

The aspect introduces some internal fields and some public methods (see Section 19.9, “Introduced methods”) in the entities, such as entity.getPersistentState() and entity.relateTo. It also introduces repository methods like find(Class<? extends NodeEntity>, TraversalDescription), and equals() and hashCode delegation, making equals() honor the backing state.

Spring Data Graph internally uses an abstraction called EntityState that the field access and instantiation advices of the aspect delegate to. This way, the aspect code is kept to a minimum, focusing mainly on 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. There are various layers of caching involved as well, so it handles repeat instantiation efficiently.

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

@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());
        }
    }
}

Since relationships are first-class 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 imply the direction of the relationship). Relationships can have an arbitrary number of properties. Spring Data Graph has special support to represent Neo4j relationships as entities too, but it is often not needed.

@NodeEntity
public class Movie {
    private Actor mostPaidActor;
}

@NodeEntity
public class Actor {
    @RelatedTo(type = "mostPaidActor", direction = Direction.INCOMING,
            elementClass = Movie.class)
    private Set<Movie> mostPaidIn;

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

@NodeEntity
public class Actor {
    public Role playedIn(Movie movie, String title) {
        return relatedTo(movie, Role.class, "ACTS_IN");
    }
}

@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 so-called index providers for exact lookups and fulltext searches. Lucene is the default index provider implementation. Each named index is configured to be fulltext or exact.

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

GraphRepository<Person> graphRepository = graphRepositoryFactory
        .createGraphRepository(Person.class);

// Exact match, in named index
Person mark = graphRepository.findByPropertyValue("people", "name", "mark");

// Numeric range query, index name inferred automatically
for (Person middleAgedDeveloper : graphRepository.findAllByRange("age", 20, 40)) {
    Developer developer=middleAgedDeveloper.projectTo(Developer.class);
}

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

GraphRepository<Person> graphRepository = graphRepositoryFactory
        .createGraphRepository(Person.class);

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

@Autowired GraphDatabaseContext gdc;

// Default index
Index<Node> personIndex = gdc.getIndex(Person.class);
personIndex.query(new QueryContext(NumericRangeQuery.newÍntRange("age", 20, 40, true, true))
                       .sort(new Sort(new SortField("age", SortField.INT, false))));

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

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

The repositories provided by Spring Data Graph build on the composable repository infrastructure in Spring Data Commons. They allow for interface based composition of repositories 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. CRUDRepository provides basic operations, IndexRepository and NamedIndexRepository delegate to Neo4j's internal indexing subsystem for queries, and TraversalRepository handles Neo4j traversals.

GraphRepository is a convenience repository interface, extending CRUDRepository, IndexRepository, and TraversalRepository. Generally, it has all the desired repository methods. If named index operations are required, then NamedIndexRepository may also be included.

GraphRepository<Person> graphRepository = graphRepositoryFactory
        .createGraphRepository(Person.class);

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

Person dave = graphRepository.findOne(123);

Long numberOfPeople = graphRepository.count();

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

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

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

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

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

public interface PersonRepository extends GraphRepository<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("occupation","developer");

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

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

Neo4j is a transactional database, only allowing modifications to be performed within transaction boundaries. Reading data does however not require 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. That is, configuring Spring to use Neo4j's transaction manager.

<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 with multiple transactional resources there are two options. The first option is to have Neo4j participate in the externally configured transaction manager by using the Spring support in Neo4j by enabling the configuration parameter for your graph database. Neo4j will then use Spring's transaction manager instead of its own.

<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"/>

One can also configure a stock XA transaction manager (e.g. Atomikos, JOTM, App-Server-TM) to be used with Neo4j and the other resources. For a bit less secure but fast 1 phase commit best effort, use ChainedTransactionManager, which comes bundled with Spring Data Graph. 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="jpaTransactionManager"
        class="org.springframework.orm.jpa.JpaTransactionManager">
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>
<bean id="jtaTransactionManager"
        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>
<bean id="transactionManager"
        class="org.springframework.data.graph.neo4j.transaction.ChainedTransactionManager">
    <constructor-arg>
        <list>
            <ref bean="jpaTransactionManager"/>
            <ref bean="jtaTransactionManager"/>
        </list>
    </constructor-arg>
</bean>

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

Node entities can be in two different persistence state: attached or detached. By default, newly created node entities are in the detached state. When persist() is called on the entity, it becomes attached to the graph, and its properties and relationships are stores in the database. If persist() is not called within a transaction, it automatically creates an implicit transaction for the operation.

Changing an attached entity inside a transaction will immediately write through the changes to the datastore. Whenever an entity is changed outside of a transaction it becomes detached. The changes are stored in the entity itself until the next call to persist().

All entities returned by library functions are initially in an attached state. Just as with any other entity, changing them outside of a transaction detaches them, and they must be reattached with persist() for the data to be saved.

@NodeEntity
class Person {
    String name;
    Person(String name) { this.name = name; }
}

// Store Michael in the database.
Person p = new Person("Michael").persist();

@NodeEntity
class Movie {
    private Actor topActor;
    public void setTopActor(Actor actor) {
        topActor = actor;
    }
}

@NodeEntity
class Actor {
}

Movie movie = new Movie();
Actor actor = new Actor();

movie.setTopActor(actor);

actor.setName("Billy Bob");
movie.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 AspectJ ITD - inter type declaration) several methods to the entities.

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.

@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. When a property is changed, it is checked against the annotated constraints, e.g. @Min, @Max, @Size, etc. Validation errors throw a ValidationException. The validation support that comes with Spring is used for evaluating the constraints. To use this feature, a validator has to be registered with the GraphDatabaseContext.

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

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

Spring Data Graph projects are easiest to build with Apache Maven. The main dependencies are: Spring Data Graph itself, Spring Data Commons, parts of the Spring Framework, and 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.RELEASE</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>

Users of Spring Data Graph have two ways of very concisely configuring it. Either they can use a Spring Data Graph XML configuration namespace, or they can use a Java-based bean configuration.

<?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/>

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

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

<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 manage only explicitly annotated parts of the entity. Those fields will be made @Transient by the aspect so that JPA ignores them.

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

The association between the two entities is maintained 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 database. Given 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. The matching node can then be found using the indexing facilities, and the two entities can be reassociated.

Using these mechanisms and the Spring Data Graph aspects, a single POJO can contain some fields handled by JPA and others handles by Spring Data Graph. This also includes relationship fields persisted in the graph database.

Cross-store persistence only requires the use of one additional annotation: @GraphProperty. See below for details and an example.

The following example is taken from the Spring Data Graph examples myrestaurants-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 configuration. All you need to do is to specify an entityManagerFactory in the XML namespace config element, and Spring Data Graph will configure itself for cross-store use.

<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 sample applications. The source code of the samples can be found on Github. The different sample projects are introduced below.

The Hello Worlds sample application is a simple console application. It creates some worlds (node entities) and rocket routes (relationships) between worlds, all in a galaxy (the graph), and then prints them.

The unit tests demonstrate some other features of Spring Data Graph as well. 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:

The IMDB sample is a web application that imports datasets from the Internet Movie Database (IMDB) into the graph database. It allows the listing of movies with their actors, and of actors and their roles in different movies. It also uses graph traversal operations to calculate the Bacon number of any given actor. This sample application shows the usage of Spring Data Graph in a more complex setting, using several annotated entities and relationships as well as indexes and graph traversals.

See the readme file for instructions 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. It is basically the foundation for the MyRestaurants-Social application (seeSection 22.5, “MyRestaurant-Social sample application”), and does therefore not use Spring Data Graph.

This application extends the MyRestaurants sample application, adding social networking functionality to it with cross-store persistence. The web application allows for users to add friends and rate restaurants. A graph traversal provides recommendations based on your friends' (and their friends') rating of restaurants.

Here's 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 Neo4j API. This enables developers to get up and running with a graph database very quickly, having their domain objects mapped to the graph with very little work. Building on this foundation, one can later explore other, more efficient ways to explore and process the graph - if the performance requirements demand it.

Spring Data Graph was however not designed with a major focus on performance. It does add some overhead to pure graph operations. Something to keep in mind is that any access of properties and relationships will in general read through down to the database. To avoid multiple reads, it is sensible to store the result in a local variable in suitable scope (e.g. method, class or jsp).

Most of the overhead comes from the use of the Java Reflection API, which is used 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() methods can be used.

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

import static org.springframework.data.graph.core.Property._;

Neo4jOperations neo = new Neo4jTemplate(graphDatabaseService);

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 done with the index() method.

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

The 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 neighbors of the start node, filtering the relationships according to the parameters.

The traverse() method covers the full traversal operation that takes a TraversalDescription (typically built with the Traversal.description() DSL) and runs it from the start node. Each path that is returned by the traversal is passed to the PathMapper to be converted into the desired type.

For the querying operations Neo4jTemplate unifies the result with the Path abstraction that comes from Neo4j. Much like a result set, a path contains a chain of nodes() connected by relationships(), starting at a startNode() and ending at a endNode(). 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 node entities 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.

When should you write a server extension? The default REST API is essentially a REST'ified representation of the Neo4j core API. It is nice for getting started, and for simpler scenarios. For more involved solutions that require high-volume access or more complex operations, writing a server extension that is able to process external parameters, do all the computations locally in the plugin, and then return just the relevant information to the calling client is preferable.

The Neo4j Server has two built-in extension mechanisms. It is possible to extend existing URI endpoints like the graph database, nodes, or relationships, adding new URIs or methods to those. This is achieved by writing a server plugin. This plugin type has some restrictions though.

For complete freedom in the implementation, an unmanaged extension can be used. Unmanaged extensions are essentially Jersey resource implementations. The resource 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 JAR files and added to the Neo4j Server's plugin directory. Server Plugins are picked up by the server at startup if they provide the necessary META-INF.services/org.neo4j.server.plugins.ServerPlugin file for Java's ServiceLoader facility. 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 Neo4j Server is easy. You need to tell the server where to find the Spring context configuration file, and which beans from it to expose:

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 GraphDatabaseService with the Spring configuration and registers the named beans as Jersey Injectables. It is still necessary to list the initializer's fully qualified class name in a file named META-INF/services/org.neo4j.server.plugins.PluginLifecycle. The Neo4j Server can then pick up and run the initialization classes before the extensions are loaded.

Spring Data Graph can use a set of Java REST bindings which come as a drop in replacement for the GraphDatabaseService API. By simply configuring the graphDatabaseService to be a RestGraphDatabase pointing to a Neo4j Server instance.

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.RELEASE</version>
</dependency>

Now, you set up the normal Spring Data Graph configuration, but point the database to an URL instead of a local directory, like so:

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