As explained in Chapter 1, Why Spring Data Graph?, Spring Data Graph (DATAGRAPH) provides integration between the Spring framework and graph databases. Familiarity with the Spring framework is assumed as stated in Part I, “Introduction”, and only minimally cross-referenced here. Graph databases and Neo4j in particular are explained in a bit more detail. minimally cross-referenced here. Graph databases and Neo4j in particular are explained in a bit more detail. The main focus of this document is however on explaining the steps needed to get a DATAGRAPH-backed application up and running.

If you encounter issues or you are just looking for an advice, feel free to use one of the links below:

For information on the Spring Data source code repository, nightly builds and snapshot artifacts please see the Spring Data home page.

You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the community forums.

If you encounter a bug or want to suggest an improvement, please create a ticket on the DATAGRAPH issue tracker.

To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community Portal.

Lastly, you can follow the SpringSource Data blog or the project team on Twitter (@SpringData)

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

The GraphDatabaseService is the API interface to the storage engine. It provides access to create and retrieve Nodes and Relationships, an IndexManager, lifecycle and transactional methods and more.

The EmbeddedGraphDatabaseService is running within the current Java application for highest performance and tightest integration. There are other, remote implementations that provide access to Neo4j stores via REST or RMI.

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

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

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

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

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

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

The best way for retrieving start nodes for traversals is using Neo4j's index facilities. The GraphDatabaseService provides access to the IndexManager which in turn retrieves named indexes for nodes and relationships. Both can be indexed with property names and values. Retrieval happens via IndexHits which are an Iterator over the results.

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

Currently indexing is a manual process; auto-indexes are a future feature. (DATAGRAPH already provides auto-indexing via the @Indexed annotation.)

Behind the scenes DATAGRAPH leverages AspectJ aspects to modify the behavior of simple POJO entities to be able to be backed by a graph store. Each entity is backed by a node that holds its properties and relationships to other entities. AspectJ is used to intercept field access and to reroute it to the backing state (either its properties or relationships). For relationship entities the fields are similarly mapped to properties. There are two specially annotated fields for the start and the end node of the relationship.

The aspect introduces some internal fields and some public methods to the entities for accessing the backing state via getUnderlyingState() and creating relationships with relateTo and retrieving relationship entities via getRelationshipTo. It also introduces finder methods like find(Class<? extends NodeEntity>, TraversalDescription) and equals and hashCode delegation.

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

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

@NodeEntity
public class Movie { 
	String title;
}

@RelationshipEntity
public class Role { 
	@StartNode
	private Actor actor;
	@EndNode
	private Movie movie;

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

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

Spring Data Graph also comes with a type bound Repository-like Finder implementation that provides methods for locating nodes and relationships.

The Finder instances are created via a FinderFactory to be bound to a concrete node or relationship entity class. The FinderFactory is created in the Spring context and can be injected.

NodeFinder<Person> finder = finderFactory.createNodeEntityFinder(Person.class);
Person dave=finder.findById(123);
int people = finder.count();
Person mark = finder.findByPropertyValue("name", "mark");
Iterable<Person> devs = finder.findAllByProperyValue("occupation","developer");
Iterable<Person> davesFriends = finder.findAllByTraversal(dave,
    Traversal.description().pruneAfterDepth(1)
    .relationships(KNOWS).filter(returnAllButStartNode()));

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. That's why the hierarchy up to java.lang.Object of all these classes will be persisted in the graph. Implementations of NodeTypeStrategy take care of persisting this information on entity instance creation. They also provide the repository methods that use this type information to perform their operations like findAll, count etc.

The current implementation uses nodes to represent the Java type hierarchy which are connected via SUBCLASS_OF relationships to their superclass nodes and via INSTANCE_OF relationships to the concrete node entity instance node.

An alternative approach could use indexing operations to perform the same functionality. Or one could skip the NodeTypeStrategy altogether if no strict checks on type conformity are needed that would allow for a much more flexible data model.

Neo4j is a transactional datastore which only allows modifications within transaction boundaries and fullfills the ACID properties. Reading from the store is also possible outside of transactions. Neo4j also provides a Spring compliant transaction manager that allows it to participate in Spring managed transactions (also with @Transactional). This transaction manager is already configured in the Spring Java config, class AbstractNeo4jConfiguration.

DATAGRAPH is designed to work within transaction boundaries. So entity creation and modification should happen within transactional methods. Due to the usage of POJO entities it is common to create and populate them also outside of a transaction (e.g. in the web layer). That's why some housekeeping support was added to DATAGRAPH. It is possible to create node entities outside of transactions and also to modify their fields. Those values are then not stored within the backing node but instead only in the entity itself. When the entity reenters a transactional context and its fields are read or written to, all the pending changes are flushed to the backing node first.

At the moment there is no support for the creation of relationships outside of transactions and also more complex operations like creating whole subgraphs is not supported.

The node and relationship aspects introduce (via ITD - inter type declaration) several methods to the entities that make common tasks easier. Unfortunately those methods are not generified yet, so the results have to be casted to the correct return type.

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

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

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

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

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

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

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

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

<repository>
	<id>neo4j-public-repository</id>
	<name>Publically available Maven 2 repository for Neo4j</name>
	<url>http://m2.neo4j.org</url>
</repository>
				

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

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

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

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

That's why DATAGRAPH provides a Spring Java Config class (annotated with @Config) AbstractNeo4jConfiguration that takes care of all that. The only thing that must be provided in the custom Spring config is the GraphDatabaseService configured with a datastore directory. This can be achieved by extending that class and implementing the graphDatabaseService method.

public class MyConfig extends AbstractNeo4jConfiguration {
    @Override
    public boolean isUsingCrossStorePersistence() {
        return false;
    }

    @Bean(destroyMethod = "shutDown")
    public GraphDatabaseService graphDatabaseService() {
        return new EmbeddedGraphDatabase("target/neo4j-db");
    }
}			

<beans>
...

	<tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
	<bean class="org.springframework.data.graph.examples.config.MyConfig"/>
    <bean class="org.springframework.context.annotation.ConfigurationClassPostProcessor"/>
...
</beans>    
			

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

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

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

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

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

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

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

	    @GraphProperty
	    @Transient
	    String nickname;

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

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

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

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

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

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

		@Transactional
	    public Recommendation rate(Restaurant restaurant, int stars, String comment) {
	        Recommendation 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 DATAGRAPH operations. The concise Spring Java Config configuration class already contains a method isUsingCrossStorePersistencethat must be implemented by a concrete configuration which controls the cross-store mode of DATAGRAPH.

public class MyRestaurantConfig extends AbstractNeo4jConfiguration {
    @Override
    public boolean isUsingCrossStorePersistence() {
        return true;
    }

    @Bean(destroyMethod = "shutDown")
    public GraphDatabaseService graphDatabaseService() {
        return new EmbeddedGraphDatabase("target/myrestaurant-social");
    }
}			

<beans>
...
	<tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
	<bean class="com.springone.myrestaurants.config.MyRestaurantConfig"/>
    <bean class="org.springframework.context.annotation.ConfigurationClassPostProcessor"/>
...
</beans>