Reinstate Asciidoc docs.

Reinstate Asciidoc to retain functionality for downstream module documentation builds.

See #2876

Author: mp911de

pom.xml

@@ -357,6 +357,10 @@
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
+			<plugin>
+				<groupId>org.asciidoctor</groupId>
+				<artifactId>asciidoctor-maven-plugin</artifactId>
+			</plugin>
 			<plugin>
 				<groupId>io.spring.maven.antora</groupId>
 				<artifactId>antora-maven-plugin</artifactId>

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.