<commit_before>:numbered:
== Package changes
Because the Neo4j Object Graph Mapper can be used independently of the Spring wrappers, the core annotations have been
moved out of the spring framework packages:

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

The exception to this is the `@Query` which is not supported as an annotation in the core OGM.

== 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.

. `@RelatedTo` -> `@Relationship`
. `@RelatedToVia` -> `@Relationship`
. `@GraphProperty` -> `@Property`
. Relationship `Direction.BOTH` -> `Relationship.UNDIRECTED`

[[custom_converters]]
== Custom Type Conversion
SDN 4 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>>

== Obsolete annotations

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

. @GraphTraversal
. @RelatedToVia
. @RelatedTo
. @Index
. @TypeAlias
. @Fetch

== 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 <<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 and this now works just fine.

.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 4 does not provide any capability for cross-store persistence

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

Please refer to <<reference_programming_model_typerepresentationstrategy>> for more details.

=== AspectJ support dropped
Due to numerous problems reported by users in earlier versions of SDN, support for Aspect J based persistence has
been removed from SDN 4.


== Changes to Neo4jTemplate

We've had to do loadsa stuff to this coz it were doin' too much and didn't mek sense.

=== 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`.


TODO: these are the template methods we've **kept** for V4 - write them up properly

* findOne():T (renamed to load)
* findAll():Collection<T> (renamed to load, changed return type from Result)
* query():Iterable<T> (changed return type from Result)
* save()
* delete()


== Features not yet included in Milestone 1 but that are on the Roadmap

. Geospatial queries
. @QueryResult

:numbered!:<commit_msg>Completing list of methods kept as place holder documentation.<commit_after>:numbered:
== Package changes
Because the Neo4j Object Graph Mapper can be used independently of the Spring wrappers, the core annotations have been
moved out of the spring framework packages:

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

The exception to this is the `@Query` which is not supported as an annotation in the core OGM.

== 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.

. `@RelatedTo` -> `@Relationship`
. `@RelatedToVia` -> `@Relationship`
. `@GraphProperty` -> `@Property`
. Relationship `Direction.BOTH` -> `Relationship.UNDIRECTED`

[[custom_converters]]
== Custom Type Conversion
SDN 4 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>>

== Obsolete annotations

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

. @GraphTraversal
. @RelatedToVia
. @RelatedTo
. @Index
. @TypeAlias
. @Fetch

== 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 <<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 and this now works just fine.

.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 4 does not provide any capability for cross-store persistence

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

Please refer to <<reference_programming_model_typerepresentationstrategy>> for more details.

=== AspectJ support dropped
Due to numerous problems reported by users in earlier versions of SDN, support for Aspect J based persistence has
been removed from SDN 4.


== Changes to Neo4jTemplate

We've had to do loadsa stuff to this coz it were doin' too much and didn't mek sense.

=== 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`.


TODO: these are the template methods we've **kept** for V4 - write them up properly

* findOne():T (renamed to load)
* findAll():Collection<T> (renamed to load, changed return type from Result)
* findOne(...depth) (replaces fetch(entity))
* query():Iterable<T> (changed return type from Result)
* save()
* delete()
* count()
* isNodeEntity(class)
* isRelationshipEntity(class)
* (probably worth re-mentioning that findByIndexedValue is kind-of replaced by loadByProperty - it allows the same functional behaviour)

== Features not yet included in Milestone 1 but that are on the Roadmap

. Geospatial queries
. @QueryResult

:numbered!:
{'fraction_non_alphanumeric': 0.06725663716814159, 'fraction_numerical': 0.0035398230088495575, 'mean_word_length': 4.913015042511446, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, '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': '2772045', 'n_tokens_mistral': 2413, 'n_tokens_neox': 2271, 'n_words': 1173}