Reorganize antora asciidoc sources for easier reuse.

mp911de · mp911de · commit 6f981143ce14 · 2023-08-22T14:10:49.000+02:00
See #2912
diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc
@@ -11,9 +11,9 @@
 ** xref:repositories/custom-implementations.adoc[]
 ** xref:repositories/core-domain-events.adoc[]
 ** xref:repositories/core-extensions.adoc[]
-* xref:repositories-scrolling.adoc[]
-* xref:repositories-null-handling.adoc[]
-* xref:repository-projections.adoc[]
+** xref:repositories/scrolling.adoc[]
+** xref:repositories/null-handling.adoc[]
+** xref:repositories/projections.adoc[]
 * xref:query-by-example.adoc[]
 * xref:auditing.adoc[]
 * xref:custom-conversions.adoc[]
@@ -26,7 +26,7 @@
 ** xref:kotlin/extensions.adoc[]
 ** xref:kotlin/coroutines.adoc[]
 * Appendices
-** xref:repository-namespace-reference.adoc[]
-** xref:repository-populator-namespace-reference.adoc[]
-** xref:repository-query-keywords-reference.adoc[]
-** xref:repository-query-return-types-reference.adoc[]
+** xref:repositories/namespace-reference.adoc[]
+** xref:repositories/populator-namespace-reference.adoc[]
+** xref:repositories/query-keywords-reference.adoc[]
+** xref:repositories/query-return-types-reference.adoc[]
diff --git a/src/main/antora/modules/ROOT/pages/auditing.adoc b/src/main/antora/modules/ROOT/pages/auditing.adoc
@@ -9,7 +9,7 @@ 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 xref:auditing.adoc#auditing.auditor-aware[`AuditorAware`].
+Applications that only track creation and modification dates are not required do make their entities implement <<auditing.auditor-aware,`AuditorAware`>>.
 ====
 
 [[auditing.annotations]]
diff --git a/src/main/antora/modules/ROOT/pages/dependencies.adoc b/src/main/antora/modules/ROOT/pages/dependencies.adoc
@@ -45,7 +45,7 @@ You can find a working example of using the BOMs in our https://github.com/sprin
 == 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 xref:dependencies.adoc#dependencies.train-version[train version and iteration]
+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]
diff --git a/src/main/antora/modules/ROOT/pages/kotlin/null-safety.adoc b/src/main/antora/modules/ROOT/pages/kotlin/null-safety.adoc
@@ -9,7 +9,7 @@ Although Java does not let you express null safety in its type system, Spring Da
 By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null checks are relaxed.
 https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] and Spring nullability annotations provide null safety for the whole Spring Data API to Kotlin developers, with the advantage of dealing with `null` related issues at compile time.
 
-See xref:repositories-null-handling.adoc[Null Handling of Repository Methods] how null safety applies to Spring Data Repositories.
+See xref:repositories/null-handling.adoc[Null Handling of Repository Methods] how null safety applies to Spring Data Repositories.
 
 [TIP]
 ====
@@ -19,4 +19,4 @@ For Kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
 The `strict` value is required take Spring Data API null-safety into account. Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve, even between minor releases and that more checks may be added in the future.
 ====
 
-NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, but should be in an upcoming release.
+NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, but should be in an upcoming release.
diff --git a/src/main/antora/modules/ROOT/pages/repositories.adoc b/src/main/antora/modules/ROOT/pages/repositories.adoc
@@ -18,9 +18,9 @@ This chapter explains the core concepts and interfaces of Spring Data repositori
 The information in this chapter is pulled from the Spring Data Commons module.
 It uses the configuration and code samples for the Jakarta Persistence API (JPA) module.
 ifeval::[{include-xml-namespaces} != false]
-If you want to use XML configuration you should adapt the XML namespace declaration and the types to be extended to the equivalents of the particular module that you use. "`xref:repository-namespace-reference.adoc#repositories.namespace-reference[Namespace reference]`" covers XML configuration, which is supported across all Spring Data modules that support the repository API.
+If you want to use XML configuration you should adapt the XML namespace declaration and the types to be extended to the equivalents of the particular module that you use. "`xref:repositories/namespace-reference.adoc#repositories.namespace-reference[Namespace reference]`" covers XML configuration, which is supported across all Spring Data modules that support the repository API.
 endif::[]
-"`xref:repository-query-keywords-reference.adoc[Repository query keywords]`" covers the query method keywords supported by the repository abstraction in general.
+"`xref:repositories/query-keywords-reference.adoc[Repository query keywords]`" covers the query method keywords supported by the repository abstraction in general.
 For detailed information on the specific features of your module, see the chapter on that module of this document.
 ====
 
diff --git a/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc b/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc
@@ -281,7 +281,7 @@ Please refer to the store specific section for more details.
 [[core.web.binding]]
 === Web Databinding Support
 
-You can use Spring Data projections (described in xref:repository-projections.adoc[Projections]) to bind incoming request payloads by using either https://goessner.net/articles/JsonPath/[JSONPath] expressions (requires https://github.com/json-path/JsonPath[Jayway JsonPath]) or https://www.w3.org/TR/xpath-31/[XPath] expressions (requires https://xmlbeam.org/[XmlBeam]), as the following example shows:
+You can use Spring Data projections (described in xref:repositories/projections.adoc[Projections]) to bind incoming request payloads by using either https://goessner.net/articles/JsonPath/[JSONPath] expressions (requires https://github.com/json-path/JsonPath[Jayway JsonPath]) or https://www.w3.org/TR/xpath-31/[XPath] expressions (requires https://xmlbeam.org/[XmlBeam]), as the following example shows:
 
 .HTTP payload binding using JSONPath or XPath expressions
 [source,java]
@@ -305,7 +305,7 @@ The `lastname` XML lookup is performed on the top-level of the incoming document
 The JSON variant of that tries a top-level `lastname` first but also tries `lastname` nested in a `user` sub-document if the former does not return a value.
 That way, changes in the structure of the source document can be mitigated easily without having clients calling the exposed methods (usually a drawback of class-based payload binding).
 
-Nested projections are supported as described in xref:repository-projections.adoc[Projections].
+Nested projections are supported as described in xref:repositories/projections.adoc[Projections].
 If the method returns a complex, non-interface type, a Jackson `ObjectMapper` is used to map the final value.
 
 For Spring MVC, the necessary converters are registered automatically as soon as `@EnableSpringDataWebSupport` is active and the required dependencies are available on the classpath.
diff --git a/src/main/antora/modules/ROOT/pages/repositories/definition.adoc b/src/main/antora/modules/ROOT/pages/repositories/definition.adoc
@@ -66,8 +66,8 @@ In such cases, a repository definition must distinguish between persistence tech
 When it detects multiple repository factories on the class path, Spring Data enters strict repository configuration mode.
 Strict configuration uses details on the repository or the domain class to decide about Spring Data module binding for a repository definition:
 
-. If the repository definition xref:repositories/definition.adoc#repositories.multiple-modules.types[extends the module-specific repository], it is a valid candidate for the particular Spring Data module.
-. If the domain class is xref:repositories/definition.adoc#repositories.multiple-modules.annotations[annotated with the module-specific type annotation], it is a valid candidate for the particular Spring Data module.
+. If the repository definition <<repositories.multiple-modules.types,extends the module-specific repository>>, it is a valid candidate for the particular Spring Data module.
+. If the domain class is <<repositories.multiple-modules.annotations,annotated with the module-specific type annotation>>, it is a valid candidate for the particular Spring Data module.
 Spring Data modules accept either third-party annotations (such as JPA's `@Entity`) or provide their own annotations (such as `@Document` for Spring Data MongoDB and Spring Data Elasticsearch).
 
 The following example shows a repository that uses module-specific interfaces (JPA in this case):
@@ -149,7 +149,7 @@ One is intended for JPA and the other for MongoDB usage.
 Spring Data is no longer able to tell the repositories apart, which leads to undefined behavior.
 ====
 
-xref:repositories/definition.adoc#repositories.multiple-modules.types[Repository type details] and xref:repositories/definition.adoc#repositories.multiple-modules.annotations[distinguishing domain class annotations] are used for strict repository configuration to identify repository candidates for a particular Spring Data module.
+<<repositories.multiple-modules.types,Repository type details>> and <<repositories.multiple-modules.annotations,distinguishing domain class annotations>> are used for strict repository configuration to identify repository candidates for a particular Spring Data module.
 Using multiple persistence technology-specific annotations on the same domain type is possible and enables reuse of domain types across multiple persistence technologies.
 However, Spring Data can then no longer determine a unique module with which to bind the repository.
 
diff --git a/src/main/antora/modules/ROOT/pages/repositories/namespace-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/namespace-reference.adoc
diff --git a/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc b/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc
@@ -11,7 +11,7 @@ Besides that, Spring Data supports returning the following wrapper types on quer
 Alternatively, query methods can choose not to use a wrapper type at all.
 The absence of a query result is then indicated by returning `null`.
 Repository methods returning collections, collection alternatives, wrappers, and streams are guaranteed never to return `null` but rather the corresponding empty representation.
-See "`xref:repository-query-return-types-reference.adoc[Repository query return types]`" for details.
+See "`xref:repositories/query-return-types-reference.adoc[Repository query return types]`" for details.
 
 [[repositories.nullability.annotations]]
 == Nullability Annotations
diff --git a/src/main/antora/modules/ROOT/pages/repositories/populator-namespace-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/populator-namespace-reference.adoc
diff --git a/src/main/antora/modules/ROOT/pages/repositories/projections.adoc b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
@@ -179,7 +179,7 @@ interface NamesOnly {
 }
 ----
 
-Again, for more complex expressions, you should use a Spring bean and let the expression invoke a method, as described  xref:repository-projections.adoc#projections.interfaces.open.bean-reference[earlier].
+Again, for more complex expressions, you should use a Spring bean and let the expression invoke a method, as described  <<projections.interfaces.open.bean-reference,earlier>>.
 
 [[projections.interfaces.nullable-wrappers]]
 === Nullable Wrappers
diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc
diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc
@@ -66,9 +66,9 @@ interface PersonRepository extends Repository<Person, Long> {
 Parsing query method names is divided into subject and predicate.
 The first part (`find…By`, `exists…By`) defines the subject of the query, the second part forms the predicate.
 The introducing clause (subject) can contain further expressions.
-Any text between `find` (or other introducing keywords) and `By` is considered to be descriptive unless using one of the result-limiting keywords such as a `Distinct` to set a distinct flag on the query to be created or xref:repositories/query-methods-details.adoc#repositories.limit-query-result[`Top`/`First` to limit query results].
+Any text between `find` (or other introducing keywords) and `By` is considered to be descriptive unless using one of the result-limiting keywords such as a `Distinct` to set a distinct flag on the query to be created or <<repositories.limit-query-result,`Top`/`First` to limit query results>>.
 
-The appendix contains the xref:repository-query-keywords-reference.adoc#appendix.query.method.subject[full list of query method subject keywords] and xref:repository-query-keywords-reference.adoc#appendix.query.method.predicate[query method predicate keywords including sorting and letter-casing modifiers].
+The appendix contains the xref:repositories/query-keywords-reference.adoc#appendix.query.method.subject[full list of query method subject keywords] and xref:repositories/query-keywords-reference.adoc#appendix.query.method.predicate[query method predicate keywords including sorting and letter-casing modifiers].
 However, the first `By` acts as a delimiter to indicate the start of the actual criteria predicate.
 At a very basic level, you can define conditions on entity properties and concatenate them with `And` and `Or`.
 
@@ -126,7 +126,7 @@ Because we treat the underscore character as a reserved character, we strongly a
 
 Query methods that return multiple results can use standard Java `Iterable`, `List`, and `Set`.
 Beyond that, we support returning Spring Data's `Streamable`, a custom extension of `Iterable`, as well as collection types provided by https://www.vavr.io/[Vavr].
-Refer to the appendix explaining all possible xref:repository-query-return-types-reference.adoc#appendix.query.return.types[query method return types].
+Refer to the appendix explaining all possible xref:repositories/query-return-types-reference.adoc#appendix.query.return.types[query method return types].
 
 [[repositories.collections-and-iterables.streamable]]
 === Using Streamable as Query Method Return Type
diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc
diff --git a/src/main/antora/modules/ROOT/pages/repositories/scrolling.adoc b/src/main/antora/modules/ROOT/pages/repositories/scrolling.adoc
