Restore src/main/asciidoc

This is necessary until the modules that still build using commons adoc
are migrated to Antora

Author: rwinch

src/main/asciidoc/auditing.adoc

@@ -0,0 +1,123 @@
+[[auditing]]
+= Auditing
+
+[[auditing.basics]]
+== Basics
+Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and when the change happened.To benefit from that functionality, you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface.
+Additionally, auditing has to be enabled either through Annotation configuration or XML configuration to register the required infrastructure components.
+Please refer to the store-specific section for configuration samples.
+
+[NOTE]
+====
+Applications that only track creation and modification dates are not required do make their entities implement <<auditing.auditor-aware, `AuditorAware`>>.
+====
+
+[[auditing.annotations]]
+=== Annotation-based Auditing Metadata
+We provide `@CreatedBy` and `@LastModifiedBy` to capture the user who created or modified the entity as well as `@CreatedDate` and `@LastModifiedDate` to capture when the change happened.
+
+.An audited entity
+====
+[source,java]
+----
+class Customer {
+
+  @CreatedBy
+  private User user;
+
+  @CreatedDate
+  private Instant createdDate;
+
+  // … further properties omitted
+}
+----
+====
+
+As you can see, the annotations can be applied selectively, depending on which information you want to capture.
+The annotations, indicating to capture when changes are made, can be used on properties of type JDK8 date and time types, `long`, `Long`, and legacy Java `Date` and `Calendar`.
+
+Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snippet below.
+
+.Audit metadata in embedded entity
+====
+[source,java]
+----
+class Customer {
+
+  private AuditMetadata auditingMetadata;
+
+  // … further properties omitted
+}
+
+class AuditMetadata {
+
+  @CreatedBy
+  private User user;
+
+  @CreatedDate
+  private Instant createdDate;
+
+}
+----
+====
+
+[[auditing.interfaces]]
+=== Interface-based Auditing Metadata
+In case you do not want to use annotations to define auditing metadata, you can let your domain class implement the `Auditable` interface. It exposes setter methods for all of the auditing properties.
+
+[[auditing.auditor-aware]]
+=== `AuditorAware`
+
+In case you use either `@CreatedBy` or `@LastModifiedBy`, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an `AuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be.
+
+The following example shows an implementation of the interface that uses Spring Security's `Authentication` object:
+
+.Implementation of `AuditorAware` based on Spring Security
+====
+[source, java]
+----
+class SpringSecurityAuditorAware implements AuditorAware<User> {
+
+  @Override
+  public Optional<User> getCurrentAuditor() {
+
+    return Optional.ofNullable(SecurityContextHolder.getContext())
+            .map(SecurityContext::getAuthentication)
+            .filter(Authentication::isAuthenticated)
+            .map(Authentication::getPrincipal)
+            .map(User.class::cast);
+  }
+}
+----
+====
+
+The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere.
+
+[[auditing.reactive-auditor-aware]]
+=== `ReactiveAuditorAware`
+
+When using reactive infrastructure you might want to make use of contextual information to provide `@CreatedBy` or `@LastModifiedBy` information.
+We provide an `ReactiveAuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be.
+
+The following example shows an implementation of the interface that uses reactive Spring Security's `Authentication` object:
+
+.Implementation of `ReactiveAuditorAware` based on Spring Security
+====
+[source, java]
+----
+class SpringSecurityAuditorAware implements ReactiveAuditorAware<User> {
+
+  @Override
+  public Mono<User> getCurrentAuditor() {
+
+    return ReactiveSecurityContextHolder.getContext()
+                .map(SecurityContext::getAuthentication)
+                .filter(Authentication::isAuthenticated)
+                .map(Authentication::getPrincipal)
+                .map(User.class::cast);
+  }
+}
+----
+====
+
+The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere.

src/main/asciidoc/custom-conversions.adoc

@@ -0,0 +1,41 @@
+The following example of a Spring `Converter` implementation converts from a `String` to a custom `Email` value object:
+
+[source,java,subs="verbatim,attributes"]
+----
+@ReadingConverter
+public class EmailReadConverter implements Converter<String, Email> {
+
+  public Email convert(String source) {
+    return Email.valueOf(source);
+  }
+}
+----
+
+If you write a `Converter` whose source and target type are native types, we cannot determine whether we should consider it as a reading or a writing converter.
+Registering the converter instance as both might lead to unwanted results.
+For example, a `Converter<String, Long>` is ambiguous, although it probably does not make sense to try to convert all `String` instances into `Long` instances when writing.
+To let you force the infrastructure to register a converter for only one way, we provide `@ReadingConverter` and `@WritingConverter` annotations to be used in the converter implementation.
+
+Converters are subject to explicit registration as instances are not picked up from a classpath or container scan to avoid unwanted registration with a conversion service and the side effects resulting from such a registration. Converters are registered with `CustomConversions` as the central facility that allows registration and querying for registered converters based on source- and target type.
+
+`CustomConversions` ships with a pre-defined set of converter registrations:
+
+* JSR-310 Converters for conversion between `java.time`, `java.util.Date` and `String` types.
+
+NOTE: Default converters for local temporal types (e.g. `LocalDateTime` to `java.util.Date`) rely on system-default timezone settings to convert between those types. You can override the default converter, by registering your own converter.
+
+[[customconversions.converter-disambiguation]]
+== Converter Disambiguation
+
+Generally, we inspect the `Converter` implementations for the source and target types they convert from and to.
+Depending on whether one of those is a type the underlying data access API can handle natively, we register the converter instance as a reading or a writing converter.
+The following examples show a writing-  and a read converter (note the difference is in the order of the qualifiers on `Converter`):
+
+[source,java]
+----
+// Write converter as only the target type is one that can be handled natively
+class MyConverter implements Converter<Person, String> { … }
+
+// Read converter as only the source type is one that can be handled natively
+class MyConverter implements Converter<String, Person> { … }
+----

src/main/asciidoc/dependencies.adoc

@@ -0,0 +1,61 @@
+[[dependencies]]
+= Dependencies
+
+Due to the different inception dates of individual Spring Data modules, most of them carry different major and minor version numbers. The easiest way to find compatible ones is to rely on the Spring Data Release Train BOM that we ship with the compatible versions defined. In a Maven project, you would declare this dependency in the `<dependencyManagement />` section of your POM as follows:
+
+.Using the Spring Data release train BOM
+====
+[source, xml, subs="+attributes"]
+----
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.data</groupId>
+      <artifactId>spring-data-bom</artifactId>
+      <version>{releasetrainVersion}</version>
+      <scope>import</scope>
+      <type>pom</type>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+----
+====
+
+[[dependencies.train-names]]
+[[dependencies.train-version]]
+The current release train version is `{releasetrainVersion}`. The train version uses https://calver.org/[calver] with the pattern `YYYY.MINOR.MICRO`.
+The version name follows `${calver}` for GA releases and service releases and the following pattern for all other versions: `${calver}-${modifier}`, where `modifier` can be one of the following:
+
+* `SNAPSHOT`: Current snapshots
+* `M1`, `M2`, and so on: Milestones
+* `RC1`, `RC2`, and so on: Release candidates
+
+You can find a working example of using the BOMs in our https://github.com/spring-projects/spring-data-examples/tree/main/bom[Spring Data examples repository]. With that in place, you can declare the Spring Data modules you would like to use without a version in the `<dependencies />` block, as follows:
+
+.Declaring a dependency to a Spring Data module
+====
+[source, xml]
+----
+<dependencies>
+  <dependency>
+    <groupId>org.springframework.data</groupId>
+    <artifactId>spring-data-jpa</artifactId>
+  </dependency>
+<dependencies>
+----
+====
+
+[[dependencies.spring-boot]]
+== Dependency Management with Spring Boot
+
+Spring Boot selects a recent version of the Spring Data modules for you. If you still want to upgrade to a newer version,
+set the `spring-data-bom.version` property to the <<dependencies.train-version,train version and iteration>>
+you would like to use.
+
+See Spring Boot's https://docs.spring.io/spring-boot/docs/current/reference/html/dependency-versions.html#appendix.dependency-versions.properties[documentation]
+(search for "Spring Data Bom") for more details.
+
+[[dependencies.spring-framework]]
+== Spring Framework
+
+The current version of Spring Data modules require Spring Framework {springVersion} or better. The modules might also work with an older bugfix version of that minor version. However, using the most recent version within that generation is highly recommended.

src/main/asciidoc/entity-callbacks.adoc

@@ -0,0 +1,163 @@
+[[entity-callbacks]]
+= Entity Callbacks
+
+The Spring Data infrastructure provides hooks for modifying an entity before and after certain methods are invoked.
+Those so called `EntityCallback` instances provide a convenient way to check and potentially modify an entity in a callback fashioned style. +
+An `EntityCallback` looks pretty much like a specialized `ApplicationListener`.
+Some Spring Data modules publish store specific events (such as `BeforeSaveEvent`) that allow modifying the given entity. In some cases, such as when working with immutable types, these events can cause trouble.
+Also, event publishing relies on `ApplicationEventMulticaster`. If configuring that with an asynchronous `TaskExecutor` it can lead to unpredictable outcomes, as event processing can be forked onto a Thread.
+
+Entity callbacks provide integration points with both synchronous and reactive APIs to guarantee in-order execution at well-defined checkpoints within the processing chain, returning a potentially modified entity or an reactive wrapper type.
+
+Entity callbacks are typically separated by API type. This separation means that a synchronous API considers only synchronous entity callbacks and a reactive implementation considers only reactive entity callbacks.
+
+[NOTE]
+====
+The Entity Callback API has been introduced with Spring Data Commons 2.2. It is the recommended way of applying entity modifications.
+Existing store specific `ApplicationEvents` are still published *before* the invoking potentially registered `EntityCallback` instances.
+====
+
+[[entity-callbacks.implement]]
+== Implementing Entity Callbacks
+
+An `EntityCallback` is directly associated with its domain type through its generic type argument.
+Each Spring Data module typically ships with a set of predefined `EntityCallback` interfaces covering the entity lifecycle.
+
+.Anatomy of an `EntityCallback`
+====
+[source,java]
+----
+@FunctionalInterface
+public interface BeforeSaveCallback<T> extends EntityCallback<T> {
+
+	/**
+	 * Entity callback method invoked before a domain object is saved.
+	 * Can return either the same or a modified instance.
+	 *
+	 * @return the domain object to be persisted.
+	 */
+	T onBeforeSave(T entity <2>, String collection <3>); <1>
+}
+----
+<1> `BeforeSaveCallback` specific method to be called before an entity is saved. Returns a potentially modifed instance.
+<2> The entity right before persisting.
+<3> A number of store specific arguments like the _collection_ the entity is persisted to.
+====
+
+.Anatomy of a reactive `EntityCallback`
+====
+[source,java]
+----
+@FunctionalInterface
+public interface ReactiveBeforeSaveCallback<T> extends EntityCallback<T> {
+
+	/**
+	 * Entity callback method invoked on subscription, before a domain object is saved.
+	 * The returned Publisher can emit either the same or a modified instance.
+	 *
+	 * @return Publisher emitting the domain object to be persisted.
+	 */
+	Publisher<T> onBeforeSave(T entity <2>, String collection <3>); <1>
+}
+----
+<1> `BeforeSaveCallback` specific method to be called on subscription, before an entity is saved. Emits a potentially modifed instance.
+<2> The entity right before persisting.
+<3> A number of store specific arguments like the _collection_ the entity is persisted to.
+====
+
+NOTE: Optional entity callback parameters are defined by the implementing Spring Data module and inferred from call site of `EntityCallback.callback()`.
+
+Implement the interface suiting your application needs like shown in the example below:
+
+.Example `BeforeSaveCallback`
+====
+[source,java]
+----
+class DefaultingEntityCallback implements BeforeSaveCallback<Person>, Ordered {      <2>
+
+	@Override
+	public Object onBeforeSave(Person entity, String collection) {                   <1>
+
+		if(collection == "user") {
+		    return // ...
+		}
+
+		return // ...
+	}
+
+	@Override
+	public int getOrder() {
+		return 100;                                                                  <2>
+	}
+}
+----
+<1> Callback implementation according to your requirements.
+<2> Potentially order the entity callback if multiple ones for the same domain type exist. Ordering follows lowest precedence.
+====
+
+[[entity-callbacks.register]]
+== Registering Entity Callbacks
+
+`EntityCallback` beans are picked up by the store specific implementations in case they are registered in the `ApplicationContext`.
+Most template APIs already implement `ApplicationContextAware` and therefore have access to the `ApplicationContext`
+
+The following example explains a collection of valid entity callback registrations:
+
+.Example `EntityCallback` Bean registration
+====
+[source,java]
+----
+@Order(1)                                                           <1>
+@Component
+class First implements BeforeSaveCallback<Person> {
+
+	@Override
+	public Person onBeforeSave(Person person) {
+		return // ...
+	}
+}
+
+@Component
+class DefaultingEntityCallback implements BeforeSaveCallback<Person>,
+                                                           Ordered { <2>
+
+	@Override
+	public Object onBeforeSave(Person entity, String collection) {
+		// ...
+	}
+
+	@Override
+	public int getOrder() {
+		return 100;                                                  <2>
+	}
+}
+
+@Configuration
+public class EntityCallbackConfiguration {
+
+    @Bean
+    BeforeSaveCallback<Person> unorderedLambdaReceiverCallback() {   <3>
+        return (BeforeSaveCallback<Person>) it -> // ...
+    }
+}
+
+@Component
+class UserCallbacks implements BeforeConvertCallback<User>,
+                                        BeforeSaveCallback<User> {   <4>
+
+	@Override
+	public Person onBeforeConvert(User user) {
+		return // ...
+	}
+
+	@Override
+	public Person onBeforeSave(User user) {
+		return // ...
+	}
+}
+----
+<1> `BeforeSaveCallback` receiving its order from the `@Order` annotation.
+<2> `BeforeSaveCallback` receiving its order via the `Ordered` interface implementation.
+<3> `BeforeSaveCallback` using a lambda expression. Unordered by default and invoked last. Note that callbacks implemented by a lambda expression do not expose typing information hence invoking these with a non-assignable entity affects the callback throughput. Use a `class` or `enum` to enable type filtering for the callback bean.
+<4> Combine multiple entity callback interfaces in a single implementation class.
+====