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

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

We spun up Tomcat in STS with the App and it worked fine. For completeness we also added Jetty to the maven-config and tested it by invoking 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 the Role we tried to create the relationship entity just by instantiating it with new and saving it with the template, but we got an exception saying that it misses the relationship-type.

We had to add it to the @RelationshipEntity as an attribute (or as a @RelationshipType annotated field in the RelationshipEntity). Another way to create instances of relationship-entities is to use the methods provided by the template, like createRelationshipBetween.

@RelationshipEntity(type="ACTS_IN")
class Role {
    @StartNode Actor actor;
    @EndNode Movie movie;
    String role;
}
class Actor {
...
    public Role playedIn(Movie movie, String roleName) {
        Role role = new Role(this, movie, roleName);
        this.roles.add(role);
        return role;
    }
}

    Role role = tomHanks.playedIn(forrestGump, "Forrest Gump");

    // either save the actor
    template.save(tomHanks);
    // or the role
    template.save(role);

    // alternative approach
    Role role = template.createRelationshipBetween(actor,movie,
                           Role.class, "ACTS_IN");

Saving just the actor would take care of relationships with the same type between two entities and remove the duplicates. Whereas just saving the role happily creates another relationship with the same type.

Now we wanted to find connected entities. We already had fields for the relationships in both classes. It was time to annotate them correctly. 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. If we want to use the same relationship between the two entities we have to make sure to provide a dedicated type, otherwise the field-names would be used resulting in different relationships.

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

@NodeEntity
class Actor {
    @Indexed(unique=true) int id;
    String name;
    @RelatedTo(type = "ACTS_IN")
    Set<Movie> movies;

    public Role playedIn(Movie movie, String roleName) {
        return new Role(this,movie, roleName);
    }
}

Changes to the collections of related entities are reflected into the graph on saving of the entity.

We made sure to add some tests for using the relationshhips, so we were assured that the collections worked as advertised.

But we still couldn't access the Role relationship entities themselves. It turned out that there was a separate annotation @RelatedToVia for accessing the actual relationship entities. And we could declare the field as an Iterable<Role>, with read-only semantics or on a Collection or Set<Role> field with modifying semantics. So off we went, creating our first real relationship (just kidding).

To have the collections of relationships being read eagerly during the loading of the Movie we have to annotate it with the @Fetch annotation. Otherwise Spring Data Neo4j refrains from following relationships automatically. The risk of loading the whole graph into memory would be too high.

@NodeEntity
class Movie {
    @Indexed(unique=true) String id;
    String title;
    int year;

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

After watching the tests pass, we were confident that the changes to the relationship fields were really stored to the underlying relationships in the graph. We were pretty satisfied with persisting 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. A simple /populate endpoint for the controller that called it would be enough for now.

@Service
public class DatabasePopulator {

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

@Controller
public class MovieController {

    @Autowired private DatabasePopulator populator;

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

Accessing the URI we could see the list of movies we had added.

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

bash# neo4j-shell -readonly -path data/graph.db
bash# neo4j-shell -readonly -port 1337

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 default 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(type = FULLTEXT). Next thing we got an exception telling us that we had to specify a separate index name. So we simply changed it to @Indexed(type = FULLTEXT, indexName = "search").

With derived finder methods, finding things became easy. By simply declaring a finder-method name that expressed the required properties, it worked without annotations. Cool stuff and you could even tell it that it should return pages of movies, its size and offset specified by a Pageable which also contains sort information. Using the like operator indicates that fulltext search should be used, instead of an exact search.

public interface MovieRepository ... {
    Movie findById(String id);
    Page<Movie> findByTitleLike(String title, Pageable page);
}

We then used this result in the controller to render a page 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) {
    Page<Movie> movies = repository.findByTitleLike(query, new PageRequest(0,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 Neo4j entity. We added the ability to create friends and to rate movies. With that we also added a simple UserRepository that was able to look up users by ID.

The relationships of the user are his friends and the movie-ratings which is implemented with a Rating Relationship-Entity. This time we used a different approach (for educational and curiosity purposes) to create the Rating relationships. The createRelationshipBetween operation of the Neo4jTemplate was our matchmaker of choice.

@NodeEntity
class User {
    @Indexed(unique=true) String login;
    String name;
    String password;

    @RelatedToVia(type = RATED)
    @Fetch Set<Rating> ratings;

    @RelatedTo(type = "FRIEND", direction=Direction.BOTH)
    @Fetch Set<User> friends;

    public Rating rate(Neo4jOperations template, Movie movie, int stars, String comment) {
        final Rating rating = template.createRelationshipBetween(this, movie, Rating.class, RATED, false);
        rating.rate(stars, comment);
        return template.save(rating);
    }

    public void addFriend(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");
    Movie forestGump = new Movie("1", "Forrest Gump");
    tomHanks.playedIn(forestGump, "Forrest");
    template.save(tomHanks);

    User me = template.save(new User("micha", "Micha", "password"));
    Rating awesome = me.rate(template, forestGump, 5, "Awesome");

    User ollie = template.save(new User("ollie", "Oliver", "password"));
    ollie.rate(template,forestGump, 2, "ok");
    me.addFriend(ollie);
    template.save(me);
    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(type="RATED", direction = Direction.INCOMING)
    @Fetch 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.

Getting the Neo4j-Server was easy, we just went to neo4j.org and downloaded the latest version. Starting it on the command-line (or installing it as a service) was a no-brainer as well.

We copied our store-directory into the data/graph.db directory of the server and started it up again. The admin console of Neo4j-Server, called 'web-admin' is pretty. Using JavaScript, it renders the graph visually in a highly configurable way. It also gave us the possibility to issue queries over a console, another handy feature.

So, how would we get our app connected to this server? It turned out the changes in configuration and setup where minimal. Spring Data Neo4j already came with a module that took care of the remote protocol. We added that maven dependency and changed the graph database used in the Spring Configuration.

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-neo4j-rest</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

<neo4j:config graphDatabaseService="graphDatabaseService"/>
<bean id="graphDatabaseService" 
	class="org.springframework.data.neo4j.rest.SpringRestGraphDatabase">
  <constructor-arg index="0" value="http://localhost:7474/db/data" />
</bean>

After those two changes we restarted the app, and ... it worked. The transparent handling of the remote API was impressive. We learned that it uses a library called java-rest-binding under the hood which is also usable without the Spring Framework.

Of course we noticed performance implications. Especially after moving the server to a remote machine. It turned out that the server supported remote execution of many operations, allowing us to run the graph traversal and querying inside the server. That means looking at our graph interactions and changing them in a way that switched from the transparent, direct graph access via the entities to a different interaction pattern.

We looked into the different modes of remotely executed operations and found traversals, Cypher and Gremlin queries and index lookups. Most of them already matched our needs but the Cypher and Gremlin approaches were best suited, because they also handled index operations and allowed to return partial attribute sets and subgraphs.

So we looked at our use-case (aka page)-based interactions with the graph entities and converted them to Cypher queries on repositories where appropriate, measuring the performance improvements as we went.

There was also a nice mechanism of mapping Cypher query results to Domain Concepts. You just had to declare and annotate an interface that represents the query results as domain entities and the nodes and relationships returned by Cypher were converted into the appropriate entities.

public interface MovieRepository extends GraphRepository<Movie> {

    @Query("START movie=node:Movie(id={0}) 
            MATCH movie-[rating?:rating]->(),
                  movie<-[:ACTS_IN]-actor 
            RETURN movie, COLLECT(actor), AVG(rating.stars)")
    MovieData getMovieData(String movieId);

    @MapResult
    public interface MovieData {
        @ResultColumn("movie")
        Movie getMovie();

        @ResultColumn("AVG(rating.stars)")
        Double getRating();

        @ResultColumn("COLLECT(actor)")
        Iterable<Actor> getCast();
    }
}

This allowed us to get all the data needed for rendering a page in a single call to the server, greatly diminishing the chatter between the client and the server.

Another approach to using the Neo4j-Server would be to write a custom server extension using the SpringPluginInitializer provided by spring-data-neo4j-rest. This extension would use the well known entities and approaches as it runs inside the server atop an embedded graph database. From the extension we would expose custom, domain and use-case oriented REST endpoints that could then be consumed by any kind of webapp, even a pure Javascript based browser app.

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 domains, 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 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 NOSQL 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 mind, 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 API of 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 both. 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();
	firstNode.setProperty( "message", "Hello, " );
	Node secondNode = graphDb.createNode();
	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 of complex, interconnected data 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 and queries 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 Neo4j provides automatic indexing via the @Indexed annotation, eliminating the need for manual index management.

	Note
	Modifying Neo4j indexes also requires transactions.

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
}

Neo4j provides a graph query language called "Cypher" which draws from many sources. It resembles SQL but with an iconic representation of patterns in the graph (concepts drawn from SPARQL). The Cypher execution engine was written in Scala to leverage the high expressiveness for lazy sequence operations of the language and the parser combinator library. A screencast explaining the possibilities in detail can be found on the Neo4j video site.

Cypher queries always begin with a start set of nodes. Those can be either expressed by their IDs or by an index lookup expression. Those start-nodes are then related to other nodes in the match clause. Start and match clauses can introduce new identifiers for nodes and relationships. In the where clause additional filtering of the result set is applied by evaluating expressions. The return clause defines which part of the query result will be available. Aggregation also happens in the return clause by using aggregation functions on some of the values. Sorting can happen in the order by clause and the skip and limit parts restrict the result set to a certain window.

Cypher can be executed on an embedded graph database using an ExecutionEngine and CypherParser. This is encapsulated in Spring Data Neo4j with CypherQueryEngine. The Neo4j-REST-Server comes with a Cypher-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding.

// Actors who played a Matrix movie:
start movie=node:Movie("title:Matrix*") match movie<-[:ACTS_IN]-actor
    return actor.name, actor.birthplace?

// User-Ratings:
start user=node:User(login='micha') match user-[r:RATED]->movie where r.stars > 3
    return movie.title, r.stars, r.comment

// Mutual Friend recommendations:
start user=node:Micha(login='micha') match user-[:FRIEND]-friend-[r:RATED]->movie where r.stars > 3
    return friend.name, movie.title, r.stars, r.comment?

// Movie suggestions based on a movie:
start movie=node:Movie(id='13') match (movie)<-[:ACTS_IN]-()-[:ACTS_IN]->(suggestion)
    return suggestion.title, count(*) order by count(*) desc limit 5

// Co-Actors, sorted by count and name of Lucy Liu
start lucy=node(1000) match lucy-[:ACTS_IN]->movie<-[:ACTS_IN]-co_actor
    return count(*), co_actor.name order by count(*) desc,co_actor.name limit 20

// Recommendations including counts, grouping and sorting
start user=node:User(login='micha') match user-[:FRIEND]-()-[r:RATED]->movie
    return movie.title, AVG(r.stars), count(*) order by AVG(r.stars) desc, count(*) desc

Gremlin is an expressive Groovy DSL developed by Marko Rodriguez as part of the Tinkerpop stack. It builds on top of a pipe implementation (Blueprints Pipes) that uses connected operations to traverse a graph. Gremlin has a concise syntax but is Turing complete.

Gremlin can be executed by including the Tinkerpop and Blueprints dependencies and then requesting a ScriptEngine of type "gremlin" from the javax.Script* facilities. In Spring Data Neo4j this is encapsulated in GremlinQueryEngine. The Neo4j-REST-Server also comes with a Gremlin-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding.

// Vertex with id 1
v = g.v(1)

// determine the name of the vertices that vertex 1 knows and that are older than 30 years of age
v.outE{it.label=='knows'}.inV{it.age > 30}.name

// calculate basic collaborative filtering for vertex 1
m = [:]
g.v(1).out('likes').in('likes').out('likes').groupCount(m)
m.sort{a,b -> a.value <=> b.value}

Up until recently Spring Data Neo4j supported only the more advanced and flexible AspectJ based mapping approach, see Section 20.2, “Advanced Mapping with AspectJ”. Feedback about issues with the AspectJ tooling and other implications persuaded us to add a simpler mapping (see Section 20.3, “Simple Object Graph Mapping”) to Spring Data Neo4j. Both versions work with the same annotations and provide similar API's, but differ in behaviour.

Reflection and Annotation-based metadata is collected about persistent entities in the Neo4jMappingContext which provides it to any part of the library. The information is stored in Neo4jPersistentEntity instances which hold all the Neo4jPersistentProperty's of the type. Each entity can be checked to determine whether it represents a Node or a Relationship. Properties declare detailed data about their indexing and relationship information as well as type information that also covers nested generic types. With all that information available it is simple to select the appropriate strategy for mapping each entity and field to elements, relationships and properties of the graph.

The main difference is in the way of accessing the graph. In the simple mapping the required information is copied into the entity on load and only stored back when an explicit save operation occurs. In the advanced mapping (AspectJ-enhanced) approach a node or relationship is attached via an additional field to the entity and all read- and write-operations (inside of Transactions) happen through that.

For the simple mapping mode, declaration of fetch strategies for related entities is necessary to avoid loading the whole graph eagerly into memory. The initial approach uses just a simple @Fetch annotations on relationship properties. The resulting MappingPolicy is provided to the infrastructure methods to ensure the correct loading behaviour. Both, Neo4jPersistentEntiy and Neo4jPersistentProperty can be queried for the MappingPolicy.

Otherwise the two approaches share much of the infrastructure. E.g. for creating new entity instances from type information store in the graph (Section 20.14, “Entity type representation”), the infrastructure for mapping individual fields to graph properties and relationships and everything related to indexing and querying. A certain part of that is also exposed via the Neo4jTemplate for direct use.

Behind the scenes, Spring Data Neo4j leverages AspectJ aspects to modify the behavior of annotated POJO entities (see Chapter 26, 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 Neo4j can retrieve the appropriate information from the entity's backing node or relationship.

The aspect introduces an internal field (entityState) and some public methods (see Section 20.11, “Active Record Methods for Advanced Mapping Mode”) to the entities, for instance entity.getPersistentState() and entity.relateTo. It also introduces some methods for graph operations that start at the current entity. Introduced methods for equals() and hashCode() use the underlying node or relationship. Please take the introduced field into account when serializing your entities and exclude it from the serialization process.

Spring Data Neo4j 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. 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 is some caching involved as well, so it handles repeated instantiation efficiently.

To use the advanced, AspectJ based mapping, please add spring-data-neo4j-aspects as a dependency and set up the AspectJ integration in Maven or other build tools as explained in Chapter 21, Environment setup. Some hints for your IDE setup are described below.

20.2.1 AspectJ IDE support

As Spring Data Neo4j uses some advanced features of AspectJ, users may experience issues with their IDE reporting errors where in fact there are none. Features that might be reported wrongfully include: introduction of methods to interfaces, declaration of additional interfaces for annotated classes, and generified introduced methods.

IDEs not providing full AspectJ support might mark parts of your code as having errors. You should rely on your build-system and tests to verify the correctness of the code. You might also have your Entities (or their interfaces) implement the NodeBacked and RelationshipBacked interfaces directly to benefit from completion support and error checking.

Eclipse and STS support AspectJ via the AJDT plugin which can be installed from the update-site listed at http://www.eclipse.org/ajdt/downloads/ (it might be necessary to use the latest development snapshot of the plugin). The current version that does not show incorrect errors is AspectJ 1.6.12 (included in STS 2.8.0), previous versions are reported to mislead the user. Note that AJDT (as of September 2012) requires projects to be rebuild after Eclipse is started to fully support all advanced features.

Note

There might be some issues with the eclipse maven plugin not adding AspectJ files correctly to the build path. If you encounter issues, please try the following: Try editing the build path to include **/*.aj for the spring-data-neo4j-aspects project. You can do this by selecting "Build Path -> Configure Build Path ..." from the Package Explorer. Then for the spring-data-neo4j-aspects/src/main/java add **/*.aj to the Included path. When importing a Spring Data Neo4j project into Eclipse with m2e, please make sure the AspectJ Configurator is installed from the following update-site: http://dist.springsource.org/release/AJDT/configurator

The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving the situation in their upcoming 11 release of their popular IDE. Their latest work is available under their early access program (EAP). Building the project with the AspectJ compiler ajc works in IDEA (Options -> Compiler -> Java Compiler should show ajc). Make sure to give the compiler at least 512 MB of RAM.

In addition to the advanced object graph mapping using AspectJ, Spring Data Neo4j also supports a simpler mode that converts graph data into domain objects and vice versa. It does not require any additional set up and should work out of the box. The simple mapping approach uses the same annotations (???) as the advanced mapping to declare mapping meta-information.

The simple object graph mapping comes into play whenever an entity is constructed from a node or relationship. This could be done explicitly like during the lookup- or create-operations of the repositories and the Neo4jTemplate but also implicitly while executing any graph operation that returns nodes or relationships and expecting mapped entities to be returned.

It uses the available meta-information about the persistent entity to iterate over its properties and relationships, fetching their data from the graph while doing so. It also executes computed fields and stores the resulting values in the properties.

We try to avoid loading the whole graph into memory by not following relationships eagerly. A dedicated @Fetch annotation controls instead if related entities are loaded or not. Whenever an entity is not fully loaded, then only its id is stored. Those entities or collections of entities can then later be loaded explicitly using the template.fetch() operation.

The additional fetch information is stored in a MappingPolicy which can be retrieved via the Neo4jTemplate for classes. Both Neo4jPersistentEntitity as well as Neo4jPersistentProperty provide access to that information on their scope.

	Note
	Please note that if you have two collections in an entity pointing to the same relationship and one of them has data and the other is empty due to the nature of persisting it, one will override the other in the graph so that you might end up with no data. If you want a relationship-collection to be ignored on save set it to null.

  @Autowired Neo4jOperations template;


  @NodeEntity class Person {
    String name;
    @Fetch Person boss;
    Person spouse;

    @RelatedTo(type = "FRIEND", direction = BOTH)
    @Fetch Set<Person> friends;
  }
  Person person = template.findOne(personId);
  assertNotNull(person.getBoss().getName());

  assertNotNull(person.getSpouse().getId());
  assertNull(person.getSpouse().getName());

  template.fetch(person.getSpouse());
  assertNotNull(person.getSpouse().getName());

  assertEquals(10,person.getFriends().size());
  assertNotNull(firstFriend.getName());

	Note
	Both the simple mapping approach as well as the fetch strategies (MappingPolicy) debuted in Spring Data Neo4j 2.0. So there might be rough edges and there are certainly many areas for improvement and extension. We look forward to your feedback on this topic.

As we tried to encapsulate each aspect of the mapping process into a separate class the resulting fabric of responsibilities is quite intricate. All of them are set up in the MappingInfrastructure that is part of the Neo4jTemplate setup.

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

@NodeEntity
public class Movie {
    String title;
}

20.4.2 @GraphId: Neo4j -id field

For the simple mapping this is a required field which must be of type Long. It is used by Spring Data Neo4j to store the node or relationship-id to re-connect the entity to the graph.

	Note
	It must not be a primitive type because then the "non-attached" case can not be represented as the default value 0 would point to the reference node. Please make also sure that an equals() and hashCode() method have to be provided which take the id field into account (and also handle the "non-attached", null case).

For the advanced mapping such a field is optional. Only if the underlying id has to be accessed, it is needed.

Entity Equality

Entity equality can be a grey area, and it is debatable whether natural keys or database ids best describe equality, there is the issue of versioning over time, etc. For Spring Data Neo4j we have adopted the convention that database-issued ids are the basis for equality, and that has some consequences:

1. Before you attach an entity to the database, i.e. before the entity has had its id-field populated, we suggest you rely on object identity for comparisons
2. Once an entity is attached, we suggest you rely solely on the id-field for equality
3. When you attach an entity, its hashcode changes - because you keep equals and hashcode consistent and rely on the database ID, and because Spring Data Neo4j populates the database ID on save

That causes problems if you had inserted the newly created entity into a hash-based collection before saving. While that can be worked around, we strongly advise you adopt a convention of not working with un-attached entities, to keep your code simple. This is best illustrated in code.

Example 20.3. Entity using id-field for equality and attaching new entity immediately

@NodeEntity
public class Studio {
    @GraphId
    Long id

    String name;

    public boolean equals(Object other) {
        if (this == other) return true;

        if (id == null) return false;

        if (! (other instanceof Studio)) return false;

        return id.equals(((Studio) other).id);
    }

    public int hashCode() {
        return id == null ? System.identityHashCode(this) : id.hashCode();
    }
}

...
Set<Studio> studios = new HashSet<Studio>();
Studio studio = studioRepository.save(new Studio("Ghibli"));
studios.add(studio);
Studio sameStudio = studioRepository.findOne(studio.id);
assertThat(studio, is(equalTo(sameStudio));
assertThat(studios.contains(sameStudio), is(true);
assertThat(studios.remove(sameStudio), is(true);

A work-around for the problem of un-attached entities having their hashcode change when they get saved is to cache the hashcode. The hashcode will change next time you load the entity, but at least if you have the entity sitting in a collection, you will still be able to find it:

Example 20.4. Caching hashcode

@NodeEntity
public class Studio {
    @GraphId
    Long id

    String name;

    transient private Integer hash;

    public boolean equals(Object other) {
        if (this == other) return true;

        if (id == null) return false;

        if (! (other instanceof Studio)) return false;

        return id.equals(((Studio) other).id);
    }

    public int hashCode() {
        if (hash == null) hash = id == null ? System.identityHashCode(this) : id.hashCode();

        return hash.hashCode();
    }
}

...
Set<Studio> studios = new HashSet<Studio>();
Studio studio = new Studio("Ghibli")
studios.add(studio);
studioRepository.save(studio);
assertThat(studios.contains(studio), is(true);
assertThat(studios.remove(studio), is(true);
Studio sameStudio = studioRepository.findOne(studio.id);
assertThat(studio, is(equalTo(sameStudio));
assertThat(studio.hashCode(), is(not(equalTo(sameStudio.hashCode())));

	Note
	Remember, transient fields are not saved.

20.4.5 @Query: fields as query result views

The @Query annotation leverages the delegation infrastructure supported by Spring Data Neo4j. It provides dynamic fields which, when accessed, return the values selected by the provided query language expression. The provided query must contain a placeholder named {self} for the the current entity. For instance the query start n=node({self}) match n-[:FRIEND]->friend return friend. Graph queries can return variable number of entities. That's why annotation can be put onto fields with a single value, a subclass of Iterable of a concrete type or an Iterable of Map<String,Object>. Additional parameters are taken from the params attribute of the @Query annotation. These parameter tuples form key-value pairs that are provided to the query at execution time.

Example 20.5. @Graph on a node entity field

@NodeEntity
public class Group {
    @Query(value = "start n=node({self}) match (n)-[r]->(friend) where r.type = {relType} return friend",
                params = {"relType", "FRIEND"})
    private Iterable<Person> friends;
}

	Note
	Please note that this annotation can also be used on repository methods. (Section 20.8, “CRUD with repositories”)

@NodeEntity
public class Group {
    @GraphTraversal(traversal = 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 Neo4j has special support to represent Neo4j relationships as entities too, but it is often not needed.

	Note
	As of Neo4j 1.4.M03, circular references are allowed. Spring Data Neo4j reflects this accordingly.

20.5.1 @RelatedTo: Connecting node entities

Every field of a node entity that references one or more other node entities is backed by relationships in the graph. These relationships are managed by Spring Data Neo4j automatically.

The simplest kind of relationship is a single field pointing to another node entity (1:1). In this case, the field does not have to be annotated at all, although the annotation may be used to control the direction and type of the relationship. When setting the field, a relationship is created when the entity is persisted. If the field is set to null, the relationship is removed.

Example 20.7. Single relationship field

@NodeEntity
public class Movie {
    private Actor topActor;
}

It is also possible to have fields that reference a set of node entities (1:N). These fields come in two forms, modifiable or read-only. Modifiable fields are of the type Set<T>, and read-only fields are Iterable<T>, where T is a @NodeEntity-annotated class.

Example 20.8. Node entity with relationships

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

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

For the simple mapping, the automatic transitive loading of related entities depends on declaration of @Fetch at the property. Otherwise the related node or relationship entities will just be initialized with their id for later loading.

When using the advanced mapping, Fields referencing other entities should not be manually initialized, as they are managed by Spring Data Neo4j Aspects under the hood. 1:N fields can be accessed immediately, and Spring Data Neo4j will provide a Set representing the relationships.

If this Set of related entities is modified, the changes are reflected in the graph, relationships are added, removed or updated accordingly.

	Note
	Spring Data Neo4j ensures by default that there is only one relationship of a given type between any two given entities. This can be circumvented by using the createRelationshipBetween() method with the allowDuplicates parameter on repositories or entities.

	Note
	Before an entity has been persisted for the first time, it will not have its state managed by Spring Data Neo4j. For example, given the Actor class defined above, if actor.movies was accessed in a non-persisted entity, it would return null, whereas if it was accessed in a persisted entity, it would return an empty managed set.

When an Interface is used as target type for the Set and/or as elementClass it should be marked as @NodeEntity too.

By setting direction to BOTH, relationships are created in the outgoing direction, but when the 1:N field is read, it will include relationships in both directions. A cardinality of M:N is not necessary because relationships can be navigated in both directions.

In the advanced mapping mode, the relationships can also be accessed by using the methods entity.getRelationshipBetween(target, type) and entity.relateTo(target, type) available on each NodeEntity. These methods find and create Neo4j relationships. It is also possible to manually remove relationships by using entity.removeRelationshipTo(target, type). Using these methods is significantly faster than adding/removing from the collection of relationships as it doesn't have to re-synchronize a whole set of relationships with the graph.

Methods of the same semantics exist in the repositories to be used in the simple mapping mode.

	Note
	Other collection types than Set are not supported so far, also currently NO Map<RelationshipType,Set<NodeBacked>>.

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

@RelationshipEntity
public class Role {
    String title;

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

@NodeEntity
public class Actor {
    @RelatedToVia
    @Set<Role> roles=new HashSet<Role>();
    public Role playedIn(Movie movie, String title) {
        Role role=new Role(this,movie,title);
        roles.add(role);
        return role;
    }
    @RelatedToVia(type="FRIEND_OF", direction=Direction.INCOMING)
    Friendship bestFriend;
}

@RelationshipEntity(type = "ACTS_IN")
public class Role {
    String title;

    @StartNode private Actor actor;
    @EndNode private Movie movie;
}
@RelationshipEntity
public class Friendship {
    Date since;

    @StartNode private Actor actor;
    @EndNode private Person buddy;
}
        

20.5.4 Relationship Type Precedence

In the example above we show how to specify a default relationship type, and how to provide the relationship type using an annotation property. Here is an example of using the @RelationshipType annotation on a member variable on the relationship entity; we call this dynamic relationship type.

Example 20.11. Dynamic Relationship Type (simple mapping)

@RelationshipEntity(type = "colleague")
public class Acquaintance {
      @StartNode private Actor actor;
      @EndNode private Person acquaintance;
      @RelationshipType private String connection;

      public Acquaintance(Actor actor, Person acquaintance, String connection) {
          ...

Actor frankSinatra = ...
Person carloGambino = ...
new Acquaintance(frankSinatra, carloGambino, "its_complicated")

      

	Note
	Because dynamic type information is, well, dynamic, it is generally not possible to read the mapping backwards using SDN. The relationship still exists, but SDN cannot help you access it because it does not know what type you gave it. Also, for this reason, we require you to specify a default relationship type, so that we can at least attempt the reverse mapping.

Should you happen to provide conflicting relationship types, we have established the following precedence, in priority order:

1. Dynamic
2. Annotation-provided
3. Default

                
                @NodeEntity
                class Person {
                    @RelatedTo(type="OWNS")
                    Car car;

                    @RelatedTo(type="OWNS")
                    Pet pet;
                ...
            

                
                @NodeEntity
                class Person {
                    @RelatedTo(type="OWNS", enforceTargetType=true)
                    Car car;

                    @RelatedTo(type="OWNS", enforceTargetType=true)
                    Pet pet;
                ...
            

Indexing is used in Neo4j to quickly find nodes and relationships to start graph operations from. Either for manually traversing the graph, using the traversal framework, cypher or gremlin queries or for "global" graph operations. Indexes are also employed to ensure uniqueness of elements with certain properties.

The Neo4j graph database employs different 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. There is also a spatial index provider for geo-searches.

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

GraphRepository<Person> graphRepository = template.repositoryFor(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);
}

20.6.2 Fulltext indexes

Spring Data Neo4j also supports fulltext indexes. By default, indexed fields are stored in an exact lookup index. To have them analyzed and prepared for fulltext search, the @Indexed annotation has the type attribute which can be set to IndexType.FULLTEXT. Please note that fulltext indexes require a separate index name as the fulltext configuration is stored in the index itself.

Access to the fulltext index is provided by the findAllByQuery() repository method. Wildcards like * are allowed. Generally though, the fulltext querying rules of the underlying index provider apply. See the Lucene documentation for more information on this.

Example 20.15. Fulltext indexing

@NodeEntity
class Person {
    @Indexed(indexName = "people-search", type=FULLTEXT) String name;
}

GraphRepository<Person> graphRepository =
             template.repositoryFor(Person.class);

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

	Note
	Please note that indexes are currently created on demand, so whenever an index that doesn't exist is requested from a query or get operation it is created. This is subject to change but has currently the implication that those indexes won't be configured as fulltext which causes subsequent fulltext updates to those indexes to fail.

20.6.3 Unique indexes

Unique indexing with index.putIfAbsent and UniqueFactory was introduced in Neo4j 1.6. It is also available via the REST API. In Spring Data Neo4j this is made available via Neo4jTemplate.getOrCreateNode and Neo4jTemplate.getOrCreateRelationship.

In an entity at most one field can be annotated with @Indexed(unique=true) regardless of the index-type used. The uniqueness will be taken into account when creating the entity by reusing an existing entity if that unique key-combination already exists. On saving of the field it will be cross-checked against the index and fail with a DataIntegrityViolationException if the field was changed to an already existing unique value. Null values are no longer allowed for these properties.

	Note
	This works for both Node-Entities as well as Relationship-Entities. Relationship-Uniqueness in Neo4j is global so that an existing unique instance of this relationship may connect two completely different nodes and might also have a different type.

Example 20.16. Unique indexing

// creates or finds a node with the unique index-key-value combination
// and initializes it with the properties given
template.getOrCreateNode("users", "login", "mh", map("name","Michael","age",37));

@NodeEntity class Person {
    @Indexed(unique = true) String name;
}

Person mark1 = repository.save(new Person("mark"));
Person mark2 = repository.save(new Person("mark"));

// just one node is created
assertEquals(mark1,mark2);
assertEquals(1, personRepository.count());

Person thomas = repository.save(new Person("thomas"));
thomas.setName("mark");
repository.save(thomas); // fails with a DataIntegrityViolationException

@Autowired Neo4jTemplate template;

// Default index
Index<Node> personIndex = template.getIndex(null, 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 = template.getIndex("people",Person.class);
namedPersonIndex.get("name", "Mark");

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

@Autowired Neo4jTemplate template;

Index<Node> personIndex = template.getIndex(Person.class, "age");
personIndex.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 = template.getIndex(Person.class,"name");
personFulltextIndex.query("name", "*cha*");
personFulltextIndex.query("{name:*cha*}");

The Neo4jTemplate offers the convenient API of Spring templates for the Neo4j graph database. The Spring Data Neo4j Object Graph mapping builds upon the core functionality of the template to persist objects to the graph and load them in a variety of ways. The template handles the active mapping mode (Section 20.1, “Object Graph Mapping”) transparently.

Besides methods for creating, storing and deleting entities, nodes and relationships in the graph, Neo4jTemplate also offers a wide range of query methods. To reduce the proliferation of query methods a simple result handling DSL was added.

Neo4jOperations neo = new Neo4jTemplate(graphDatabase);
    
    Node mark = neo.createNode(map("name", "Mark"));
    Node thomas = neo.createNode(map("name", "Thomas"));
    
    neo.createRelationshipBetween(mark, thomas, "WORKS_WITH", 
                                map("project", "spring-data"));
    
    neo.index("devs", thomas, "name", "Thomas");
    
    assertEquals( "Mark", 
        neo.query("start p=node({person}) match p<-[:WORKS_WITH]-other return other.name",
                  map("person", asList(thomas.getId()))).to(String.class).single());
    
    
    
    // Gremlin
    assertEquals(thomas, neo.execute("g.v(person).out('WORKS_WITH')",
            map("person", mark.getId())).to(Node.class).single());
    
    // Index lookup
    assertEquals(thomas, neo.lookup("devs", "name", "Thomas").to(Node.class).single());
    
    // Index lookup with Result Converter
    assertEquals("Thomas", neo.lookup("devs", "name", "Thomas")
      .to(String.class, new ResultConverter<PropertyContainer, String>() {
        public String convert(PropertyContainer element, Class<String> type) {
            return (String) element.getProperty("name");
        }
      }).single());
    

                @Configuration
    @EnableNeo4jRepositories
    public class ApplicationConfig extends Neo4jConfiguration {
        ...
        @Bean
        ApplicationListener<BeforeSaveEvent> beforeSaveEventApplicationListener() {
            return new ApplicationListener<BeforeSaveEvent>() {
                @Override
                public void onApplicationEvent(BeforeSaveEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    entity.setUniqueId(acmeIdFactory.create());
                }
            };
        }

        @Bean
        ApplicationListener<AfterSaveEvent> afterSaveEventApplicationListener() {
            return new ApplicationListener<AfterSaveEvent>() {
                @Override
                public void onApplicationEvent(AfterSaveEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    auditLog.onEventSaved(entity);
                }
            };
        }

        @Bean
        ApplicationListener<DeleteEvent> deleteEventApplicationListener() {
            return new ApplicationListener<DeleteEvent>() {
                @Override
                public void onApplicationEvent(DeleteEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    auditLog.onEventDeleted(entity);
                }
            };
        }
        ...
            

The repositories provided by Spring Data Neo4j 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 Neo4j repositories support annotated and named queries for the Neo4j Cypher query-language and Gremlin graph DSL.

Spring Data Neo4j comes with typed repository implementations that provide methods for locating node and relationship entities. There are several 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.

With the RelationshipOperationsRepository it is possible to access, create and delete relationships between entitites or nodes. The SpatialRepository allows geographic searches (Section 20.10, “Geospatial Queries”)

GraphRepository is a convenience repository interface, combining CRUDRepository, IndexRepository, and TraversalRepository. Generally, it has all the desired repository methods. If other operations are required then the additional repository interfaces should be added to the individual interface declaration.

public interface MovieRepository extends GraphRepository<Movie> {
    
    // returns the node with id equal to idOfMovie parameter  
    @Query("start n=node({0}) return n")
    Movie getMovieFromId(Integer idOfMovie);

    // returns the nodes which will use index named title equal to movieTitle parameter
    // movieTitle String must not contain any spaces, otherwise you will receive a NullPointerException.
    @Query("start movie=node:Movie(title={0}) return movie")
    Movie getMovieFromTitle(String movieTitle);

    // returns the Actors that have a ACTS_IN relationship to the movie node with the title equal to movieTitle parameter. 
    // (The parenthesis around 'movie' and 'actor' in the match clause are optional.)                       
    @Query("start movie=node:Movie(title={0}) match (movie)&lt;-[:ACTS_IN]-(actor) return actor")
    Page<Actor> getActorsThatActInMovieFromTitle(String movieTitle, PageRequest);

    // returns users who rated a movie (movie parameter) higher than rating (rating parameter)
    @Query("start movie=node:({0}) " +
           "match (movie)&lt;-[r:RATED]-(user) " +
           "where r.stars > {1} " +
           "return user")
    Iterable<User> getUsersWhoRatedMovieFromTitle(Movie movie, Integer rating);

    // returns users who rated a movie based on movie title (movieTitle parameter) higher than rating (rating parameter)
    @Query("start movie=node:Movie(title={0}) " +
           "match (movie)&lt;-[r:RATED]-(user) " +
           "where r.stars > {1} " +
           "return user")
     Iterable<User> getUsersWhoRatedMovieFromTitle(String movieTitle, Integer rating);
 }
                

public interface PersonRepository 
               extends GraphRepository<Person> {

// start person=node:Person(id={0}) return person
Person findById(String id)

// start person=node:Person({0}) return person - {0} will be "id:"+name
Iterable<Person> findByNameLike(String name)

// start person=node:__types__("className"="com...Person") 
// where person.age = {0} and person.married = {1}
// return person
Iterable<Person> findByAgeAndMarried(int age, boolean married)

// start person=node:__types__("className"="com...Person")
// match person<-[:CHILD]-parent
// where parent.age > {0} and person.married = {1}
// return person
Iterable<Person> findByParentAgeAndMarried(int age, boolean married)
}

    @NodeEntity
    public static class Person {
        @GraphId Long id;
        private String name;
        private Group group;

        private Person(){}
        public Person(String name) {
            this.name = name;
        }
    }

    @NodeEntity
    public static class Group {
        @GraphId Long id;
        private String title;
        // incoming relationship for the person -> group
        @RelatedTo(type = "group", direction = Direction.INCOMING)
        private Set<Person> members=new HashSet<Person>();

        private Group(){}
        public Group(String title, Person...people) {
            this.title = title;
            members.addAll(asList(people));
        }
    }
    public interface PersonRepository extends GraphRepository<Person> {
        Iterable<Person> findByGroupTitle(String name);
    }

    @Autowired PersonRepository personRepository;

    Person oliver=personRepository.save(new Person("Oliver"));
    final Group springData = new Group("spring-data",oliver);
    groupRepository.save(springData);

    final Iterable<Person> members = personRepository.findByGroupTitle("spring-data");
    assertThat(members.iterator().next().name, is(oliver.name));

import static org.neo4j.cypherdsl.CypherQuery.*;
import static org.neo4j.cypherdsl.querydsl.CypherQueryDSL.*;

	public interface PersonRepository extends GraphRepository<Person>,
	  CypherDslRepository<Person> {}

	@Autowired PersonRepository repo;
	// START company=node:Company(name={name}) MATCH company<-[:WORKS_AT]->person RETURN person

	Execute query = start( lookup( "company", "Company", "name", param("name") ) ).
	                          match( path().from( "company" ).in( "WORKS_AT" ).to( "person" )).
	                          returns( identifier( "person" ))
	Page<Person> people = repo.query(query , map("name","Neo4j"), new PageRequest(1,10));

	QPerson person = QPerson.person;
	QCompany company = QCompany.company;
	Execute query = start( lookup( company, "Company", company.name, param("name") ) ).
	                          match( path().from( company ).in( "WORKS_AT" ).to( person ).
	                          .where(person.firstName.like("P*").and(person.age.gt(25))).
	                          returns( identifier(person) )
	EndResult<Person> people = repo.query(query , map("name","Neo4j"));

	

<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-core</artifactId>
    <version>2.2.3</version>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-lucene</artifactId>
    <version>2.2.3</version>
    <optional>true</optional>
    <exclusions>
        <exclusion>
            <groupId>org.apache.lucene</groupId>
            <artifactId>lucene-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>2.2.3</version>
    <scope>provided</scope>
</dependency>

            <plugin>
                <groupId>com.mysema.maven</groupId>
                <artifactId>maven-apt-plugin</artifactId>
                <version>1.0.2</version>
                <configuration>
                    <processor>org.springframework.data.neo4j.querydsl.SDNAnnotationProcessor</processor>
                </configuration>
                <executions>
                    <execution>
                        <id>test-sources</id>
                        <phase>generate-test-sources</phase>
                        <goals>
                            <goal>test-process</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>target/generated-sources/test</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

public interface PersonRepository extends GraphRepository<Person> {}

@Autowired PersonRepository repo;
// OR
GraphRepository<Person> repo = template
                           .repositoryFor(Person.class);

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

Person dave = repo.findOne(123);

Long numberOfPeople = repo.count();

EndResult<Person> devs = graphRepository.findAllByPropertyValue("occupation", "developer");

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

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

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

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

20.8.8 Composing repositories

The recommended way of providing repositories is to define a repository interface per domain class. The mechanisms provided by the repository infrastructure will automatically detect them, along with additional implementation classes, and create an injectable repository implementation to be used in services or other spring beans.

Example 20.26. Composing repositories

public interface PersonRepository extends GraphRepository<Person>, PersonRepositoryExtension {}

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

// have it injected
@Autowired
PersonRepository personRepository;
// or created via the template
PersonRepository personRepository = template.repositoryFor(Person.class);


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

Person dave=personRepository.findOne(123);

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

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

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


// 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
// (template reference is optional)
<neo4j:repositories base-package="org.springframework.data.neo4j"
    graph-database-context-ref="template"/>

// have it injected
@Autowired
PersonRepository personRepository;

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

Person dave=personRepository.findOne(123);

EndResult<Person> devs = personRepository.findAllByPropertyValue("occupation","developer");

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

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

	Note
	If you use <context:component-scan> in your spring config, please make sure to put it behind <neo4j:repositories>, as the RepositoryFactoryBean adds new bean definitions for all the declared repositories, the context scan doesn't pick them up otherwise.

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

Spring Data Neo4j 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 changes are reflected on the same data.

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
    Set<Training> trainings;
}

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

SpatialRepository is a dedicated Repository for spatial queries. Spring Data Neo4j provides an optional dependency to neo4j-spatial which is an advanced library for GIS operations. So if you include the maven dependency in your pom.xml, Neo4j-Spatial and the required SPATIAL index provider is available.

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-spatial</artifactId>
    <version>0.7-SNAPSHOT</version>
</dependency>

To have your entities available for spatial index queries, please include a String property containing a "well known text", location string. WKT is the Well Known Text Spatial Format eg. POINT( LON LAT ) or POLYGON (( LON1 LAT1 LON2 LAT2 LON3 LAT3 LON1 LAT1 ))

@NodeEntity
class Venue {
   String name;
   @Indexed(type = POINT, indexName = "VenueLocation") String wkt;
   public void setLocation(float lon, float lat) {
      this.wkt = String.format("POINT( %.2f %.2f )",lon,lat);
   }
}

venue.setLocation(56,15);

After adding the SpatialRepository to your repository you can use the findWithinBoundingBox, findWithinDistance, findWithinWellKnownText.

    Iterable<Person> teamMembers = personRepository.findWithinBoundingBox("personLayer", 55, 15, 57, 17);
Iterable<Person> teamMembers = personRepository.findWithinWellKnownText("personLayer", "POLYGON ((15 55, 15 57, 17 57, 17 55, 15 55))");
Iterable<Person> teamMembers = personRepository.findWithinDistance("personLayer", 16,56,70);

public interface SpatialRepository<T> {
    ClosableIterable<T> findWithinBoundingBox(String indexName, double lowerLeftLat,
                                              double lowerLeftLon,
                                              double upperRightLat,
                                              double upperRightLon);

    ClosableIterable<T> findWithinDistance( final String indexName, final double lat, double lon, double distanceKm);

    ClosableIterable<T> findWithinWellKnownText( final String indexName, String wellKnownText);
}

This chapter only applies to the advanced mapping. Currently the Aspects introduce the following methods by default, this will change in the future, there will be separate Mixin-Interfaces that can selectively be mixed into the domain entities if needed. Otherwise the AspectJ interaction will be restricted to field access interception and post-constructor handling.

The node and relationship aspects introduce (via AspectJ ITD - inter-type declaration) several methods to the entities.

Neo4j is a transactional database, only allowing modifications to be performed within transaction boundaries. Reading data does however not require transactions. Spring Data Neo4j integrates nicely with both the declarative transaction support with @Transactional as well as the manual transaction handling with TransactionTemplate. It also supports the rollback mechanisms of the Spring Testing library.

Spring Data Neo4j 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.

	Note
	To avoid name collisons the transaction manager configured by Spring Data Neo4j is called neo4jTransactionManager and is aliased to transactionManager. So defining a separate transactionManager bean should not interfere with Spring Data Neo4j operations.

	Note
	The explicit XML configuration given below is encoded in the Neo4jConfiguration configuration bean that uses Spring's @Configuration feature. This greatly simplifies the configuration of Spring Data Neo4j.

<bean id="neo4jTransactionManager"
        class="org.springframework.data.neo4j.config.JtaTransactionManagerFactoryBean">
    <constructor-arg ref="graphDatabaseService"/>
</bean>

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

For scenarios with multiple transactional resources there are two options. The first option is to have Neo4j participate in the externally configured transaction manager 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.neo4j.transaction.JotmFactoryBean"/>
    </property>
</bean>

<bean id="graphDatabaseService" 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 Neo4j. 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.data.neo4j.config.JtaTransactionManagerFactoryBean">
    <constructor-arg ref="graphDatabaseService"/>
</bean>
<bean id="transactionManager"
        class="org.springframework.data.neo4j.transaction.ChainedTransactionManager">
    <constructor-arg>
        <list>
            <ref bean="jpaTransactionManager"/>
            <ref bean="jtaTransactionManager"/>
        </list>
    </constructor-arg>
</bean>

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

This section only applies to the advanced mapping (AspectJ-backed). The simple mapping always detaches entities on load as it copies the data out of the graph into the entities and stores it back fully too.

Node entities can be in two different persistence states: attached or detached. By default, newly created node entities are in the detached state. When persist() or template.save() is called on the entity, it becomes attached to the graph, and its properties and relationships are stores in the database. If the save operation is not called within a transaction, it automatically creates an implicit transaction only 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 (its fields) itself until the next call to a save operation.

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 hierarchy is saved in the graph database.

As the type information is also stored in node/relationship-properties and/or indexes it might amount to a substantial amount of data in the graph. It is possible to use an @TypeAlias("name") annotation on nodes and relationships to have a short constant name for each type which is (unlike the default approach) renaming-refactoring-safe. For using the simple class name by default, register a Neo4jMappingContext bean configured with an instance of EntityAlias. It is also possible to opt out of storing type information using the NoopTypeRepresentationStrategies.

Implementations of TypeRepresentationStrategy take care of persisting this information during entity instance creation. They also provide the repository methods that use this type information to perform their operations, like findAll and count. The derived finderMethods also use the type information for graph global queries.

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

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

Spring Data Neo4j 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.

Spring Data Neo4j supports property-based validation support. When a property is changed and persisted, 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 Neo4jTemplate, which is done automatically by the Neo4jConfiguration if one is present in the Spring Config.

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

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

The validation supports needs the bean validation API and a reference implementation configured. Right now this is the Hibernate Validator by default (which is not integrated with Hibernate ORM). The maven dependency is:

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>4.2.0.Final</version>
</dependency>

// the application-context should contain a LocalValidatorFactoryBean

<bean id="validator"
  class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>

For the simple POJO mapping it is enough to add the org.springframework.data:spring-data-neo4j:2.1.0.RELEASE dependency to your project.

<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-neo4j</artifactId>
<version>2.1.0.RELEASE</version>
</dependency>

The necessary build plugin to build Spring Data Neo4j projects with Gradle is available as part of the Spring Data Neo4j distribution or on Github which makes the usage as easy as:

sourceCompatibility = 1.6
targetCompatibility = 1.6

springVersion = "3.1.0.RELEASE"
springDataNeo4jVersion = "2.1.0.RELEASE"
aspectjVersion = "1.6.12"

apply from:'https://github.com/SpringSource/spring-data-neo4j/raw/master/build/
gradle/springdataneo4j.gradle'

configurations {
    runtime
    testCompile
}
repositories {
    mavenCentral()
	mavenLocal()
	mavenRepo urls: "http://maven.springframework.org/release"
}

The actual springdataneo4j.gradle is very simple, just decorating the javac tasks with the iajc ant task.

The supplied sample ant build configuration is mainly about resolving the dependencies for Spring Data Neo4j Aspects and AspectJ using Ivy and integrating the iajc ant task in the build.

	<taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties" classpath="${lib.dir}/aspectjtools.jar"/>

<target name="compile" description="Compile production classes" depends="lib.retrieve">
	<mkdir dir="${main.target}" />

	<iajc sourceroots="${main.src}" destDir="${main.target}" classpathref="path.libs" source="1.6">
		<aspectpath>
			<pathelement location="${lib.dir}/spring-aspects.jar"/>
		</aspectpath>
		<aspectpath>
			<pathelement location="${lib.dir}/spring-data-neo4j-aspects.jar"/>
		</aspectpath>
	</iajc>
</target>

Spring Data Neo4j projects are easiest to build with Apache Maven. The core dependency is Spring Data Neo4j Aspects which comes with transitive dependencies to Spring Data Neo4j, Spring Data Commons, parts of the Spring Framework, AspectJ 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-aspects</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

<dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjrt</artifactId>
    <version>1.6.12</version>
</dependency>

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>aspectj-maven-plugin</artifactId>
    <version>1.2</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.12</version>
        </dependency>
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjtools</artifactId>
            <version>1.6.12</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-data-neo4j-aspects</artifactId>
            </aspectLibrary>
        </aspectLibraries>
        <source>1.6</source>
        <target>1.6</target>
    </configuration>
</plugin>

Users of Spring Data Neo4j have two ways of very concisely configuring it. Either they can use a Spring Data Neo4j 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:neo4j="http://www.springframework.org/schema/data/neo4j"
        xsi:schemaLocation="
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd
            http://www.springframework.org/schema/context
            http://www.springframework.org/schema/context/spring-context.xsd
            http://www.springframework.org/schema/data/neo4j
            http://www.springframework.org/schema/data/neo4j/spring-neo4j.xsd">

    <context:annotation-config/>
    <neo4j: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"/>
<!-- optionally pass in neo4j-config parameters to the graph database
    <constructor-arg index="1">
        <map>
            <entry key="allow_store_upgrade" value="true"/>
        </map>
    </constructor-arg>
-->
</bean>

<neo4j:config graphDatabaseService="graphDatabaseService"/>

<context:annotation-config/>

<bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase"
    destroy-method="shutdown">
	<constructor-arg index="0" value="foo/db" />
	<constructor-arg index="1">
		<map><entry key="enable_remote_shell" value="true"/></map>
    </constructor-arg>
</bean>

<bean id="serverWrapper" class="org.neo4j.server.WrappingNeoServerBootstrapper" 
	init-method="start" destroy-method="stop">
	<constructor-arg ref="graphDatabaseService"/>
</bean>

// also add the static server-assets dependency to your pom.xml
<dependency>
    <groupId>org.neo4j.app</groupId>
    <artifactId>neo4j-server</artifactId>
    <classifier>static-web</classifier>
    <version>${neo4j-version}</version>
</dependency>

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

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

<neo4j:repositories base-package="org.example.repository"/>		

<!-- with template bean reference -->
<neo4j:repositories base-package="org.example.repository" graph-database-context-ref="template"/>		
		

21.5.3 Java-based bean configuration

You can also configure Spring Data Neo4j using Java-based bean metadata.

	Note
	For those not familiar with Java-based bean configuration in Spring, we recommend that you read up on it first. The Spring documentation has a high-level introduction as well as detailed documentation on it.

In order to configure Spring Data Neo4j with Java-based bean config, the class Neo4jConfiguration is registered with the context. This is either done explicitly in the context configuration, or via classpath scanning for classes that have the @Configuration annotation. The only thing that must be provided is the GraphDatabaseService. The example below shows how to register the @Configuration Neo4jConfiguration class, as well as Spring's ConfigurationClassPostProcessor that transforms the @Configuration class to bean definitions.

Example 21.12. Java-based bean configuration

<![CDATA[<beans ...>
    ...
    <tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
    <bean class="org.springframework.data.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>

Additional beans can be configured to be included in the Neo4j-Configuration just by defining them in the Spring context. ConversionService for custom conversions, Validators for bean validation, TypeRepresentationStrategyFactory for configuring the in graph type representation, IndexProviders for custom index handling (e.g. for multi-tenancy) or Entity-Instantiators (with their config) to have more control over the creation of entity instances and much more.

Partial graph persistence is achieved by restricting the Spring Data Neo4j 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 the persist operation.

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 Neo4j aspects, a single POJO can contain some fields handled by JPA and others handles by Spring Data Neo4j. 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.

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

    @GraphProperty
    String nickname;

    @RelatedTo
    Set<UserAccount> friends;

    @RelatedToVia(type = "recommends")
    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;

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

    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 Neo4j configuration. All you need to do is to specify an entityManagerFactory in the XML namespace config element, and Spring Data Neo4j 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/neo4j"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context
        http://www.springframework.org/schema/context/spring-context.xsd
        http://www.springframework.org/schema/data/neo4j
        http://www.springframework.org/schema/data/neo4j/spring-neo4j.xsd
        ">

    <context:annotation-config/>

    <neo4j: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 Neo4j 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 Neo4j as well. The sample comes with a minimal configuration for Maven and Spring to get up and running quickly.

The Hello Worlds application is available both for the simple mapping (hello-worlds) and for the advanced mapping (hello-world-aspects).

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 Neo4j in a more complex setting, using several annotated entities and relationships as well as indexes and in-graph 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 23.5, “MyRestaurant-Social sample application”), and does therefore not use Spring Data Neo4j.

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 cineasts.net application was introduced extensively in the first part of this guide, the tutorial. The tutorial covers the development of the simple mapping version of cineasts.

To document the differences, versions for the advanced mapping (cineasts-aspects) and accessing the remote server (cineasts-rest) are also available.

A online version of cineasts can be found on cineasts.net. A sample dataset of the cineasts databse is available at the neo4j sample-data page.

This is a subset of the visualization of the cineasts graph for the "Matrix" movie.

Usually, a Spring MVC application is bundled into a war and deployed to an application server like Tomcat. But Heroku can host any kind of java application. It just needs to know what to launch. So, we'll transform the war into a self-hosted servlet using an embedded Jetty server, then add a startup script to launch it.

First, we'll add the dependencies for Jetty to the pom.xml:

<dependency>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-webapp</artifactId>
    <version>7.4.4.v20110707</version>
</dependency>
<dependency>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>jsp-2.1-glassfish</artifactId>
    <version>2.1.v20100127</version>
</dependency>
      

Then we'll change the scope of the servlet-api artifact from provided to compile. This library is normally provided at runtime by the application container. Since we're self-hosting, it needs to be included directly. Make sure the servlet-api dependency looks like this:

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>servlet-api</artifactId>
    <version>2.5</version>
    <scope>compile</scope>
</dependency>
      

We could provide a complicated command-line to Heroku to launch the app. Instead, we'll simplify the command-line by using the appassembler-maven-plugin to create a launch script. Add the plugin to your pom's build/plugins section:

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>appassembler-maven-plugin</artifactId>
<version>1.1.1</version>
<executions>
  <execution>
    <phase>package</phase>
    <goals><goal>assemble</goal></goals>
    <configuration>
      <assembleDirectory>target</assembleDirectory>
      <extraJvmArguments>-Xmx512m</extraJvmArguments>
      <programs>
        <program>
          <mainClass>Main</mainClass>
          <name>webapp</name>
        </program>
      </programs>
    </configuration>
  </execution>
</executions>
</plugin>
      

Finally, switch the packaging from war to jar. That's it for the pom.

Now that the application is ready to be self-hosted, create a simple Main to bootstrap Jetty and host the servlet.

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;
public class Main {
    public static void main(String[] args) throws Exception {
        String webappDirLocation = "src/main/webapp/";
        String webPort = System.getenv("PORT");
        if(webPort == null || webPort.isEmpty()) {
            webPort = "8080";
        }
        Server server = new Server(Integer.valueOf(webPort));
        WebAppContext root = new WebAppContext();
        root.setContextPath("/");
        root.setDescriptor(webappDirLocation+"/WEB-INF/web.xml");
        root.setResourceBase(webappDirLocation);
        root.setParentLoaderPriority(true);
        server.setHandler(root);
        server.start();
        server.join();
    }
}
      

Notice the use of environment variable "PORT" for discovering which port to use. Heroku and the Neo4j Add-on use a number of environment variable to configure the application. Next, we'll modify the Spring application context to use the Neo4j variables for specifying the connection to Neo4j itself.

In the SDN Todos example, src/main/resources/META-INF/spring/applicationContext-graph.xml was modified to look like this:

<neo4j:config graphDatabaseService="graphDatabaseService"/>
<bean id="graphDatabaseService"
    class="org.springframework.data.neo4j.rest.SpringRestGraphDatabase">
    <constructor-arg index="0" value="${NEO4J_REST_URL}" />
    <constructor-arg index="1" value="${NEO4J_LOGIN}" />
    <constructor-arg index="2" value="${NEO4J_PASSWORD}" />
</bean>

Before provisioning at Heroku, test the application locally. First make sure you've got Neo4j server running locally, using default configuration. Then set the following environment variables:

export NEO4J_REST_URL=http://localhost:7474/db/data
export NEO4J_LOGIN=""
export NEO4J_PASSWORD=""

Now you can launch the app by running sh target/bin/webapp. If running the SDN Todos example, you can test it by running ./bin/todos list. That should return an empty JSON array, since no todos have been created yet.

For details about the todos script, see the readme included with the example.

With a self-hosted application ready, deploying to Heroku needs a few more steps. First, create a Procfile at the top-level of the project, which will contain a single line identifying the command line which launches the application.

The contents of the Procfile should contain:

web: sh target/bin/webapp

# Initialize a local git repository, adding all the project files
  git init
  git add .
  git commit -m "initial commit"

# Provision a Heroku stack, add the Neo4j Add-on and deploy the appication

  heroku create --stack cedar
  heroku addons:add neo4j
  git push heroku master

	Note
	Note that the stack must be "cedar" to support running Java. Check that the process is running by using heroku ps, which should show a "web.1" process in the "up" state. Success!

For the SDN Todos application, you can try out the remote application using the -r switch with the bin/todo script like this:

./bin/todo -r mk "tweet thanks for the good work @mesirii @akollegger"
./bin/todo -r list

To see the Neo4j graph you just created through Heroku, use heroku config to reveal the NEO4J_URL environment variable, which will take you to Neo4j's Webadmin.

The focus of Spring Data Neo4j 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.

Like with 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 are the ease of use of real domain objects in your business logic and also the integration with existing frameworks and libraries that expect Java POJOs as input or create them as results.

Spring Data Neo4j, however, was not designed with a major focus on performance. It does add some overhead to pure graph operations.

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 infrastructure from Spring-Data-Commons, so that only the first access gets a performance penalty. Other reflection penalties like field or method access will occur all the time.

For the simple mapping it is important to be aware of the size graph of data that is pulled out of the graph database in a single read and copied to domain entities. That's why Spring Data Neo4j loads related data not by default. You have to provide an indicator (@Fetch) to do so. Alternatively the Neo4jTemplate.fetch method offers means of of loading entities and collections of those.

For the advanced mapping mode keep in mind 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).

To evaluate if the performance of Spring Data Neo4j impacts a certain use-case it is sensible to define performance requirements and measure the actual time in realistic test scenarios for the use-case. Only if Spring Data Neo4j doesn't perform as fast as required it is recommended to drop down to the native Neo4j API.

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

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 Neo4j 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("template", Neo4jTemplate.class));
    }
}

Now, your resources can require the Spring beans they need, annotated with @Context like this:

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

The SpringPluginInitializer merges the server provided 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.

To use REST-API the Neo4j Server exposes, one would either go with REST libraries on the lower level or choose one of the Neo4j related REST drivers in various languages. For Java Neo4j provides the Neo4j Java REST bindings which come as a drop in replacement for the GraphDatabaseService API. Spring Data Neo4j REST uses those bindings to provide seamless access to a remote Neo4j Database.

By simply configuring the graphDatabaseService to be a SpringRestGraphDatabase pointing to a Neo4j Server instance and referring to that from <neo4j:config> Spring Data Neo4j will use the server side database for both the simple mapping as well as the advanced mapping.

	Note
	The Neo4j Server REST API does not allow for transactions to span across requests, which means that Spring Data Neo4j is not transactional across multiple operations when running with a SpringRestGraphDatabase.

Please also keep in mind that performing graph operations via the REST-API is about one order of magnitude slower than local operations. Try to use the Neo4j Cypher query language, server-side traversals (RestTraversal) or Gremlin expressions whenever possible for retrieving large sets of data. Future versions of Spring Data Neo4j will use the more performant batch API as well as a binary protocol.

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

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

<neo4j:config graphDatabaseService="graphDatabaseService"/>

<bean id="graphDatabaseService" class="org.springframework.data.neo4j.rest.SpringRestGraphDatabase">
    <constructor-arg value="http://localhost:7474/db/data/" index="0"/>
<!-- for running against a server requiring authentication
    <constructor-arg value="username" index="1"/>
    <constructor-arg value="password" index="2"/>
-->
</bean>

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

For traversals and Cypher and Gremlin graph queries it is sensible to forward those to the remote endpoint and execute them there instead of walking the graph over the wire. SpringRestGraphDatabase already supports that by providing methods that forward to the remote instance. (e.g. queryEngineFor(), index() and createTraversalDescription()). Please use those methods when interacting with a remote server for optimal performance. Those methods are also used by the Neo4jTemplate and the mapping infrastructure automatically.