Prefer Java configuration over XML.

Closes #4186

Author: mp911de

src/main/asciidoc/index.adoc

@@ -3,7 +3,8 @@ Mark Pollack; Thomas Risberg; Oliver Gierke; Costin Leau; Jon Brisbin; Thomas Da
 :revnumber: {version}
 :revdate: {localdate}
 ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
-:spring-data-commons-docs: ../../../../../spring-data-commons/src/main/asciidoc
+:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
+:store: Mongo
 
 (C) 2008-2022 The original authors.
 

src/main/asciidoc/reference/gridfs.adoc

@@ -3,9 +3,10 @@
 
 MongoDB supports storing binary files inside its filesystem, GridFS. Spring Data MongoDB provides a `GridFsOperations` interface as well as the corresponding implementation, `GridFsTemplate`, to let you interact with the filesystem. You can set up a `GridFsTemplate` instance by handing it a `MongoDatabaseFactory` as well as a `MongoConverter`, as the following example shows:
 
-.JavaConfig setup for a GridFsTemplate
+
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 class GridFsConfiguration extends AbstractMongoClientConfiguration {
 
@@ -17,13 +18,9 @@ class GridFsConfiguration extends AbstractMongoClientConfiguration {
   }
 }
 ----
-====
 
-The corresponding XML configuration follows:
-
-.XML configuration for a GridFsTemplate
-====
-[source,xml]
+.XML
+[source,xml,role="secondary"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"

src/main/asciidoc/reference/mapping.adoc

@@ -266,11 +266,11 @@ calling `get()` before the actual conversion
 
 Unless explicitly configured, an instance of `MappingMongoConverter` is created by default when you create a `MongoTemplate`. You can create your own instance of the `MappingMongoConverter`. Doing so lets you dictate where in the classpath your domain classes can be found, so that Spring Data MongoDB can extract metadata and construct indexes. Also, by creating your own instance, you can register Spring converters to map specific classes to and from the database.
 
-You can configure the `MappingMongoConverter` as well as `com.mongodb.client.MongoClient` and MongoTemplate by using either Java-based or XML-based metadata. The following example uses Spring's Java-based configuration:
+You can configure the `MappingMongoConverter` as well as `com.mongodb.client.MongoClient` and MongoTemplate by using either Java-based or XML-based metadata. The following example shows the configuration:
 
-.@Configuration class to configure MongoDB mapping support
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 @Configuration
 public class MongoConfig extends AbstractMongoClientConfiguration {
@@ -299,24 +299,11 @@ public class MongoConfig extends AbstractMongoClientConfiguration {
     return new LoggingEventListener<MongoMappingEvent>();
   }
 }
-----
-<1> The mapping base package defines the root path used to scan for entities used to pre initialize the `MappingContext`. By default the configuration classes package is used.
-<2> Configure additional custom converters for specific domain types that replace the default mapping procedure for those types with your custom implementation.
-====
-
-`AbstractMongoClientConfiguration` requires you to implement methods that define a `com.mongodb.client.MongoClient` as well as provide a database name. `AbstractMongoClientConfiguration` also has a method named  `getMappingBasePackage(…)` that you can override to tell the converter where to scan for classes annotated with the `@Document` annotation.
-
-You can add additional converters to the converter by overriding the `customConversionsConfiguration` method.
-MongoDB's native JSR-310 support can be enabled through `MongoConverterConfigurationAdapter.useNativeDriverJavaTimeCodecs()`.
-Also shown in the preceding example is a `LoggingEventListener`, which logs `MongoMappingEvent` instances that are posted onto Spring's `ApplicationContextEvent` infrastructure.
-
-NOTE: `AbstractMongoClientConfiguration` creates a `MongoTemplate` instance and registers it with the container under the name `mongoTemplate`.
 
-Spring's MongoDB namespace lets you enable mapping functionality in XML, as the following example shows:
+----
 
-.XML schema to configure MongoDB mapping support
-====
-[source,xml]
+.XML
+[source,xml,role="secondary"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"
@@ -353,8 +340,19 @@ Spring's MongoDB namespace lets you enable mapping functionality in XML, as the
 
 </beans>
 ----
+<1> The mapping base package defines the root path used to scan for entities used to pre initialize the `MappingContext`. By default the configuration classes package is used.
+<2> Configure additional custom converters for specific domain types that replace the default mapping procedure for those types with your custom implementation.
 ====
 
+`AbstractMongoClientConfiguration` requires you to implement methods that define a `com.mongodb.client.MongoClient` as well as provide a database name. `AbstractMongoClientConfiguration` also has a method named  `getMappingBasePackage(…)` that you can override to tell the converter where to scan for classes annotated with the `@Document` annotation.
+
+You can add additional converters to the converter by overriding the `customConversionsConfiguration` method.
+MongoDB's native JSR-310 support can be enabled through `MongoConverterConfigurationAdapter.useNativeDriverJavaTimeCodecs()`.
+Also shown in the preceding example is a `LoggingEventListener`, which logs `MongoMappingEvent` instances that are posted onto Spring's `ApplicationContextEvent` infrastructure.
+
+NOTE: `AbstractMongoClientConfiguration` creates a `MongoTemplate` instance and registers it with the container under the name `mongoTemplate`.
+
+
 The `base-package` property tells it where to scan for classes annotated with the `@org.springframework.data.mongodb.core.mapping.Document` annotation.
 
 [[mapping-usage]]
@@ -607,7 +605,7 @@ The mapping subsystem allows the customization of the object construction by ann
 
 * If a parameter is annotated with the `@Value` annotation, the given expression is evaluated and the result is used as the parameter value.
 * If the Java type has a property whose name matches the given field of the input document, then it's property information is used to select the appropriate constructor parameter to pass the input field value to. This works only if the parameter name information is present in the java `.class` files which can be achieved by compiling the source with debug information or using the new `-parameters` command-line switch for javac in Java 8.
-* Otherwise a `MappingException` will be thrown indicating that the given constructor parameter could not be bound.
+* Otherwise, a `MappingException` will be thrown indicating that the given constructor parameter could not be bound.
 
 [source,java]
 ----

src/main/asciidoc/reference/mongo-auditing.adoc

@@ -1,11 +1,11 @@
 [[mongo.auditing]]
 == General Auditing Configuration for MongoDB
 
-Since Spring Data MongoDB 1.4, auditing can be enabled by annotating a configuration class with the `@EnableMongoAuditing` annotation, as the followign example shows:
+Since Spring Data MongoDB 1.4, auditing can be enabled by annotating a configuration class with the `@EnableMongoAuditing` annotation, as the following example shows:
 
-.Activating auditing using JavaConfig
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 @Configuration
 @EnableMongoAuditing
@@ -17,19 +17,16 @@ class Config {
   }
 }
 ----
-====
-If you expose a bean of type `AuditorAware` to the `ApplicationContext`, the auditing infrastructure picks it up automatically and uses it to determine the current user to be set on domain types. If you have multiple implementations registered in the `ApplicationContext`, you can select the one to be used by explicitly setting the `auditorAwareRef` attribute of `@EnableMongoAuditing`.
-
-To activate auditing functionality via XML, add the Spring Data Mongo `auditing` namespace element to your configuration, as the following example shows:
 
-.Activating auditing by using XML configuration
-====
-[source,xml]
+.XML
+[source,xml,role="secondary"]
 ----
 <mongo:auditing mapping-context-ref="customMappingContext" auditor-aware-ref="yourAuditorAwareImpl"/>
 ----
 ====
 
+If you expose a bean of type `AuditorAware` to the `ApplicationContext`, the auditing infrastructure picks it up automatically and uses it to determine the current user to be set on domain types. If you have multiple implementations registered in the `ApplicationContext`, you can select the one to be used by explicitly setting the `auditorAwareRef` attribute of `@EnableMongoAuditing`.
+
 To enable auditing, leveraging a reactive programming model, use the `@EnableReactiveMongoAuditing` annotation. +
 If you expose a bean of type `ReactiveAuditorAware` to the `ApplicationContext`, the auditing infrastructure picks it up automatically and uses it to determine the current user to be set on domain types. If you have multiple implementations registered in the `ApplicationContext`, you can select the one to be used by explicitly setting the `auditorAwareRef` attribute of `@EnableReactiveMongoAuditing`.
 

src/main/asciidoc/reference/mongo-repositories-aggregation.adoc

@@ -82,7 +82,7 @@ Use the `@Meta` annotation to set those options via `maxExecutionTimeMs`, `comme
 
 [source,java]
 ----
-public interface PersonRepository extends CrudReppsitory<Person, String> {
+interface PersonRepository extends CrudReppsitory<Person, String> {
 
   @Meta(allowDiskUse = true)
   @Aggregation("{ $group: { _id : $lastname, names : { $addToSet : $firstname } } }")
@@ -99,7 +99,7 @@ Or use `@Meta` to create your own annotation as shown in the sample below.
 @Meta(allowDiskUse = true)
 @interface AllowDiskUse { }
 
-public interface PersonRepository extends CrudReppsitory<Person, String> {
+interface PersonRepository extends CrudReppsitory<Person, String> {
 
   @AllowDiskUse
   @Aggregation("{ $group: { _id : $lastname, names : { $addToSet : $firstname } } }")

src/main/asciidoc/reference/mongo-repositories.adoc

@@ -51,14 +51,14 @@ Right now this interface serves only to provide type information, but we can add
 To start using the repository, use the `@EnableMongoRepositories` annotation.
 That annotation carries the same attributes as the namespace element.
 If no base package is configured, the infrastructure scans the package of the annotated configuration class.
-The following example shows how to use Java configuration for a repository:
+The following example shows how to configuration your application to use MongoDB repositories:
 
-.Java configuration for repositories
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 @Configuration
-@EnableMongoRepositories
+@EnableMongoRepositories("com.acme.*.repositories")
 class ApplicationConfig extends AbstractMongoClientConfiguration {
 
   @Override
@@ -68,17 +68,13 @@ class ApplicationConfig extends AbstractMongoClientConfiguration {
 
   @Override
   protected String getMappingBasePackage() {
-    return "com.oreilly.springdata.mongodb";
+    return "com.acme.*.repositories";
   }
 }
 ----
-====
 
-If you would rather go with XML based configuration add the following content:
-
-.General MongoDB repository Spring XML configuration
-====
-[source,xml]
+.XML
+[source,xml,role="secondary"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"
@@ -113,14 +109,14 @@ Consequently, accessing the second page of `Person` objects at a page size of 10
 ====
 [source,java]
 ----
-@RunWith(SpringRunner.class)
+@ExtendWith(SpringExtension.class)
 @ContextConfiguration
-public class PersonRepositoryTests {
+class PersonRepositoryTests {
 
     @Autowired PersonRepository repository;
 
     @Test
-    public void readsFirstPageCorrectly() {
+    void readsFirstPageCorrectly() {
 
       Page<Person> persons = repository.findAll(PageRequest.of(0, 10));
       assertThat(persons.isFirstPage()).isTrue();