Merge pull request #27781 from loicmathieu/mongo-guide-improvements

Improve MongoDB guides

docs/src/main/asciidoc/mongodb-panache.adoc

@@ -7,9 +7,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 
 include::./attributes.adoc[]
 :config-file: application.properties
-:mongodb-doc-root-url: https://mongodb.github.io/mongo-java-driver/4.2
+:mongodb-doc-root-url: https://www.mongodb.com/docs/drivers/java/sync/current
 
-MongoDB is a well known NoSQL Database that is widely used, but using its raw API can be cumbersome as you need to express your entities and your queries as a MongoDB link:{mongodb-doc-root-url}/bson/documents/#document[`Document`].
+MongoDB is a well known NoSQL Database that is widely used, but using its raw API can be cumbersome as you need to express your entities and your queries as a MongoDB link:{mongodb-doc-root-url}/fundamentals/data-formats/documents/#document[`Document`].
 
 MongoDB with Panache provides active record style entities (and repositories) like you have in xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] and focuses on making your entities trivial and fun to write in Quarkus.
 
@@ -169,7 +169,7 @@ public class Person extends PanacheMongoEntity {
 
 NOTE: Annotating with `@MongoEntity` is optional. Here the entity will be stored in the `ThePerson` collection instead of the default `Person` collection.
 
-MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos/[PojoCodecProvider] to convert your entities to a MongoDB `Document`.
+MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo[PojoCodecProvider] to convert your entities to a MongoDB `Document`.
 
 You will be allowed to use the following annotations to customize this mapping:
 
@@ -319,7 +319,7 @@ public class Person  {
 
 NOTE: Annotating with `@MongoEntity` is optional. Here the entity will be stored in the `ThePerson` collection instead of the default `Person` collection.
 
-MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos/[PojoCodecProvider] to convert your entities to a MongoDB `Document`.
+MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/[PojoCodecProvider] to convert your entities to a MongoDB `Document`.
 
 You will be allowed to use the following annotations to customize this mapping:
 
@@ -746,7 +746,7 @@ quarkus.log.category."io.quarkus.mongodb.panache.runtime".level=DEBUG
 
 == The PojoCodecProvider: easy object to BSON document conversion.
 
-MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos[PojoCodecProvider], with link:{mongodb-doc-root-url}/pojos/#pojo-support[automatic POJO support],
+MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/[PojoCodecProvider], with link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/#configure-the-driver-for-pojos[automatic POJO support],
 to automatically convert your object to a BSON document.
 
 In case you encounter the `org.bson.codecs.configuration.CodecConfigurationException` exception, it means the codec is not able to
@@ -765,6 +765,9 @@ MongoDB offers ACID transactions since version 4.0.
 
 To use them with MongoDB with Panache you need to annotate the method that starts the transaction with the `@Transactional` annotation.
 
+In MongoDB, a transaction is only possible on a replicaset,
+luckily our xref:mongodb.adoc#dev-services[Dev Services for MongoDB] setups a single node replicaset so it is compatible with transactions.
+
 WARNING: Transaction support inside MongoDB with Panache is still experimental.
 
 == Custom IDs
@@ -829,7 +832,7 @@ Kotlin data classes are a very convenient way of defining data carrier classes,
 But this type of class comes with some limitations: all fields needs to be initialized at construction time or be marked as nullable,
 and the generated constructor needs to have as parameters all the fields of the data class.
 
-MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos[PojoCodecProvider], a MongoDB codec which mandates the presence of a parameterless constructor.
+MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo[PojoCodecProvider], a MongoDB codec which mandates the presence of a parameterless constructor.
 
 Therefore, if you want to use a data class as an entity class, you need a way to make Kotlin generate an empty constructor.
 To do so, you need to provide default values for all the fields of your classes.
@@ -843,7 +846,7 @@ First, you can create a BSON Codec which will be automatically registered by Qua
 See this part of the documentation: xref:mongodb.adoc#simplifying-mongodb-client-usage-using-bson-codec[Using BSON codec].
 
 Another option is to use the `@BsonCreator` annotation to tell the `PojoCodecProvider` to use the Kotlin data class default constructor,
-in this case all constructor parameters have to be annotated with `@BsonProperty`: see link:{mongodb-doc-root-url}/bson/pojos/#supporting-pojos-without-no-args-constructors[Supporting pojos without no args constructor].
+in this case all constructor parameters have to be annotated with `@BsonProperty`: see link:{mongodb-doc-root-url}/fundamentals/data-formats/pojo-customization/#pojos-without-no-argument-constructors[Supporting pojos without no args constructor].
 
 This will only work when the entity extends `PanacheMongoEntityBase` and not `PanacheMongoEntity`, as the ID field also needs to be included in the constructor.
 
@@ -891,7 +894,7 @@ and when defining your repositories: `ReactivePanacheMongoRepository` or `Reacti
 [TIP]
 .Mutiny
 ====
-The reactive API of the MongoDB with Panache uses Mutiny reactive types.
+The reactive API of MongoDB with Panache uses Mutiny reactive types.
 If you are not familiar with Mutiny, check xref:mutiny-primer.adoc[Mutiny - an intuitive reactive programming library].
 ====
 

docs/src/main/asciidoc/mongodb.adoc

@@ -240,9 +240,11 @@ Because the `mongo+srv` protocol often used to connect to MongoDB requires JNDI,
 === Dev Services (Configuration Free Databases)
 
 Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. In the case of MongoDB this support extends to the default MongoDB connection.
-What that means practically, is that if you have not configured `quarkus.mongodb.connection-string` Quarkus will automatically start a MongoDB container when running tests or dev mode,
+What that means practically, is that if you have not configured `quarkus.mongodb.connection-string`, Quarkus will automatically start a MongoDB container when running tests or in dev mode,
 and automatically configure the connection.
 
+MongoDB Dev Services is based on link:https://www.testcontainers.org/modules/databases/mongodb/[Testcontainers MongoDB module] that will start a single node replicaset.
+
 When running the production version of the application, the MongoDB connection need to be configured as normal, so if you want to include a production database config in your
 `application.properties` and continue to use Dev Services we recommend that you use the `%prod.` profile to define your MongoDB settings.
 
@@ -298,7 +300,7 @@ As by default, `MongoClient` is configured to access a local MongoDB database on
 If you want to use Docker to run a MongoDB database, you can use the following command to launch one:
 [source,bash]
 ----
-docker run -ti --rm -p 27017:27017 mongo:4.0
+docker run -ti --rm -p 27017:27017 mongo:4.4
 ----
 
 [NOTE]
@@ -316,11 +318,13 @@ In the `src/main/resources/META-INF/resources` directory, add a `fruits.html` fi
 You can now interact with your REST service:
 
 :devtools-wrapped:
+
  * start Quarkus with:
 +
 include::{includes}/devtools/dev.adoc[]
  * open a browser to `http://localhost:8080/fruits.html`
  * add new fruits to the list via the form
+
 :!devtools-wrapped:
 
 [[reactive]]
@@ -329,13 +333,6 @@ A reactive MongoDB Client is included in Quarkus.
 Using it is as easy as using the classic MongoDB Client.
 You can rewrite the previous example to use it like the following.
 
-[NOTE]
-.Deprecation
-====
-The `io.quarkus.mongodb.ReactiveMongoClient` client is deprecated and will be removed in the future.
-It is recommended to switch to the `io.quarkus.mongodb.reactive.ReactiveMongoClient` client providing the `Mutiny` API.
-====
-
 [TIP]
 .Mutiny
 ====
@@ -430,7 +427,7 @@ By using a Bson `Codec`, the MongoDB Client will take care of the transformation
 
 First you need to create a Bson `Codec` that will tell Bson how to transform your entity to/from a MongoDB `Document`.
 Here we use a `CollectibleCodec` as our object is retrievable from the database (it has a MongoDB identifier), if not we would have used a `Codec` instead.
-More information in the codec documentation: https://mongodb.github.io/mongo-java-driver/3.10/bson/codecs.
+More information in the codec documentation: https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/data-formats/codecs/.
 
 [source,java]
 ----
@@ -577,7 +574,7 @@ public class CodecFruitService {
 
 == The POJO Codec
 
-The link:https://mongodb.github.io/mongo-java-driver/3.12/bson/pojos/[POJO Codec] provides a set of annotations that enable the customization of
+The link:https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/data-formats/document-data-format-pojo/[POJO Codec] provides a set of annotations that enable the customization of
 the way a POJO is mapped to a MongoDB collection and this codec is initialized automatically by Quarkus
 
 One of these annotations is the `@BsonDiscriminator` annotation that allows to storage multiple Java types in a single MongoDB collection by adding
@@ -624,7 +621,10 @@ Read the xref:opentracing.adoc[OpenTracing] guide, for how to configure OpenTrac
 
 == Testing helpers
 
-To start a MongoDB database for your unit tests, Quarkus provides two `QuarkusTestResourceLifecycleManager` that relies on link:https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Flapdoodle embedded MongoDB].
+xref:#dev-services[Dev Services for MongoDB] is your best option to start a MongoDB database for your unit tests.
+
+But if you can't use it, you can start a MongoDB database using one of the two `QuarkusTestResourceLifecycleManager` that Quarkus provides.
+They rely on link:https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Flapdoodle embedded MongoDB].
 
 - `io.quarkus.test.mongodb.MongoTestResource` will start a single instance on port 27017.
 - `io.quarkus.test.mongodb.MongoReplicaSetTestResource` will start a replicaset with two instances, one on port 27017 and the other on port 27018.