21. Environment setup

Spring Data Neo4j dramatically simplifies development, but some setup is naturally required. For building the application, Maven needs to be configured to include the Spring Data Neo4j dependencies. For the advanced mapping mode, it is necessary to configure the AspectJ weaving. After the build setup is complete, the Spring application needs to be configured to make use of Spring Data Neo4j. Examples for these different setups can be found in the Spring Data Neo4j examples.

Spring Data Neo4j projects can be built using Maven. There are also means to build them with Gradle or Ant/Ivy.

21.1 Dependencies for Spring Data Neo4j Simple Mapping

For the simple POJO mapping it is enough to add the org.springframework.data:spring-data-neo4j:2.1.0.RELEASE dependency to your project.

Example 21.1. Maven dependencies for Spring Data Neo4j

<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-neo4j</artifactId>
<version>2.1.0.RELEASE</version>
</dependency>

21.2 Gradle configuration for Advanced Mapping (AspectJ)

The necessary build plugin to build Spring Data Neo4j projects with Gradle is available as part of the Spring Data Neo4j distribution or on Github which makes the usage as easy as:

Example 21.2. Gradle Build Configuration

sourceCompatibility = 1.6
targetCompatibility = 1.6

springVersion = "3.1.0.RELEASE"
springDataNeo4jVersion = "2.1.0.RELEASE"
aspectjVersion = "1.6.12"

apply from:'https://github.com/SpringSource/spring-data-neo4j/raw/master/build/
gradle/springdataneo4j.gradle'

configurations {
    runtime
    testCompile
}
repositories {
    mavenCentral()
	mavenLocal()
	mavenRepo urls: "http://maven.springframework.org/release"
}

The actual springdataneo4j.gradle is very simple, just decorating the javac tasks with the iajc ant task.

21.3 Ant/Ivy configuration for Advanced Mapping (AspectJ)

The supplied sample ant build configuration is mainly about resolving the dependencies for Spring Data Neo4j Aspects and AspectJ using Ivy and integrating the iajc ant task in the build.

Example 21.3. Ant/Ivy Build Configuration

	<taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties" classpath="${lib.dir}/aspectjtools.jar"/>

<target name="compile" description="Compile production classes" depends="lib.retrieve">
	<mkdir dir="${main.target}" />

	<iajc sourceroots="${main.src}" destDir="${main.target}" classpathref="path.libs" source="1.6">
		<aspectpath>
			<pathelement location="${lib.dir}/spring-aspects.jar"/>
		</aspectpath>
		<aspectpath>
			<pathelement location="${lib.dir}/spring-data-neo4j-aspects.jar"/>
		</aspectpath>
	</iajc>
</target>

21.4 Maven configuration for Advanced Mapping

Spring Data Neo4j projects are easiest to build with Apache Maven. The core dependency is Spring Data Neo4j Aspects which comes with transitive dependencies to Spring Data Neo4j, Spring Data Commons, parts of the Spring Framework, AspectJ and the Neo4j graph database.

21.4.1 Repositories

The milestone releases of Spring Data Neo4j are available from the dedicated milestone repository. Neo4j releases and milestones are available from Maven Central.

Example 21.4. Spring milestone repository

<repository>
    <id>spring-maven-milestone</id>
    <name>Springframework Maven Repository</name>
    <url>http://maven.springframework.org/milestone</url>
</repository>

21.4.2 Dependencies

The dependency on spring-data-neo4j-aspects will transitively pull in the necessary parts of Spring Framework (core, context, aop, aspects, tx), AspectJ, Neo4j, and Spring Data Commons. If you already use these (or different versions of these) in your project, then include those dependencies on your own. In this case, please make sure that the versions match. If you want to use Gremlin, please add the dependency (which is optional in SDN) accordingly.

Example 21.5. Maven dependencies

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-neo4j-aspects</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

<dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjrt</artifactId>
    <version>1.6.12</version>
</dependency>

21.4.3 Maven AspectJ build configuration

Since the advanced mapping uses AspectJ for build-time aspect weaving of entities, it is necessary to hook the AspectJ Maven plugin into the build process. The plugin also has its own dependencies. You also need to explicitly specify the aspect libraries (spring-aspects and spring-data-neo4j-aspects).

Example 21.6. AspectJ configuration

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>aspectj-maven-plugin</artifactId>
    <version>1.2</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.12</version>
        </dependency>
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjtools</artifactId>
            <version>1.6.12</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-data-neo4j-aspects</artifactId>
            </aspectLibrary>
        </aspectLibraries>
        <source>1.6</source>
        <target>1.6</target>
    </configuration>
</plugin>

21.5 Spring configuration

Users of Spring Data Neo4j have two ways of very concisely configuring it. Either they can use a Spring Data Neo4j XML configuration namespace, or they can use a Java-based bean configuration.

21.5.1 XML namespace

The XML namespace can be used to configure Spring Data Neo4j. The config element provides an XML-based configuration of Spring Data Neo4j in one line. It has three attributes. graphDatabaseService points out the Neo4j instance to use. For convenience, storeDirectory can be set instead of graphDatabaseService to point to a directory where a new EmbeddedGraphDatabase will be created. For cross-store configuration, the entityManagerFactory attribute needs to be configured.

Example 21.7. XML configuration with store directory

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:context="http://www.springframework.org/schema/context"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:neo4j="http://www.springframework.org/schema/data/neo4j"
        xsi:schemaLocation="
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd
            http://www.springframework.org/schema/context
            http://www.springframework.org/schema/context/spring-context.xsd
            http://www.springframework.org/schema/data/neo4j
            http://www.springframework.org/schema/data/neo4j/spring-neo4j.xsd">

    <context:annotation-config/>
    <neo4j:config storeDirectory="target/config-test"/>

</beans>

Example 21.8. XML configuration with GraphDatabaseService bean

<context:annotation-config/>

<bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase"
        destroy-method="shutdown">
    <constructor-arg index="0" value="target/config-test"/>
<!-- optionally pass in neo4j-config parameters to the graph database
    <constructor-arg index="1">
        <map>
            <entry key="allow_store_upgrade" value="true"/>
        </map>
    </constructor-arg>
-->
</bean>

<neo4j:config graphDatabaseService="graphDatabaseService"/>

Example 21.9. XML configuration with embedded Neo4j-Server

<context:annotation-config/>

<bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase"
    destroy-method="shutdown">
	<constructor-arg index="0" value="foo/db" />
	<constructor-arg index="1">
		<map><entry key="enable_remote_shell" value="true"/></map>
    </constructor-arg>
</bean>

<bean id="serverWrapper" class="org.neo4j.server.WrappingNeoServerBootstrapper" 
	init-method="start" destroy-method="stop">
	<constructor-arg ref="graphDatabaseService"/>
</bean>

// also add the static server-assets dependency to your pom.xml
<dependency>
    <groupId>org.neo4j.app</groupId>
    <artifactId>neo4j-server</artifactId>
    <classifier>static-web</classifier>
    <version>${neo4j-version}</version>
</dependency>

Example 21.10. XML configuration with cross-store

<context:annotation-config/>

<bean class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"
        id="entityManagerFactory">
    <property name="dataSource" ref="dataSource"/>
    <property name="persistenceXmlLocation" value="classpath:META-INF/persistence.xml"/>
</bean>

<neo4j:config storeDirectory="target/config-test"
        entityManagerFactory="entityManagerFactory"/>

21.5.2 Repository Configuration

Spring Data Neo4j repositories are configured using the <neo4j:repositories> element which defines the base-package (or packages) for the repositories. A reference to an existing Neo4jTemplate bean reference can be passed in as well.

As Spring Data Neo4j repositories build upon the infrastructure provided by Spring Data Commons, the configuration options for repositories described there work here as well.

Example 21.11. XML configuration for repositories

<neo4j:repositories base-package="org.example.repository"/>		

<!-- with template bean reference -->
<neo4j:repositories base-package="org.example.repository" graph-database-context-ref="template"/>		
		

21.5.3 Java-based bean configuration

You can also configure Spring Data Neo4j using Java-based bean metadata.

[Note]Note

For those not familiar with Java-based bean configuration in Spring, we recommend that you read up on it first. The Spring documentation has a high-level introduction as well as detailed documentation on it.

In order to configure Spring Data Neo4j with Java-based bean config, the class Neo4jConfiguration is registered with the context. This is either done explicitly in the context configuration, or via classpath scanning for classes that have the @Configuration annotation. The only thing that must be provided is the GraphDatabaseService. The example below shows how to register the @Configuration Neo4jConfiguration class, as well as Spring's ConfigurationClassPostProcessor that transforms the @Configuration class to bean definitions.

Example 21.12. Java-based bean configuration

<![CDATA[<beans ...>
    ...
    <tx:annotation-driven mode="aspectj" transaction-manager="transactionManager"/>
    <bean class="org.springframework.data.neo4j.config.Neo4jConfiguration"/>

    <bean class="org.springframework.context.annotation.ConfigurationClassPostProcessor"/>

    <bean id="graphDatabaseService" class="org.neo4j.kernel.EmbeddedGraphDatabase"
          destroy-method="shutdown" scope="singleton">
        <constructor-arg index="0" value="target/config-test"/>
    </bean>
    ...
</beans>


Additional beans can be configured to be included in the Neo4j-Configuration just by defining them in the Spring context. ConversionService for custom conversions, Validators for bean validation, TypeRepresentationStrategyFactory for configuring the in graph type representation, IndexProviders for custom index handling (e.g. for multi-tenancy) or Entity-Instantiators (with their config) to have more control over the creation of entity instances and much more.