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

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

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

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

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

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

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

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

@NodeEntity
public class Movie {
private Actor topActor;
}

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

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

@RelationshipEntity
public class Role {
String title;

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

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

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

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

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

    // automatically indexed numerically
    @Indexed
    int age;

}

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

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

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

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

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

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

@Autowired GraphDatabaseContext gdc;

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

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

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

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

            

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

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

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

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

TraversalQueryExecutor works with the traversal framework.

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

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

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

Person dave=graphRepository.findOne(123);

Long numberOfPeople = graphRepository.count();

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

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

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

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

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

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

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

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

// have it injected
@Autowired
PersonRepository personRepository;

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

    Person dave=personRepository.findOne(123);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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