Restructure documentation.

Move examples into test source root to ensure proper compilation. Remove lingering asciidoc resources.
Merge entity callbacks into lifecycle events. Add links from MongoDB overview.

See: #4497

Author: mp911de

src/main/antora/modules/ROOT/examples/MongoApplication.java renamed to spring-data-mongodb/src/test/java/org/springframework/data/mongodb/example/MongoApplication.java

@@ -16,12 +16,10 @@
 // tag::file[]
 package org.springframework.data.mongodb.example;
 
-import static org.springframework.data.mongodb.core.query.Criteria.where;
-import static org.springframework.data.mongodb.core.query.Query.query;
+import static org.springframework.data.mongodb.core.query.Criteria.*;
 
 import org.springframework.data.mongodb.core.MongoOperations;
 import org.springframework.data.mongodb.core.MongoTemplate;
-import org.springframework.data.mongodb.core.query.Query;
 
 import com.mongodb.client.MongoClients;
 

src/main/antora/modules/ROOT/examples/Person.java renamed to spring-data-mongodb/src/test/java/org/springframework/data/mongodb/example/Person.java

@@ -17,7 +17,6 @@
 package org.springframework.data.mongodb.example;
 
 import static org.springframework.data.mongodb.core.query.Criteria.*;
-import static org.springframework.data.mongodb.core.query.Query.*;
 
 import org.springframework.data.mongodb.core.ReactiveMongoOperations;
 import org.springframework.data.mongodb.core.ReactiveMongoTemplate;

src/main/antora/modules/ROOT/examples/ReactiveMongoApplication.java renamed to spring-data-mongodb/src/test/java/org/springframework/data/mongodb/example/ReactiveMongoApplication.java

@@ -0,0 +1 @@
+../../../../../../spring-data-mongodb/src/test/java/org/springframework/data/mongodb/example

src/main/antora/modules/ROOT/assets/images/epub-cover.png

@@ -7,40 +7,40 @@
 * xref:mongodb.adoc[]
 ** xref:mongodb/getting-started.adoc[]
 ** xref:mongodb/configuration.adoc[]
+
 ** xref:mongodb/template-api.adoc[]
 *** xref:mongodb/template-config.adoc[]
+*** xref:mongodb/template-collection-management.adoc[]
 *** xref:mongodb/template-crud-operations.adoc[]
 *** xref:mongodb/template-query-operations.adoc[]
-**** xref:mongodb/template-query-options.adoc[]
-*** xref:mongodb/template-document-count.adoc[]
 *** xref:mongodb/aggregation-framework.adoc[]
-*** xref:mongodb/template-collection-management.adoc[]
-**** xref:mongodb/template-collection-schema.adoc[]
-*** xref:mongodb/template-gridfs.adoc[]
+*** xref:mongodb/template-document-count.adoc[]
+
+** xref:mongodb/template-gridfs.adoc[]
 ** xref:mongodb/mapping/mapping.adoc[]
+*** xref:mongodb/mapping/mapping-schema.adoc[]
 *** xref:mongodb/mapping/custom-conversions.adoc[Type based Converter]
 *** xref:mongodb/mapping/property-converters.adoc[]
 *** xref:mongodb/mapping/unwrapping-entities.adoc[]
 *** xref:mongodb/mapping/document-references.adoc[Object References]
-*** xref:mongodb/mapping/entity-callbacks.adoc[Entity Callbacks]
-*** xref:mongodb/mapping/lifecycle-events.adoc[]
 *** xref:mongodb/mapping/mapping-index-management.adoc[]
+
+** xref:mongodb/lifecycle-events.adoc[]
+** xref:mongodb/auditing.adoc[]
 ** xref:mongodb/client-session-transactions.adoc[]
 ** xref:mongodb/change-streams.adoc[]
 ** xref:mongodb/tailable-cursors.adoc[]
 ** xref:mongodb/sharding.adoc[]
 ** xref:mongodb/mongo-encryption.adoc[]
-** xref:mongodb/auditing.adoc[]
 
 // Repository
 * xref:repositories.adoc[]
 ** xref:repositories/core-concepts.adoc[]
 ** xref:repositories/definition.adoc[]
 ** xref:mongodb/repositories/repositories.adoc[]
-*** xref:mongodb/repositories/repositories-index-hints.adoc[]
-*** xref:mongodb/repositories/repositories-collation.adoc[]
 ** xref:repositories/create-instances.adoc[]
 ** xref:repositories/query-methods-details.adoc[]
+** xref:mongodb/repositories/query-methods.adoc[]
 ** xref:repositories/projections.adoc[]
 ** xref:repositories/custom-implementations.adoc[]
 ** xref:repositories/core-domain-events.adoc[]

src/main/antora/modules/ROOT/assets/images/epub-cover.svg

@@ -4,17 +4,18 @@
 
 Spring Data support for MongoDB contains a wide range of features:
 
-* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets.
-* `MongoTemplate` helper class that increases productivity when performing common Mongo operations. Includes integrated object mapping between documents and POJOs.
-* Exception translation into Spring's portable Data Access Exception hierarchy.
-* Feature-rich Object Mapping integrated with Spring's Conversion Service.
-* Annotation-based mapping metadata that is extensible to support other metadata formats.
-* Persistence and mapping lifecycle events.
-* Java-based Query, Criteria, and Update DSLs.
-* Automatic implementation of Repository interfaces, including support for custom finder methods.
-* QueryDSL integration to support type-safe queries.
-* Multi Document Transactions.
-* GeoSpatial integration.
+* xref:mongodb/template-config.adoc[Spring configuration support] with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets.
+* xref:mongodb/template-api.adoc[`MongoTemplate` helper class] that increases productivity when performing common Mongo operations.
+Includes integrated object mapping between documents and POJOs.
+* xref:mongodb/template-api.adoc#mongo-template.exception-translation[Exception translation] into Spring's portable Data Access Exception hierarchy.
+* Feature-rich xref:mongodb/mapping/mapping.adoc[Object Mapping] integrated with Spring's Conversion Service.
+* xref:mongodb/mapping/mapping.adoc#mapping-usage-annotations[Annotation-based mapping metadata] that is extensible to support other metadata formats.
+* xref:mongodb/lifecycle-events.adoc[Persistence and mapping lifecycle events].
+* xref:mongodb/template-query-operations.adoc[Java-based Query, Criteria, and Update DSLs].
+* Automatic implementation of xref:repositories.adoc[Repository interfaces], including support for custom query methods.
+* xref:mongodb/repositories/repositories.adoc#mongodb.repositories.queries.type-safe[QueryDSL integration] to support type-safe queries.
+* xref:mongodb/client-session-transactions.adoc[Multi-Document Transactions].
+* xref:mongodb/template-query-operations.adoc#mongo.geo-json[GeoSpatial integration].
 
 For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality.
 `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations.

src/main/antora/modules/ROOT/examples/example

@@ -19,7 +19,7 @@ Then you can create a `Person` class to persist:
 ====
 [source,java]
 ----
-include::example$Person.java[tags=file]
+include::example$example/Person.java[tags=file]
 ----
 ====
 
@@ -31,14 +31,14 @@ Imperative::
 +
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 ----
-include::example$MongoApplication.java[tags=file]
+include::example$example/MongoApplication.java[tags=file]
 ----
 
 Reactive::
 +
 [source,java,indent=0,subs="verbatim,quotes",role="secondary"]
 ----
-include::example$ReactiveMongoApplication.java[tags=file]
+include::example$example/ReactiveMongoApplication.java[tags=file]
 ----
 ======
 

src/main/antora/modules/ROOT/nav.adoc

@@ -49,8 +49,58 @@ Declaring these beans in your Spring ApplicationContext causes them to be invoke
 * `onAfterConvert`: Called in `MongoTemplate` `find`, `findAndRemove`, `findOne`, and `getCollection` methods after the `Document` has been retrieved from the database was converted to a POJO.
 ====
 
-NOTE: Lifecycle events are only emitted for root level types. Complex types used as properties within a document root are not subject to event publication unless they are document references annotated with `@DBRef`.
+NOTE: Lifecycle events are only emitted for root level types.
+Complex types used as properties within a document root are not subject to event publication unless they are document references annotated with `@DBRef`.
 
 WARNING: Lifecycle events depend on an `ApplicationEventMulticaster`, which in case of the `SimpleApplicationEventMulticaster` can be configured with a `TaskExecutor`, and therefore gives no guarantees when an Event is processed.
 
+include::{commons}@data-commons::page$entity-callbacks.adoc[leveloffset=+1]
+
+[[mongo.entity-callbacks]]
+== Store specific EntityCallbacks
+
+Spring Data MongoDB uses the `EntityCallback` API for its auditing support and reacts on the following callbacks.
+
+.Supported Entity Callbacks
+[%header,cols="4"]
+|===
+| Callback
+| Method
+| Description
+| Order
+
+| `ReactiveBeforeConvertCallback`
+`BeforeConvertCallback`
+| `onBeforeConvert(T entity, String collection)`
+| Invoked before a domain object is converted to `org.bson.Document`.
+| `Ordered.LOWEST_PRECEDENCE`
+
+| `ReactiveAfterConvertCallback`
+`AfterConvertCallback`
+| `onAfterConvert(T entity, org.bson.Document target, String collection)`
+| Invoked after a domain object is loaded. +
+Can modify the domain object after reading it from a `org.bson.Document`.
+| `Ordered.LOWEST_PRECEDENCE`
+
+| `ReactiveAuditingEntityCallback`
+`AuditingEntityCallback`
+| `onBeforeConvert(Object entity, String collection)`
+| Marks an auditable entity _created_ or _modified_
+| 100
+
+| `ReactiveBeforeSaveCallback`
+`BeforeSaveCallback`
+| `onBeforeSave(T entity, org.bson.Document target, String collection)`
+| Invoked before a domain object is saved. +
+Can modify the target, to be persisted, `Document` containing all mapped entity information.
+| `Ordered.LOWEST_PRECEDENCE`
+
+| `ReactiveAfterSaveCallback`
+`AfterSaveCallback`
+| `onAfterSave(T entity, org.bson.Document target, String collection)`
+| Invoked before a domain object is saved. +
+Can modify the domain object, to be returned after save, `Document` containing all mapped entity information.
+| `Ordered.LOWEST_PRECEDENCE`
+
+|===
 

src/main/antora/modules/ROOT/pages/kotlin/object-mapping.adoc

@@ -30,7 +30,7 @@ public class Payment {
   "date"   : ISODate("2019-04-03T12:11:01.870Z") <3>
 }
 ----
-<1> String _id_ values that represent a valid `ObjectId` are converted automatically. See xref:mongodb/template-id-handling.adoc#mongo-template.id-handling[How the `_id` Field is Handled in the Mapping Layer]
+<1> String _id_ values that represent a valid `ObjectId` are converted automatically. See xref:mongodb/template-crud-operations.adoc#mongo-template.id-handling[How the `_id` Field is Handled in the Mapping Layer]
 for details.
 <2> The desired target type is explicitly defined as `Decimal128` which translates to `NumberDecimal`. Otherwise the
 `BigDecimal` value would have been truned into a `String`.