/src/main/asciidoc/migration.adoc
AsciiDoc | 227 lines | 169 code | 58 blank | 0 comment | 0 complexity | 767b310c8f72fac0642516e3dd27fc3f MD5 | raw file
Possible License(s): Apache-2.0
- [[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]