Review

In the previous section, we have laid down the functional specs of the application and discussed the Neo4j data model. In this section, we will discuss the project's structure, write the Java classes, and map our domain classes to the Neo4j data model.

Part 1: Introduction and Functional Specs
Part 2: Java classes
Part 3: XML configuration
Part 4: HTML (with AJAX)
Part 5: Running the Application

Project Structure

Our application is a Maven project and therefore follows Maven structure. As we create the classes, we've organized them in logical layers: domain, repository, service, and controller.

Here's a preview of our project's structure:

The Layers

Domain Layer

This layer contains the following POJOs:

User - represents our user
Role - represents the role of the user
UserRoleRelationship - represents the relationship of a user to its role

	package org.krams.domain;

	import org.springframework.data.neo4j.annotation.Fetch;
	import org.springframework.data.neo4j.annotation.GraphId;
	import org.springframework.data.neo4j.annotation.Indexed;
	import org.springframework.data.neo4j.annotation.NodeEntity;
	import org.springframework.data.neo4j.annotation.RelatedTo;

	@NodeEntity
	public class User {

	@GraphId
	private Long id;

	private String firstName;
	private String lastName;

	@Indexed
	private String username;
	private String password;

	@Fetch @RelatedTo(type = "HAS_ROLE")
	private Role role;

	...getters/setters
	}

view raw User.java hosted with ❤ by GitHub

	package org.krams.domain;

	import org.springframework.data.neo4j.annotation.GraphId;
	import org.springframework.data.neo4j.annotation.NodeEntity;

	@NodeEntity
	public class Role {

	@GraphId
	private Long id;
	private User user;
	private Integer role;

	...getters/setters
	}

view raw Role.java hosted with ❤ by GitHub

	package org.krams.domain;

	import org.springframework.data.neo4j.annotation.EndNode;
	import org.springframework.data.neo4j.annotation.RelationshipEntity;
	import org.springframework.data.neo4j.annotation.StartNode;

	@RelationshipEntity(type = "HAS_ROLE")
	public class UserRoleRelationship {

	private String description;

	@StartNode private User user;

	@EndNode private Role role;

	...getters/setters
	}

view raw UserRoleRelationship.java hosted with ❤ by GitHub

Notice we've annotated our domain classes with Spring Data Neo4j annotations. Here are the explanations:

@NodeEntity

The @NodeEntity annotation is used to turn a POJO class into an entity backed by a node in the graph database. Fields on the entity are by default mapped to properties of the node. Fields referencing other node entities (or collections thereof) are linked with relationships.

Source: Spring Data Neo4j Reference

@GraphId

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.

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

Source: Spring Data Neo4j Reference

@Indexed

@Indexed: Making entities searchable by field value

The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j indexing facilities. The resulting index can be used to later retrieve nodes or relationships that contain a certain property value, e.g. a name. Often an index is used to establish the start node for a traversal.

Source: Spring Data Neo4j Reference

@Fetch

To have the collections of relationships being read eagerly ... we have to annotate it with the @Fetch annotation. Otherwise Spring Data Neo4j refrains from following relationships automatically.

Source: Spring Data Neo4j Reference

@RelatedTo

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

Source: Spring Data Neo4j Reference

@RelationshipEntity

To access the full data model of graph relationships, POJOs can also be annotated with @RelationshipEntity, making them relationship entities. Just as node entities represent nodes in the graph, relationship entities represent relationships. As described above, fields annotated with @RelatedTo provide a way to link node entities together via relationships, but it provides no way of accessing the relationships themselves.

Relationship entities can be accessed via by @RelatedToVia-annotated

Fields in relationship entities are, similarly to node entities, persisted as properties on the relationship. For accessing the two endpoints of the relationship, two special annotations are available: @StartNode and @EndNode. A field annotated with one of these annotations will provide read-only access to the corresponding endpoint, depending on the chosen annotation.

Source: Spring Data Neo4j Reference

Controller Layer

This layer contains two controllers, MediatorController and UserController

MediatorController is responsible for redirecting requests to appropriate pages. This isn't really required but it's here for organizational purposes.
UserController is responsible for handling user-related requests such as adding and deleting of records

	package org.krams.controller;

	import org.springframework.stereotype.Controller;
	import org.springframework.web.bind.annotation.RequestMapping;

	@Controller
	@RequestMapping("/")
	public class MediatorController {

	@RequestMapping
	public String getHomePage() {
	return "redirect:/users";
	}
	}

view raw MediatorController.java hosted with ❤ by GitHub

	package org.krams.controller;

	import org.krams.domain.Role;
	import org.krams.domain.User;
	import org.krams.dto.UserDto;
	import org.krams.dto.UserListDto;
	import org.krams.dto.UserMapper;
	import org.krams.service.UserService;
	import org.springframework.beans.factory.annotation.Autowired;
	import org.springframework.stereotype.Controller;
	import org.springframework.web.bind.annotation.RequestBody;
	import org.springframework.web.bind.annotation.RequestMapping;
	import org.springframework.web.bind.annotation.RequestMethod;
	import org.springframework.web.bind.annotation.RequestParam;
	import org.springframework.web.bind.annotation.ResponseBody;

	@Controller
	@RequestMapping("/users")
	public class UserController {

	@Autowired
	private UserService service;

	@RequestMapping
	public String getUsersPage() {
	return "users";
	}

	@RequestMapping(value="/records")
	public @ResponseBody UserListDto getUsers() {

	UserListDto userListDto = new UserListDto();
	userListDto.setUsers(UserMapper.map(service.readAll()));
	return userListDto;
	}

	@RequestMapping(value="/get")
	public @ResponseBody User get(@RequestBody User user) {
	return service.read(user);
	}

	@RequestMapping(value="/create", method=RequestMethod.POST)
	public @ResponseBody UserDto create(
	@RequestParam String username,
	@RequestParam String password,
	@RequestParam String firstName,
	@RequestParam String lastName,
	@RequestParam Integer role) {

	Role newRole = new Role();
	newRole.setRole(role);

	User newUser = new User();
	newUser.setUsername(username);
	newUser.setPassword(password);
	newUser.setFirstName(firstName);
	newUser.setLastName(lastName);
	newUser.setRole(newRole);

	return UserMapper.map(service.create(newUser));
	}

	@RequestMapping(value="/update", method=RequestMethod.POST)
	public @ResponseBody UserDto update(
	@RequestParam String username,
	@RequestParam String firstName,
	@RequestParam String lastName,
	@RequestParam Integer role) {

	Role existingRole = new Role();
	existingRole.setRole(role);

	User existingUser = new User();
	existingUser.setUsername(username);
	existingUser.setFirstName(firstName);
	existingUser.setLastName(lastName);
	existingUser.setRole(existingRole);

	return UserMapper.map(service.update(existingUser));
	}

	@RequestMapping(value="/delete", method=RequestMethod.POST)
	public @ResponseBody Boolean delete(
	@RequestParam String username) {

	User existingUser = new User();
	existingUser.setUsername(username);

	return service.delete(existingUser);
	}
	}

view raw UserController.java hosted with ❤ by GitHub

Service Layer

This layer contains a single service, UserService for managing users.

	package org.krams.service;

	import java.util.ArrayList;
	import java.util.List;
	import org.krams.domain.User;
	import org.krams.repository.RoleRepository;
	import org.krams.repository.UserRepository;
	import org.springframework.beans.factory.annotation.Autowired;
	import org.springframework.data.neo4j.conversion.EndResult;
	import org.springframework.stereotype.Service;

	@Service
	public class UserService {

	@Autowired
	private UserRepository userRepository;

	@Autowired
	private RoleRepository roleRepository;

	public User create(User user) {
	User existingUser = userRepository.findByUsername(user.getUsername());

	if (existingUser != null) {
	throw new RuntimeException("Record already exists!");
	}

	user.getRole().setUser(user);
	return userRepository.save(user);
	}

	public User read(User user) {
	return user;
	}

	public List<User> readAll() {
	List<User> users = new ArrayList<User>();

	EndResult<User> results = userRepository.findAll();
	for (User r: results) {
	users.add(r);
	}

	return users;
	}

	public User update(User user) {
	User existingUser = userRepository.findByUsername(user.getUsername());

	if (existingUser == null) {
	return null;
	}

	existingUser.setFirstName(user.getFirstName());
	existingUser.setLastName(user.getLastName());
	existingUser.getRole().setRole(user.getRole().getRole());

	roleRepository.save(existingUser.getRole());
	return userRepository.save(existingUser);
	}

	public Boolean delete(User user) {
	User existingUser = userRepository.findByUsername(user.getUsername());

	if (existingUser == null) {
	return false;
	}

	userRepository.delete(existingUser);
	return true;
	}
	}

view raw UserService.java hosted with ❤ by GitHub

What is Spring Data Neo4j?

Spring Data Neo4j enables POJO based development for the Graph Database Neo4j. It maps annotated entity classes to the Neo4j Graph Database with advanced mapping functionality. The template programming model is equivalent to well known Spring templates and builds the basis for interaction with the graph and is also used for the advanced repository support.
Spring Data Neo4j is part of the Spring Data project which aims to provide convenient support for NoSQL databases.

Source: http://www.springsource.org/spring-data/neo4j

Utility classes

TraceInterceptor class is an AOP-based utility class to help us debug our application. This is a subclass of CustomizableTraceInterceptor (see Spring Data JPA FAQ)

	package org.krams.aop;

	import org.aopalliance.intercept.MethodInvocation;
	import org.apache.commons.logging.Log;
	import org.apache.log4j.Logger;
	import org.springframework.aop.interceptor.CustomizableTraceInterceptor;

	/**
	* Extends {@link CustomizableTraceInterceptor} to provide custom logging levels
	*/
	public class TraceInterceptor extends CustomizableTraceInterceptor {

	private static final long serialVersionUID = 287162721460370957L;
	protected static Logger logger4J = Logger.getLogger("aop");

	@Override
	protected void writeToLog(Log logger, String message, Throwable ex) {
	if (ex != null) {
	logger4J.debug(message, ex);
	} else {
	logger4J.debug(message);
	}
	}

	@Override
	protected boolean isInterceptorEnabled(MethodInvocation invocation, Log logger) {
	return true;
	}
	}