/src/main/asciidoc/migration.adoc

[[migration]]
[appendix]
= Migration Guide

[[migration.5-0]]
== Migrating from 4.2 -> 5.0/5.1

* Base class for repositories `GraphRepository` has been renamed `Neo4jRepository` and parameter types change from `<T>` to `<T, ID>`.
* All Repository methods can return `Streams`.
* The repository method naming scheme has changed for SD commons 2.0 as part of https://jira.spring.io/browse/DATACMNS-944[DATACMNS-944].
** for example, `findOne` repository methods are renamed `findById` and now return `Optional<T>`.
** please check the JavaDoc of `org.springframework.data.repository.CrudRepository`
* Paged custom queries no longer accept queries without `countQuery` attribute.
* The keywords `Between` and `IsBetween` in query methods now include the given limits in the query.
  Use a combination of `GreaterThan`/`isGreaterThan` and `LessThan`/`isLessThan` (e.g. `isGreaterThanLowerLimitAndIsLessThanUpperLimit`) to keep the exclusive behavior.
* Id handling : `Long` native ids are not mandatory anymore. See <<reference:annotating-entities:graph-id, GraphId field>>.
* Primary indexes are now deprecated and replaced by `@Id` See <<reference:annotating-entities:entity-identifier, Entity identifier>>.
* Annotations on accessors are no longer valid. See <<reference:annotating-entities, Annotating entities>>.
* Loading with depth `-1` calls have to be reviewed (please see the Neo4j-OGM migration guide under _Migration from 2.1 to 3.0 / Performance and unlimited load depth_).
* The `ogm.properties` file and environment variable have been removed. 
You have to explicitly provide the configuration file now or configure the driver programmatically. 
See <<reference:configuration:driver, the configuration section>>.
* The driver class name in the configuration is now inferred from connection URL.
* Java 8 dates are now better supported ; the use of `java.util.Date` or converters is not required anymore. You may want to switch to more fine grained date types like `Instant`. See <<reference:type-conversion:built-in, conversions>>.
* The query filters are now immutable. See <<reference:filters, Filters>>.

[[migration.4-2]]
== Migrating from 4.0/4.1 -> 4.2

Spring Data Neo4j 4.2 significantly reduces complexity of configuration for application developers.
There is no longer a need to extend from `Neo4jConfiguration` or define a `Session` bean. Configuration for various types
of applications are described <<reference.getting_started.spring-configuration,here>>

1. Remove any subclassing of `Neo4jConfiguration`
2. Define the `sessionFactory` bean with an instance of `SessionFactory` and the `transactionManager` bean with an instance of `Neo4jTransactionManager`. Be sure to pass the `SessionFactory` into the constructor for the transaction manager.

[[migration.4-0]]
== Migrating from pre 4.0 -> 4.2

[[migration.4-0.packages]]
=== Package Changes

Because the Neo4j Object Graph Mapper can be used independently of Spring Data Neo4j, the core annotations have been
moved out of the spring framework packages:

`org.springframework.data.neo4j.annotation` -> `org.neo4j.ogm.annotation`

[NOTE]
====
The `@Query` and `@QueryResult` annotations are only supported in the Spring modules, and are not used by the core
mapping framework. These annotations have not changed.
====

[[migration.4-0.annotations]]
=== Annotation Changes

There have been some changes to the annotations that were used in previous versions of Spring Data Neo4j.
Wherever possible we have tried to maintain the previous annotations verbatim, but in a few cases this has not been
possible, usually for technical reasons but sometimes for aesthetic ones. Our goal has been to minimise the number
of annotations you need to use as well as trying to make them more self-explanatory. The following annotations
have been changed.

|===
h| Old h| New
m| @RelatedTo m| @Relationship
m| @RelatedToVia m| @Relationship
m| @GraphProperty m| @Property
m| @MapResult m| @QueryResult
m| @ResultColumn m| @Property
m| Relationship Direction.BOTH m| Relationship.UNDIRECTED
|===

[[migration.4-0.custom_converters]]
=== Custom Type Conversion
SDN provides automatic type conversion for the obvious candidates: byte[] and Byte[] arrays, Dates, BigDecimal and
BigInteger types. In order to define bespoke type conversions for particular entity attribute, you can annotate a
field or method with `@Convert` to specify your own implementation of `org.neo4j.ogm.typeconversion.AttributeConverter`.

You can find out more about type conversions here: <<reference_programming-model_conversion,Custom Converters>>

[[migration.4-0.date-format]]
=== Date Format Changes
The default Date converter is <<reference:type-conversion:built-in,@DateString>>.

SDN 3.x and earlier represented Dates as a String value consisting of the number of milliseconds since January 1, 1970, 00:00:00 GMT.

If you are upgrading to SDN 4.x from these versions and your application used the default, then you need to annotate your `Date`
properties with `@DateLong`.
Moreover, the property values in the graph need to be converted to numbers.

.Upgrade Date properties to numbers
[source,cypher]
----
MATCH (n:Foo) //All nodes which contain date properties to be migrated
WHERE NOT HAS(n.migrated)// Take the first 10k nodes that haven't been migrated yet
WITH n LIMIT 10000
SET n.dateProperty = toInt(n.dateProperty),n.migrated=1 //where dateProperty is the date with a String value to be migrated
RETURN count(n); //Run until the statement returns zero records
//Similar process to remove the migrated flag
----

However, if your application already represented Dates as  `@GraphProperty(propertyType = Long.class)` then simply changing this to
`@DateLong` is sufficient.

[[migration.4-0.indexing]]
=== Indexing

The best way to retrieve start nodes for traversals and queries is by using Neo4j's integrated index facilities.
SDN supports Index and Constraint management but differs in how it does this to previous versions.

[[migration.4-0.obsolete-annotations]]
=== Obsolete Annotations

The following annotations are no longer used, either because they are no longer needed, or cannot be supported via Cypher.

* @GraphTraversal
* @RelatedToVia
* @RelatedTo
* @TypeAlias
* @Fetch

[[migration.4-0.no-support]]
=== Features No Longer Supported

Some features of the previous annotations have been dropped.

Overriding @Property Types::
Support for overriding property types via arguments to @Property has been dropped. If your attribute requires
a non-default conversion to and from a database property, you can use a <<migration.4-0.custom_converters,Custom Converter>> instead.

@Relationship enforceTargetType::
In previous versions of Spring Data Neo4j, you would have to add an `enforceTargetType` attribute into every clashing
`@Relationship` annotation.  Thanks to changes in the underlying object-graph mapping mechanism, this is no longer
necessary.

.Clashing Relationship Types
[source,java]
----
@NodeEntity
class Person {
    @Relationship(type="OWNS")
    private Car car;

    @Relationship(type="OWNS")
    private Pet pet;
...
}
----

Cross-store Persistence::
Neo4j is dropping XA support and therefore SDN does not provide any capability for cross-store persistence

TypeRepresentationStrategy::
SDN 4 replaces the existing `TypeRepresentionStrategy` configuration with a straightforward convention based on simple class-names
or entities using `@NodeEntity(label=...)`


AspectJ Support::
Support for AspectJ-based persistence has been removed from SDN 4 as the write-and-read-through approach only works with an integrated, embedded database, not Neo4j server. The performance improvements in SDN 4 should make their use as a performance optimisation unnecessary anyway.


=== Deprecation of Neo4jTemplate

Users that rely on a direct interaction with the database should be using the Neo4j-OGM `Session` directly.
`Neo4jTemplate` has been kept to give upgrading users a better experience.

The `Neo4jTemplate` has been slimmed-down significantly for SDN 4. It contains the exact same methods as `Session`. In fact `Neo4jTemplate` is just a very thin wrapper with an ability to support SDN Exception Translation.
Many of the operations are no longer needed or can be expressed with a straightforward Cypher query.

If you do use `Neo4jTemplate`, then you should code against its `Neo4jOperations` interface instead of the template class.

The following table shows the `Neo4jTemplate` functions that have been retained for version 4 of Spring Data Neo4j.  In some cases the method names have changed but the same functionality is offered under the new version.

[cols="1,1,2"]
.Neo4j Template Method Migration
|===
|Old Method Name|New Method Name|Notes

|`findOne`
|`load`
|Overloaded to take optional depth parameter

|`findAll`
|`loadAll`
|Overloaded to take optional depth parameter, also now returns a `Collection` rather than a `Result`

|`query`
|`query`
|Return type changed from `Result` to be `Iterable`

|`save`
|`save`
|

|`delete`
|`delete`
|

|`count`
|`count`
|No longer defines generic type parameters

|`findByIndexedValue`
|`loadByProperty`
|Indexes are not supported natively, but you can index node properties in your database setup and use this method to find by them

|===

To achieve the old `template.fetch(entity)` equivalent behaviour, you should call one of the load methods specifying the fetch depth as a parameter.

It's also worth noting that `exec(GraphCallback)` and the `create...()` methods have been made obsolete by Cypher.
Instead, you should now issue a Cypher query to the new `execute` method to create the nodes or relationships that you need.

Dynamic labels, properties and relationship types are not supported as of this version, server extensions should be considered instead.

==== Built-In Query DSL Support
Previous versions of SDN allowed you to use a DSL to generate Cypher queries. There are many different DSL
libraries available and you're free to use which of these - or none - that you want. With Cypher changing on a regular
basis, avoiding a DSL implementation in SDN means less ongoing maintenance and less likelihood of your code
being incompatible with future versions of Neo4j.

==== Graph Traversal and Node/Relationship Manipulation
These features cannot be supported by Cypher and have therefore been dropped from `Neo4jTemplate`.


Please provide feedback on the new APIs of SDN 5 and the migration needs to spring-data-neo4j@neotechnology.com or via a https://jira.spring.io/browse/DATAGRAPH[JIRA issue]