Adds a new snippet for is-new-state-detection.

This is intended for inclusion by other modules.

Closes #2352.

Author: schauder

src/main/asciidoc/is-new-state-detection.adoc

@@ -0,0 +1,30 @@
+[[is-new-state-detection]]
+= Entity State Detection Strategies
+
+The following table describes the strategies that Spring Data offers for detecting whether an entity is new:
+
+.Options for detection whether an entity is new in Spring Data
+[options = "autowidth",cols="1,1"]
+|===
+|Id-Property inspection (the default)
+|By default, Spring Data inspects the version property of the given entity.
+If the identifier property is `null` or `0` in case of primitive types, then the entity is assumed to be new.
+Otherwise, it is assumed to not be new.
+
+|Version-Property inspection
+|If a property annotated with `@Version` is present and `null`, or in case of a version property of primitive type `0` the entity is considered new.
+If the version property is present but has a different value, the entity is considered to not be new.
+If no version property is present Spring Data falls back to inspection of the Id-Property.
+
+|Implementing `Persistable`
+|If an entity implements `Persistable`, Spring Data delegates the new detection to the `isNew(…)` method of the entity.
+See the link:https://docs.spring.io/spring-data/data-commons/docs/current/api/index.html?org/springframework/data/domain/Persistable.html[Javadoc] for details.
+
+_Note: Properties of `Persistable` will get detected and persisted if you use `AccessType.PROPERTY`.
+To avoid that, use `@Transient`._
+
+|Implementing `EntityInformation`
+|You can customize the `EntityInformation` abstraction used in the repository base implementation by creating a subclass of the module specific repository factory and overriding the `getEntityInformation(…)` method.
+You then have to register the custom implementation of module specific repository factory as a Spring bean.
+Note that this should rarely be necessary.
+|===