GH-2254 - Document BeforeBindCallbacks.

Closes #2254.

Author: michael-simons

src/main/asciidoc/faq/faq.adoc

@@ -553,6 +553,126 @@ public interface MyPersonRepository extends Neo4jRepository<Person, Long> {
     Therefore, you must specify an additional count query.
     All other restrictions from the second method apply.
 
+[[faq.path-mapping]]
+== Can I map named paths?
+
+A series of connected nodes and relationships is called a "path" in Neo4j.
+Cypher allows paths to be named using an identifer, as exemplified by:
+
+[source,cypher]
+----
+p = (a)-[*3..5]->(b)
+----
+
+or as in the infamous Movie graph, that includes the following path (in that case, one of the shortest path between two actors):
+
+[[bacon-distance]]
+[source,cypher]
+.The "Bacon" distance
+----
+MATCH p=shortestPath((bacon:Person {name:"Kevin Bacon"})-[*]-(meg:Person {name:"Meg Ryan"}))
+RETURN p
+----
+
+Which looks like this:
+
+image::bacon-distance.png[]
+
+We find 3 nodes labeled `Person` and 2 nodes labeled `Movie`. Both can be mapped with a custom queury.
+Assume there's a node entity for both `Person` and `Movie` as well as `Actor` taking care of the relationship:
+
+
+[source,java]
+."Standard" movie graph domain model
+----
+@Node
+public final class Person {
+
+	@Id @GeneratedValue
+	private final Long id;
+
+	private final String name;
+
+	private Integer born;
+
+	@Relationship("REVIEWED")
+	private List<Movie> reviewed = new ArrayList<>();
+}
+
+@RelationshipProperties
+public final class Actor {
+
+	@Id @GeneratedValue
+	private final Long id;
+
+	@TargetNode
+	private final Person person;
+
+	private final List<String> roles;
+}
+
+@Node
+public final class Movie {
+
+	@Id
+	private final String title;
+
+	@Property("tagline")
+	private final String description;
+
+	@Relationship(value = "ACTED_IN", direction = Direction.INCOMING)
+	private final List<Actor> actors;
+}
+----
+
+When using a query as shown in <<bacon-distance>> for a domain class of type `Person` like this
+
+[source,java]
+----
+interface PeopleRepository extends Neo4jRepository<Person, Long> {
+    @Query(""
+        + "MATCH p=shortestPath((bacon:Person {name: $person1})-[*]-(meg:Person {name: $person2}))\n"
+        + "RETURN p"
+    )
+    List<Person> findAllOnShortestPathBetween(@Param("person1") String person1, @Param("person2") String person2);
+}
+----
+
+it will retrieve all people from the path and map them.
+If there are relationship types on the path like `REVIEWED` that are also present on the domain, these
+will be filled accordingly from the path.
+
+WARNING: Take special care when you use nodes hydrated from a path based query to save data.
+If not all relationships are hydrated, data will be lost.
+
+The other way round works as well. The same query can be used with the `Movie` entity.
+It then will only populate movies.
+The following listing shows how todo this as well as how the query can be enriched with additional data
+not found on the path. That data is used to correctly populate the missing relationships (in that case, all the actors)
+
+[source,java]
+----
+interface MovieRepository extends Neo4jRepository<Movie, String> {
+
+    @Query(""
+        + "MATCH p=shortestPath(\n"
+        + "(bacon:Person {name: $person1})-[*]-(meg:Person {name: $person2}))\n"
+        + "WITH p, [n IN nodes(p) WHERE n:Movie] AS x\n"
+        + "UNWIND x AS m\n"
+        + "MATCH (m) <-[r:DIRECTED]-(d:Person)\n"
+        + "RETURN p, collect(r), collect(d)"
+    )
+    List<Movie> findAllOnShortestPathBetween(@Param("person1") String person1, @Param("person2") String person2);
+}
+----
+
+The query returns the path plus all relationships and related nodes collected so that the movie entities are fully hydrated.
+
+The path mapping works for single paths as well for multiple records of paths (which are returned by the `allShortestPath` function.)
+
+TIP: Named paths can be used efficiently to populate and return more than just a root node, see <<custom-query.paths>>.
+
+
 [[faq.custom-queries-and-custom-mappings]]
 == Is `@Query` the only way to use custom queries?
 
@@ -718,7 +838,7 @@ and one implementation. The implementation would than have had all three abstrac
 All of this applies of course to reactive repositories as well.
 They would work with the `ReactiveNeo4jTemplate` and `ReactiveNeo4jClient` and the reactive session provided by the driver.
 
-If you have recuring methods for all repositories, you could swap out the default repository implementation.
+If you have recurring methods for all repositories, you could swap out the default repository implementation.
 
 [[faq.custom-base-repositories]]
 == How do I use custom Spring Data Neo4j base repositories?
@@ -752,6 +872,37 @@ Those are
 * `org.springframework.data.annotation.LastModifiedBy`
 * `org.springframework.data.annotation.LastModifiedDate`
 
+<<auditing>> gives you a general view how to use auditing in the bigger context of Spring Data Commons.
+The following listing presents every configuration option provided by Spring Data Neo4j:
+
+[source,java,indent=0,tabsize=4]
+.Enabling and configuring Neo4j auditing
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/imperative/AuditingIT.java[tags=faq.entities.auditing]
+----
+<.> Set to true if you want the modification data to be written during creating as well
+<.> Use this attribute to specify the name of the bean that provides the auditor (i.e. a user name)
+<.> Use this attribute to specify the name of a bean that provides the current date. In this case
+    a fixed date is used as the above configuration is part of our tests
+
+The reactive version is basically the same apart from the fact the auditor aware bean is of type `ReactiveAuditorAware`,
+so that the retrieval of an auditor is part of the reactive flow.
+
+In addition to those auditing mechanism you can add as many beans implementing `BeforeBindCallback<T>` or `ReactiveBeforeBindCallback<T>`
+to the context. These beans will be picked up by Spring Data Neo4j and called in order (in case they implement `Ordered` or
+are annotated with `@Order`) just before an entity is persisted.
+
+They can modify the entity or return a completely new one.
+The following example adds one callback to the context that changes one attribute before the entity is persisted:
+
+[source,java,indent=0,tabsize=4]
+.Modifying entities before save
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/imperative/CallbacksIT.java[tags=faq.entities.auditing.callbacks]
+----
+
+No additional configuration is required.
+
 [[faq.find-by-example]]
 == How do I use "Find by example"?
 
@@ -779,125 +930,6 @@ movieExample = Example.of(
 movies = this.movieRepository.findAll(movieExample);
 ----
 
-[[faq.path-mapping]]
-== Can I map named paths?
-
-A series of connected nodes and relationships is called a "path" in Neo4j.
-Cypher allows paths to be named using an identifer, as exemplified by:
-
-[source,cypher]
-----
-p = (a)-[*3..5]->(b)
-----
-
-or as in the infamous Movie graph, that includes the following path (in that case, one of the shortest path between two actors):
-
-[[bacon-distance]]
-[source,cypher]
-.The "Bacon" distance
-----
-MATCH p=shortestPath((bacon:Person {name:"Kevin Bacon"})-[*]-(meg:Person {name:"Meg Ryan"}))
-RETURN p
-----
-
-Which looks like this:
-
-image::bacon-distance.png[]
-
-We find 3 nodes labeled `Person` and 2 nodes labeled `Movie`. Both can be mapped with a custom queury.
-Assume there's a node entity for both `Person` and `Movie` as well as `Actor` taking care of the relationship:
-
-
-[source,java]
-."Standard" movie graph domain model
-----
-@Node
-public final class Person {
-
-	@Id @GeneratedValue
-	private final Long id;
-
-	private final String name;
-
-	private Integer born;
-
-	@Relationship("REVIEWED")
-	private List<Movie> reviewed = new ArrayList<>();
-}
-
-@RelationshipProperties
-public final class Actor {
-
-	@Id @GeneratedValue
-	private final Long id;
-
-	@TargetNode
-	private final Person person;
-
-	private final List<String> roles;
-}
-
-@Node
-public final class Movie {
-
-	@Id
-	private final String title;
-
-	@Property("tagline")
-	private final String description;
-
-	@Relationship(value = "ACTED_IN", direction = Direction.INCOMING)
-	private final List<Actor> actors;
-}
-----
-
-When using a query as shown in <<bacon-distance>> for a domain class of type `Person` like this
-
-[source,java]
-----
-interface PeopleRepository extends Neo4jRepository<Person, Long> {
-    @Query(""
-        + "MATCH p=shortestPath((bacon:Person {name: $person1})-[*]-(meg:Person {name: $person2}))\n"
-        + "RETURN p"
-    )
-    List<Person> findAllOnShortestPathBetween(@Param("person1") String person1, @Param("person2") String person2);
-}
-----
-
-it will retrieve all people from the path and map them.
-If there are relationship types on the path like `REVIEWED` that are also present on the domain, these
-will be filled accordingly from the path.
-
-WARNING: Take special care when you use nodes hydrated from a path based query to save data.
-         If not all relationships are hydrated, data will be lost.
-
-The other way round works as well. The same query can be used with the `Movie` entity.
-It then will only populate movies.
-The following listing shows how todo this as well as how the query can be enriched with additional data
-not found on the path. That data is used to correctly populate the missing relationships (in that case, all the actors)
-
-[source,java]
-----
-interface MovieRepository extends Neo4jRepository<Movie, String> {
-
-    @Query(""
-        + "MATCH p=shortestPath(\n"
-        + "(bacon:Person {name: $person1})-[*]-(meg:Person {name: $person2}))\n"
-        + "WITH p, [n IN nodes(p) WHERE n:Movie] AS x\n"
-        + "UNWIND x AS m\n"
-        + "MATCH (m) <-[r:DIRECTED]-(d:Person)\n"
-        + "RETURN p, collect(r), collect(d)"
-    )
-    List<Movie> findAllOnShortestPathBetween(@Param("person1") String person1, @Param("person2") String person2);
-}
-----
-
-The query returns the path plus all relationships and related nodes collected so that the movie entities are fully hydrated.
-
-The path mapping works for single paths as well for multiple records of paths (which are returned by the `allShortestPath` function.)
-
-TIP: Named paths can be used efficiently to populate and return more than just a root node, see <<custom-query.paths>>.
-
 [[faq.spring-boot.sdn]]
 == Do I need Spring Boot to use Spring Data Neo4j?
 

src/test/java/org/springframework/data/neo4j/integration/imperative/AuditingIT.java

@@ -24,10 +24,14 @@
 import org.junit.jupiter.api.Test;
 import org.neo4j.driver.Driver;
 import org.springframework.beans.factory.annotation.Autowired;
+// tag::faq.entities.auditing[]
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
 import org.springframework.data.auditing.DateTimeProvider;
 import org.springframework.data.domain.AuditorAware;
+
+// end::faq.entities.auditing[]
 import org.springframework.data.neo4j.config.AbstractNeo4jConfig;
 import org.springframework.data.neo4j.config.EnableNeo4jAuditing;
 import org.springframework.data.neo4j.core.DatabaseSelectionProvider;
@@ -127,32 +131,21 @@ interface ImmutableEntityWithGeneratedIdRepository
 			extends Neo4jRepository<ImmutableAuditableThingWithGeneratedId, String> {}
 
 	@Configuration
+	@Import(AuditingConfig.class)
 	@EnableTransactionManagement
 	@EnableNeo4jRepositories(considerNestedRepositories = true)
-	@EnableNeo4jAuditing(modifyOnCreate = false, auditorAwareRef = "auditorProvider",
-			dateTimeProviderRef = "fixedDateTimeProvider")
 	static class Config extends AbstractNeo4jConfig {
 
 		@Bean
 		public Driver driver() {
 			return neo4jConnectionSupport.getDriver();
 		}
 
-		@Bean
-		public AuditorAware<String> auditorProvider() {
-			return () -> Optional.of("A user");
-		}
-
 		@Override
 		protected Collection<String> getMappingBasePackages() {
 			return Collections.singleton(ImmutableAuditableThing.class.getPackage().getName());
 		}
 
-		@Bean
-		public DateTimeProvider fixedDateTimeProvider() {
-			return () -> Optional.of(DEFAULT_CREATION_AND_MODIFICATION_DATE);
-		}
-
 		@Bean
 		public BookmarkCapture bookmarkCapture() {
 			return new BookmarkCapture();
@@ -166,3 +159,24 @@ public PlatformTransactionManager transactionManager(Driver driver, DatabaseSele
 		}
 	}
 }
+
+// tag::faq.entities.auditing[]
+@Configuration
+@EnableNeo4jAuditing(
+		modifyOnCreate = false, // <.>
+		auditorAwareRef = "auditorProvider", // <.>
+		dateTimeProviderRef = "fixedDateTimeProvider" // <.>
+)
+class AuditingConfig {
+
+	@Bean
+	public AuditorAware<String> auditorProvider() {
+		return () -> Optional.of("A user");
+	}
+
+	@Bean
+	public DateTimeProvider fixedDateTimeProvider() {
+		return () -> Optional.of(AuditingITBase.DEFAULT_CREATION_AND_MODIFICATION_DATE);
+	}
+}
+// end::faq.entities.auditing[]