<commit_before>[[reference_setup]]
= Getting started

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 and 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 http://github.com/neo4j-examples[Spring Data Neo4j examples].

Spring Data Neo4j projects can be built using Maven, Gradle or Ant/Ivy.

== Dependencies for Spring Data Neo4j

.Maven dependencies for Spring Data Neo4j
[source,xml]
----
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-neo4j</artifactId>
    <version>{version}</version>
</dependency>
----

== Spring configuration

Users of Spring Data Neo4j 4 can current only configure their applications using Java-based bean configuration.
Support for XML namespace configuration is expected to be available in later versions.

=== Java-based bean configuration

In order to configure Spring Data Neo4j with Java-based bean config, your Spring context must extend the core `Neo4jConfiguration` class that comes with Spring Data Neo4j. 
The example below shows how this can be done.

NOTE:   You will need to override the `neo4jServer()`, `getSessionFactory()` and `getSession()` bean definitions to provide
the required context for your own application. This is explained in more detail below.

.Pure Java Configuration
[source,java]
----
@Configuration
@EnableNeo4jRepositories(basePackages = "org.neo4j.example.repository")
@EnableTransactionManagement
public class MyConfiguration extends Neo4jConfiguration {

    @Bean
    public Neo4jServer neo4jServer() {
        return new RemoteServer("http://localhost:7474");
    }

    @Bean
    public SessionFactory getSessionFactory() {
        // with domain entity base package(s)
        return new SessionFactory("org.neo4j.example.domain");
    }

    // needed for session in view in web-applications
    @Bean
    @Scope(value = "session", proxyMode = ScopedProxyMode.TARGET_CLASS)
    public Session getSession() throws Exception {
        return super.getSession();
    }

}
----

=== Neo4jServer Bean

The `Neo4jServer` interface simply provides a URL with which to access the database.  
The default implementations are `RemoteServer` and `InProcessServer` (for testing).

As the name implies, `RemoteServer` is used to provide the URL of a remote Neo4j server.  
This will be the most typical use case for deployed applications.  
As the above example shows, you simply construct a new instance with the URL of the server that you want to use.

`InProcessServer` is useful for test and development environments, but is not recommended for production use.  
This implementation will start a new instance of `CommunityNeoServer` running on an available local port and return the URL needed to connect to it. 
It also registers a shutdown hook so that the underlying Neo4j server exits cleanly when the JVM shuts down, via _Control+C_, for example.
To use the `InProcessServer` in your tests, you will need to add the following dependencies``:

.Maven dependencies for Spring Data Neo4j Test classes
[source,xml]
----

        <dependency>
            <groupId>org.springframework.data</groupId>
            <artifactId>spring-data-neo4j</artifactId>
            <version>${sdn.version}</version>
            <type>test-jar</type>
        </dependency>

        <dependency>
            <groupId>org.neo4j</groupId>
            <artifactId>neo4j-kernel</artifactId>
            <version>${neo4j.version}</version>
            <type>test-jar</type>
        </dependency>

        <dependency>
            <groupId>org.neo4j.app</groupId>
            <artifactId>neo4j-server</artifactId>
            <version>${neo4j.version}</version>
            <type>test-jar</type>
        </dependency>
----

=== SessionFactory Bean

The `SessionFactory` is needed by SDN to create instances of `org.neo4j.ogm.session.Session` as required.  
This also sets up the object-graph mapping metadata when constructed, which is then used across all `Session` objects that it creates.  
As seen in the above example, the packages to scan for domain object metadata should be provided to the `SessionFactory` constructor.

Note that the session factory should typically be application-scoped.
While you can use a narrower scope for this if you like, there is typically no advantage in doing so.

=== Session Bean

A `Session` is used to drive the object-graph mapping framework on which Spring Data Neo4j is based.  
All repository implementations and `Neo4jTemplate` are driven by the `Session`, and you can also auto-wire it into your Spring beans and code against it directly if you wish.

The life cycle of a `Session` is important to consider because it keeps track of the changes that have been made to entities and their relationships.  
The reason it does this is so that only entities and relationships that have changed get persisted on save, which is particularly efficient when working with large graphs.  <commit_msg>DATAGRAPH-692 - Document the new test dependencies.<commit_after>[[reference_setup]]
= Getting started

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 and 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 http://github.com/neo4j-examples[Spring Data Neo4j examples].

Spring Data Neo4j projects can be built using Maven, Gradle or Ant/Ivy.

== Dependencies for Spring Data Neo4j

.Maven dependencies for Spring Data Neo4j
[source,xml]
----
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-neo4j</artifactId>
    <version>{version}</version>
</dependency>
----

== Spring configuration

Users of Spring Data Neo4j 4 can current only configure their applications using Java-based bean configuration.
Support for XML namespace configuration is expected to be available in later versions.

=== Java-based bean configuration

In order to configure Spring Data Neo4j with Java-based bean config, your Spring context must extend the core `Neo4jConfiguration` class that comes with Spring Data Neo4j. 
The example below shows how this can be done.

NOTE:   You will need to override the `neo4jServer()`, `getSessionFactory()` and `getSession()` bean definitions to provide
the required context for your own application. This is explained in more detail below.

.Pure Java Configuration
[source,java]
----
@Configuration
@EnableNeo4jRepositories(basePackages = "org.neo4j.example.repository")
@EnableTransactionManagement
public class MyConfiguration extends Neo4jConfiguration {

    @Bean
    public Neo4jServer neo4jServer() {
        return new RemoteServer("http://localhost:7474");
    }

    @Bean
    public SessionFactory getSessionFactory() {
        // with domain entity base package(s)
        return new SessionFactory("org.neo4j.example.domain");
    }

    // needed for session in view in web-applications
    @Bean
    @Scope(value = "session", proxyMode = ScopedProxyMode.TARGET_CLASS)
    public Session getSession() throws Exception {
        return super.getSession();
    }

}
----

=== Neo4jServer Bean

The `Neo4jServer` interface simply provides a URL with which to access the database.  
The default implementations are `RemoteServer` and `InProcessServer` (for testing).

As the name implies, `RemoteServer` is used to provide the URL of a remote Neo4j server.  
This will be the most typical use case for deployed applications.  
As the above example shows, you simply construct a new instance with the URL of the server that you want to use.

`InProcessServer` is useful for test and development environments, but is not recommended for production use.  
This implementation will start a new instance of `CommunityNeoServer` running on an available local port and return the URL needed to connect to it. 
It also registers a shutdown hook so that the underlying Neo4j server exits cleanly when the JVM shuts down, via _Control+C_, for example.
To use the `InProcessServer` in your tests, you will need to add the following dependencies``:

.Maven dependencies for Spring Data Neo4j Test classes
[source,xml]
----

        <dependency>
            <groupId>org.springframework.data</groupId>
            <artifactId>spring-data-neo4j</artifactId>
            <version>${sdn.version}</version>
            <type>test-jar</type>
        </dependency>

       <dependency>
          <groupId>org.neo4j</groupId>
          <artifactId>neo4j-ogm</artifactId>
          <version>${neo4j-ogm.version}</version>
          <type>test-jar</type>
          <scope>test</scope>
      </dependency>

      <dependency>
          <groupId>org.neo4j.test</groupId>
          <artifactId>neo4j-harness</artifactId>
          <version>${neo4j.version}</version>
          <scope>test</scope>
      </dependency>
----

=== SessionFactory Bean

The `SessionFactory` is needed by SDN to create instances of `org.neo4j.ogm.session.Session` as required.  
This also sets up the object-graph mapping metadata when constructed, which is then used across all `Session` objects that it creates.  
As seen in the above example, the packages to scan for domain object metadata should be provided to the `SessionFactory` constructor.

Note that the session factory should typically be application-scoped.
While you can use a narrower scope for this if you like, there is typically no advantage in doing so.

=== Session Bean

A `Session` is used to drive the object-graph mapping framework on which Spring Data Neo4j is based.  
All repository implementations and `Neo4jTemplate` are driven by the `Session`, and you can also auto-wire it into your Spring beans and code against it directly if you wish.

The life cycle of a `Session` is important to consider because it keeps track of the changes that have been made to entities and their relationships.  
The reason it does this is so that only entities and relationships that have changed get persisted on save, which is particularly efficient when working with large graphs.  
{'fraction_non_alphanumeric': 0.0708253358925144, 'fraction_numerical': 0.007965451055662189, 'mean_word_length': 3.795674183156926, 'pattern_counts': {'":': 0, '<': 81, '<?xml version=': 0, '>': 81, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5202075', 'n_tokens_mistral': 2739, 'n_tokens_neox': 2585, 'n_words': 1222}