Chapter 2. Tutorial

The demo application uses Gradle as a build system.

Before we can use the library, we need to add a dependency.

Gradle dependencies for Neo4j-OGM. 

compile "org.neo4j:neo4j-ogm-core:3.1.2"
runtime "org.neo4j:neo4j-ogm-bolt-driver:3.1.2"

Refer to Dependency Management for more information on dependencies.

We configure the database parameters by using the configuration builder.

Configuration configuration = new Configuration.Builder()
    .uri("bolt://localhost")
    .credentials("neo4j", "password")
    .build();

SessionFactory sessionFactory = new SessionFactory(configuration, "com.mycompany.app.domainclasses");

POJOs annotated with @NodeEntity will be represented as nodes in the graph.

The label assigned to this node can be specified via the label property on the annotation; if not specified, it will default to the simple class name of the entity. Each parent class in addition also contributes a label to the entity (with the exception of java.lang.Object). This is useful when we want to retrieve collections of super types.

Let’s go ahead and annotate all our node entities in the code we wrote earlier.

Note that we’re overriding the default label for a Course with Class

@NodeEntity
class Department {
    String name;
    Set<Subject> subjects;
}

@NodeEntity
class Subject {
    String name;
    Department department;
    Set<Teacher> teachers;
    Set<Course> courses;
}

@NodeEntity
class Teacher {
    String name;
    Set<Course> courses;
    Set<Subject> subjects;
}

@NodeEntity(label="Class")
class Course {
    String name;
    Subject subject;
    Teacher teacher;
    Set<Enrollment> enrollments;
}

@NodeEntity
class Student {
    String name;
    Set<Enrollment> enrollments;
    Set<StudyBuddy> studyBuddies;
}

Next up, the relationships between the nodes.

Every field in an entity that references another entity is backed by a relationship in the graph. The @Relationship annotation allows you to specify both the type of the relationship and the direction. By default, the direction is assumed to be OUTGOING and the type is the UPPER_SNAKE_CASE field name.

We’re going to be specific about the relationship type to avoid using the default and also make it easier to refactor classes later by not being dependent on the field name. Again, we are going to modify the code we saw in the last section:

@NodeEntity
class Department {
    String name;

    @Relationship(type = "CURRICULUM")
    Set<Subject> subjects;
}

@NodeEntity
class Subject {
    String name;

    @Relationship(type="CURRICULUM", direction = Relationship.INCOMING)
    Department department;

    @Relationship(type = "TAUGHT_BY")
    Set<Teacher> teachers;

    @Relationship(type = "SUBJECT_TAUGHT", direction = "INCOMING")
    Set<Course> courses;
}

@NodeEntity
class Teacher {
    String name;

     @Relationship(type="TEACHES_CLASS")
     Set<Course> courses;

     @Relationship(type="TAUGHT_BY", direction = Relationship.INCOMING)
     Set<Subject> subjects;
}

@NodeEntity(label="Class")
class Course {
    String name;

     @Relationship(type= "SUBJECT_TAUGHT")
     Subject subject;

     @Relationship(type= "TEACHES_CLASS", direction=Relationship.INCOMING)
     Teacher teacher;

     @Relationship(type= "ENROLLED", direction=Relationship.INCOMING)
     Set<Enrollment> enrollments = new HashSet<>();
}

@NodeEntity
class Student {
    String name;

    @Relationship(type = "ENROLLED")
    Set<Enrollment> enrollments;

    @Relationship(type = "BUDDY", direction = Relationship.INCOMING)
    Set<StudyBuddy> studyBuddies;
}

Sometimes something isn’t quite a Node entity.

In this demo the only remaining class to annotate is Enrollment. As discussed earlier, this is a relationship entity since it manages the underlying ENROLLED relation between a student and course. It isn’t a simple relation because it has a relationship property called enrolledDate.

A relationship entity must be annotated with @RelationshipEntity and also the type of relationship. In this case, the type of relationship is ENROLLED as specified in both the Student and Course entities.

We are also going to indicate to Neo4j-OGM the start and end node of this relationship.

@RelationshipEntity(type = "ENROLLED")
class Enrollment {

    @StartNode
    Student student;

    @EndNode
    Course course;

    Date enrolledDate;

}

Every node and relationship persisted to the graph must have an id. Neo4j-OGM uses this to identify and re-connect the entity to the graph in memory. Identifier may be either a primary id or a native graph id.

Since every entity requires an id, we’re going to create an Entity superclass. This is an abstract class, so you’ll see that the nodes do not inherit an Entity label, which is exactly what we want.

If you plan on implementing hashCode and equals make sure it does not make use of the native id. See Node Entities for more information.

abstract class Entity {

    @Id @GeneratedValue
    private Long id;

    public Long getId() {
        return id;
    }
}

Our entities will now extend this class, for example

@NodeEntity
class Department extends Entity {
    String name;

    @Relationship(type = "CURRICULUM")
    Set<Subject> subjects;

    Department() {

    }
}

We are almost there!

Neo4j-OGM also also requires a public no-args constructor to be able to construct objects from all our annotated entities. We’ll make sure all our entities have one.

Neo4j supports Numeric, String, boolean and arrays of these as property values.

How do we handle the enrolledDate since Date is not a valid data type?

Luckily for us, Neo4j-OGM provides many converters out of the box, one of which is a Date to Long converter. We simply annotate the field with @DateLong and the conversion of the Date to it’s Long representation and back is handled by Neo4j-OGM when persisting and loading from the graph.

@RelationshipEntity(type = "ENROLLED")
class Enrollment {

    Long id;

    @StartNode
    Student student;

    @EndNode
    Course course;

    @DateLong
    Date enrolledDate;

    Enrollment() {
    }
}

The smart object mapping capability is provided by the Session object. A Session is obtained from a SessionFactory.

We’re going to set up the SessionFactory just once and have it produce as many sessions as required.

public class Neo4jSessionFactory {

    private final static Configuration = ... // provide configuration as seen before
    private final static SessionFactory sessionFactory = new SessionFactory(configuration, "school.domain");
    private static Neo4jSessionFactory factory = new Neo4jSessionFactory();

    public static Neo4jSessionFactory getInstance() {
        return factory;
    }

    // prevent external instantiation
    private Neo4jSessionFactory() {
    }

    public Session getNeo4jSession() {
        return sessionFactory.openSession();
    }
}

The SessionFactory constructor accepts packages that are to be scanned for annotated domain entities.

The domain objects in our university application are grouped under school.domain. When the SessionFactory is created, it will scan school.domain for potential domain classes and construct the object mapping metadata to be used by all sessions created thereafter.

The Session keeps track of changes made to entities and relationships and persists ones that have been modified on save. Once an entity is tracked by the session, reloading this entity within the scope of the same session will result in the session cache returning the previously loaded entity. However, the subgraph in the session will expand if the entity or its related entities retrieve additional relationships from the graph.

For the purpose of this demo application, we’ll use short living sessions - a new session per web request - to avoid stale data issues.

Our university application will use the following operations:

interface Service<T> {

    Iterable<T> findAll()

    T find(Long id)

    void delete(Long id)

    T createOrUpdate(T object)

}

These CRUD interactions with the graph are all handled by the Session. Let’s write a GenericService to deal with common Session operations.

abstract class GenericService<T> implements Service<T> {

    private static final int DEPTH_LIST = 0
    private static final int DEPTH_ENTITY = 1
    protected Session session = Neo4jSessionFactory.getInstance().getNeo4jSession()

    @Override
    Iterable<T> findAll() {
        return session.loadAll(getEntityType(), DEPTH_LIST)
    }

    @Override
    T find(Long id) {
        return session.load(getEntityType(), id, DEPTH_ENTITY)
    }

    @Override
    void delete(Long id) {
        session.delete(session.load(getEntityType(), id))
    }

    @Override
    T createOrUpdate(T entity) {
        session.save(entity, DEPTH_ENTITY)
        return find(entity.id)
    }

    abstract Class<T> getEntityType()
}

One of the features of Neo4j-OGM is variable depth persistence. This means you can vary the depth of fetches depending on the shape of your data and application. The default depth is 1, which loads simple properties of the entity and its immediate relations. This is sufficient for the find method, which is used in the application to present a create or edit form for an entity.

Loading relationships is not required when listing all entities of a type. We merely require the id and name of the entity, and so a depth of 0 is used by findAll to only load simple properties of the entity but skip its relationships.

The default save depth is -1, or everything that has been modified and can be reached from the entity up to an infinite depth. This means we can persist all our changes in one go.

This GenericService takes care of CRUD operations for all our entities! All we did was delegate to the Session; no need to write persistence logic for every entity.

Popular Study Buddies is a report that lists the most popular peer study groups. This requires a custom Cypher query. It is easy to supply a Cypher query to the query method available on the Session.

class StudyBuddyServiceImpl extends GenericService<StudyBuddy> implements StudyBuddyService {

    @Override
    Iterable<StudyBuddy> findAll() {
        return session.loadAll(StudyBuddy, 1)
    }

    @Override
    Iterable<Map<String, Object>> getStudyBuddiesByPopularity() {
        String query = "MATCH (s:StudyBuddy)<-[:BUDDY]-(p:Student) return p, count(s) as buddies ORDER BY buddies DESC"
        return Neo4jSessionFactory.getInstance().getNeo4jSession().query(query, Collections.EMPTY_MAP)
    }

    @Override
    Class<StudyBuddy> getEntityType() {
        return StudyBuddy.class
    }
}

The query provided by the Session can return a domain object, a collection of them, or a special wrapped object called a Result.