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. 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 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 relationship 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, reading from the graph store can also be done without transactions.

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 nodes or relationship and reading from 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 );
}

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. Behind each entity lies a backing node that holds the 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

The Finder instances are created via a FinderFactory to be bound to a concrete node entity class.

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.

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.

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

As stated in the requirements chapter, DATAGRAPH is built easiest with Apache Maven. Its 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.M1</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>    
			

This is achieved by allowing the DATAGRAPH aspects only to handle those parts of the entities that are explicitely annotated with DATAGRAPH annotations. 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 the connection between the two stores can be kept. So 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 makes the Java type hierarchy of the datamodel accessible in the graph. So those pieces of information can be used to 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>