Neo4j in Action (2015)

Appendix C. Setting up your project to use SDN

This appendix will walk you through the setup instructions required to run SDN. Specifically, these instructions are for version 3.2.1.RELEASE of SDN, which is officially compatible with Neo4j 2.1.5. The SDN 3.2.1.RELEASE version is the one referred to in the dedicated SDN chapter (chapter 10), and it’s the version used by the accompanying source code as well.

The easiest way to configure your project to use SDN is through a Maven build, which is also used for the accompanying source code. General instructions for setting up and installing Maven are provided in appendix B. SDN can also be built with Gradle or Ant/Ivy if you’d like; instructions for how to do this can be found at http://docs.spring.io/spring-data/data-neo4j/docs/current/reference/html/#setup.

This appendix will also provide details of the minimal Spring configuration required to make SDN function appropriately.

Depending on whether you want to make use of the simple or the advanced mapping mode, the setup will be a bit different. The source code for chapter 9 provides a configured setup for both simple and advanced mapping modes.

The most up-to-date set of instructions, as well as options not specified here, can be found in Michael Hunger’s Good Relationships: http://docs.spring.io/spring-data/data-neo4j/docs/current/reference/html/#setup.

SDN versions and official documentation references

This book targets SDN version 3.2.1, compatible with Neo4j version 2.1.5. As you can appreciate, writing a book while trying to keep up with the latest versions of open source software can be challenging at the best of times. To ensure you always have links to the latest information, we have endeavored to use references that point to the latest stable release of the official documentation. At the time of writing, all SDN documentation URLs follow a common pattern, namely http://docs.spring.io/spring-data/data-neo4j/docs/<version>/reference/html where version is the SDN version of the docs you wish to view, with current being an alias that always points to the latest, most stable released version.

For the 3.2.1-specific information, please consult http://docs.spring.io/spring-data/data-neo4j/docs/3.2.1.RELEASE/reference/html. For the latest stable release, please consult http://docs.spring.io/spring-data/data-neo4j/docs/current/reference/html.

C.1. Maven configuration

If you’re using Maven, you need to ensure that one of the following sets of Maven dependencies (either listing C.1 or C.2 as appropriate) is included in your pom.xml file. The choice depends on which mapping mode you are using.

The following listing shows the dependencies for the simple mapping mode.

Listing C.1. Maven dependencies required for the simple mapping mode

In theory, the core spring-data-neo4j artifact should be all that’s required, but in reality there’s currently one other library that also needs to be included in order for SDN to function correctly, and it is an implementation of the JSR-303 Validation Spec API. In our sample code, we’ve chosen the Hibernate implementation. The SDN library itself makes use of the validation API, so users need to provide an actual implementation at runtime.

Both the simple and advanced versions of the SDN library make use of Maven’s transitive dependency management system to ensure that all of the supporting libraries required for development are automatically pulled down.

The following listing shows the dependencies for the advanced mapping mode.

Listing C.2. Maven dependencies required for the advanced mapping mode

As with the simple mapping mode, you’ll need to explicitly include a dependency to a concrete JSR 303 implementation library. Again, we’ve used the Hibernate one here.

In addition to the dependencies themselves, the advanced mapping mode requires you to configure the Maven build to use AspectJ for the build-time weaving of entities. The following listing shows the snippet of configuration that will need to be added to your pom.xml file to achieve this.

Listing C.3. AspectJ build configuration for the advanced mapping mode

<build>

<groupId>org.codehaus.mojo</groupId>

<artifactId>aspectj-maven-plugin</artifactId>

<groupId>org.aspectj</groupId>

<artifactId>aspectjrt</artifactId>

</dependency>

<groupId>org.aspectj</groupId>

<artifactId>aspectjtools</artifactId>

</dependency>

</dependencies>

<goals>

<goal>compile</goal>

<goal>test-compile</goal>

</goals>

</execution>

</executions>

<groupId>org.springframework</groupId>

<artifactId>spring-aspects</artifactId>

</aspectLibrary>

<groupId>org.springframework.data</groupId>

<artifactId>spring-data-neo4j-aspects</artifactId>

</aspectLibrary>

</aspectLibraries>

</configuration>

</plugin>

</plugins>

</build>

C.2. Spring configuration

This section looks at what’s required to set up and configure Spring within your application. The setup is relatively minimal, so even if you don’t know Spring, it shouldn’t prove too painful.

The Spring configuration itself can be done either via an XML file or Spring’s Java bean configuration (using @Configuration annotations). As most of the SDN documentation at the time of writing provides examples using XML, we’ll do likewise here, but you can look up how to make use of the Java bean approach in chapter 21 of Michael Hunger’s Good Relationships: http://docs.spring.io/spring-data/data-neo4j/docs/current/reference/html/#setup.

Core XML configuration

You need to tell Spring what beans need to be created and instantiated. With the XML approach, this is done by providing an XML file with initial content that looks like the following.

Listing C.1. XML configuration using a store directory

The Neo4j-specific XML namespace element, neo4j:config, provides a simple way of concisely configuring SDN. It creates or exposes the core graph database bean as well as other helper classes, such as the Neo4jTemplate.

The neo4j:config element itself has four attributes (storeDirectory, graph-DatabaseService, entityManagerFactory, and typeRepresentationStrategyFactory) that can be configured. For convenience, there is a storeDirectory attribute that when set points to a particular directory where a new EmbeddedGraphDatabase will be created if one doesn’t exist (if one is already there, it will be used). This is the approach used in the sample code.

You can make use of the graphDatabaseService attribute to point to a particular preconfigured Neo4j instance that should be used. In that case you’d also need to define a factory bean to create an appropriate Neo4j instance, as shown in the following snippet:

<neo4j:config graphDatabaseService="graphDatabaseService" />

<bean id="graphDbFactory"

class="org.neo4j.graphdb.factory.GraphDatabaseFactory"/>

<bean id="graphDatabaseService"

scope="singleton"

destroy-method="shutdown"

factory-bean="graphDbFactory"

factory-method="newEmbeddedDatabase">

<constructor-arg value="target/config-test"/>

</bean>

As of SDN 3.0, the base-package XML element is mandatory, and you’re expected to supply a list of all the packages that SDN should search to find your annotated domain entities. If you’re engaging in cross-store persistence, you’ll also need to supply the entityManagerFactoryattribute value (not shown here).

If you’d like to make use of a type representation strategy other than the default one (SDN 3.x defaults to label-based; SDN 2.x defaults to legacy indexed-based), you can optionally define a bean named typeRepresentationStrategyFactory of typeorg.springframework.data.neo4j.support.typerepresentation.TypeRepresentationStrategyFactory, as shown in the following snippet, choosing an appropriate value for the second constructor argument:

<bean id="typeRepresentationStrategyFactory"

class="org.springframework.data.neo4j.support.typerepresentation.TypeRepresentationStrategyFactory">

<constructor-arg index="0" ref="graphDatabase"/>

<constructor-arg index="1" value="Indexed"/>

</bean>

More information on the available options can be found in the “Entity type representation” section in chapter 20 of Michael Hunger’s Good Relationships at http://docs.spring.io/spring-data/data-neo4j/docs/current/reference/html/#reference_programming-model_typerepresentationstrategy.

For more configuration options see the official website.

Repository configuration

Within the XML configuration approach, SDN repositories can be configured using the <neo4j:repositories> element. The following snippet shows an example of how to instruct Spring to look within the com.manning.neo4jia.chapter09.simple .repository Java package to find repository classes that need to be made available as Spring beans for use by SDN:

<neo4j:repositories base-package=

"com.manning.neo4jia.chapter09.simple.repository"/>

You’d replace the package name with the location where your specific repository implementations live. The package element defines the base-package (or packages) to search through to find repositories.

Additional Spring Data Commons Configuration Options

SDN is built on top of the infrastructure and libraries provided by the Spring Data Commons project. The additional configuration options made available via SD Commons should also work here.

How does Spring know where to find the XML configuration file?

The short answer is that you need to tell it, but this will generally depend on what kind of application you are creating.

If you’re building a web application, the Spring Web framework provides a custom ContextLoaderListener class that you can use within your web.xml file to create the container, as shown in the following snippet. Note that in this case, the XML configuration file (applicationContext.xml) is referred to from its location within the WEB-INF directory:

<context-param>

<param-name>contextConfigLocation</param-name>

<param-value>/WEB-INF/applicationContext.xml</param-value>

</context-param>

<listener-class>

org.springframework.web.context.ContextLoaderListener

</listener-class>

</listener>

Alternatively, if you’re building a standalone Java application, you could make use of the ClassPathXmlApplicationContext class, as shown in the following snippet:

ClassPathXmlApplicationContext ctx

= new ClassPathXmlApplicationContext(

"classpath:applicationContext.xml");

UserRepository userRepository = ctx.getBean(UserRepository.class);

...

For more options on other ways you can provide Spring with its configuration details, see the “Introduction to the Spring IoC container and beans” section of the Spring Framework Reference Documentation: http://docs.spring.io/spring/docs/4.0.x/spring-framework-reference/htmlsingle/#beans-introduction.