JAVA-2751: Reference documentation for new MongoClients entry point to the synchronous driver

Author: jyemin

docs/reference/content/driver/getting-started/quick-start-pojo.md

@@ -149,7 +149,10 @@ There are multiple ways to set the `pojoCodecRegistry` for use:
  - You can set it when instantiating a MongoClient object:
 
  ```java
- MongoClient mongoClient = new MongoClient("localhost", MongoClientOptions.builder().codecRegistry(pojoCodecRegistry).build());
+MongoClientSettings settings = MongoClientSettings.builder()
+        .codecRegistry(pojoCodecRegistry)
+        .build();
+MongoClient mongoClient = MongoClients.create(settings);
 ```
 
 - You can use an alternative `CodecRegistry` with a `MongoDatabase`:

docs/reference/content/driver/getting-started/quick-start.md

@@ -23,9 +23,24 @@ that can be found with the driver source on github.
 
 - The following import statements:
 
+New MongoClient API (since 3.7):
+
+```java
+import com.mongodb.ConnectionString;
+import com.mongodb.clients.MongoClients;
+import com.mongodb.clients.MongoClient;
+```
+
+Legacy MongoClient API:
+
 ```java
 import com.mongodb.MongoClient;
 import com.mongodb.MongoClientURI;
+```
+
+And the common elements between the legacy and new APIs:
+
+```java
 import com.mongodb.ServerAddress;
 
 import com.mongodb.client.MongoDatabase;
@@ -45,7 +60,9 @@ import java.util.List;
 ```
 ## Make a Connection
 
-Use [`MongoClient()`]({{< apiref "com/mongodb/MongoClient.html">}}) to make a connection to a running MongoDB instance.
+Use [`MongoClients.create()`]({{< apiref "com/mongodb/client/MongoClients.html">}}), 
+or [`MongoClient()`]({{< apiref "com/mongodb/MongoClient.html">}}) for the legacy MongoClient API, 
+to make a connection to a running MongoDB instance.
 
 The `MongoClient` instance represents a pool of connections to the database; you will only need one instance of class `MongoClient` even with multiple threads.
 
@@ -61,9 +78,46 @@ The `MongoClient` instance represents a pool of connections to the database; you
 
 ### Connect to a Single MongoDB instance
 
-The following example shows five ways to connect to the
-database `mydb` on the local machine. If the database does not exist, MongoDB
-will create it for you.
+The following example shows several ways to connect to a single MongoDB server.
+
+##### New MongoClient API (since 3.7)
+
+To connect to a single MongoDB instance:
+
+- You can instantiate a MongoClient object without any parameters to connect to a MongoDB instance running on localhost on port ``27017``:
+
+```java
+MongoClient mongoClient = MongoClients.create();
+```
+
+- You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port ``27017``:
+
+```java
+MongoClient mongoClient = MongoClients.create(
+        MongoClientSettings.builder()
+                .applyToClusterSettings(builder ->
+                        builder.hosts(Arrays.asList(new ServerAddress("hostOne"))))
+                .build());
+```
+
+- You can explicitly specify the hostname and the port:
+
+```java
+MongoClient mongoClient = MongoClients.create(
+        MongoClientSettings.builder()
+                .applyToClusterSettings(builder ->
+                        builder.hosts(Arrays.asList(new ServerAddress("hostOne", 27018))))
+                .build());
+```
+
+- You can specify the [`ConnectionString`]({{< apiref "/com/mongodb/ConnectionString.html">}}):
+
+```java
+MongoClient mongoClient = MongoClients.create("mongodb://hostOne:27017,hostTwo:27018");
+```
+
+
+##### Legacy MongoClient API
 
 To connect to a single MongoDB instance:
 
@@ -76,24 +130,26 @@ MongoClient mongoClient = new MongoClient();
 - You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port ``27017``:
 
 ```java
-MongoClient mongoClient = new MongoClient( "localhost" );
+MongoClient mongoClient = new MongoClient( "hostOne" );
 ```
 
 - You can explicitly specify the hostname and the port:
 
 ```java
-MongoClient mongoClient = new MongoClient( "localhost" , 27017 );
+MongoClient mongoClient = new MongoClient( "hostOne" , 27018 );
 ```
 
 - You can specify the
 [`MongoClientURI`]({{< apiref "/com/mongodb/MongoClientURI.html">}}) connection string:
 
 ```java
- MongoClientURI connectionString = new MongoClientURI("mongodb://localhost:27017");
+ MongoClientURI connectionString = new MongoClientURI("mongodb://hostOne:27017,hostTwo:27017");
  MongoClient mongoClient = new MongoClient(connectionString);
 ```
 
-The connection string mostly follows [RFC 3986](http://tools.ietf.org/html/rfc3986), with the exception of the domain name. For MongoDB, it is possible to list multiple domain names separated by a comma. For more information on the connection string, see [connection string]({{< docsref "reference/connection-string" >}}).
+The connection string mostly follows [RFC 3986](http://tools.ietf.org/html/rfc3986), with the exception of the domain name. For MongoDB, 
+it is possible to list multiple domain names separated by a comma. For more information on the connection string, see 
+[connection string]({{< docsref "reference/connection-string" >}}).
 
 ## Access a Database
 

docs/reference/content/driver/reference/monitoring.md

@@ -100,10 +100,11 @@ public class TestCommandListener implements CommandListener {
 and an instance of `MongoClientOptions` configured with an instance of `TestCommandListener`:
 
 ```java
-MongoClientOptions options = MongoClientOptions.builder()
-                                       .addCommandListener(new TestCommandListener())
-                                       .build();
-MongoClient client = new MongoClient(new ServerAddress(), options);
+MongoClientSettings settings = MongoClientSettings.builder()
+        .addCommandListener(new TestCommandListener())
+        .build();
+MongoClient client = MongoClients.create(settings);
+
 ```
 
 A `MongoClient` configured with these options will print a message to `System.out` before sending each command to a MongoDB server, and
@@ -177,10 +178,11 @@ and an instance of `MongoClientOptions` configured with an instance of `TestClus
 
 ```java
 List<ServerAddress> seedList = ...
-MongoClientOptions options = MongoClientOptions.builder()
-                                       .addClusterListener(new TestClusterListener(ReadPreference.secondary()))
-                                       .build();
-MongoClient client = new MongoClient(seedList, options);
+MongoClientSettings settings = MongoClientSettings.builder()
+        .applyToClusterSettings(builder -> 
+                builder.addClusterListener(new TestClusterListener(ReadPreference.secondary())))
+        .build();
+MongoClient client = MongoClients.create(settings);
 ```
 
 A `MongoClient` configured with these options will print a message to `System.out` when the MongoClient is created with these options,
@@ -248,10 +250,11 @@ and an instance of `MongoClientOptions` configured with an instance of `TestConn
 
 ```java
 List<ServerAddress> seedList = ...
-MongoClientOptions options = MongoClientOptions.builder()
-                                      .addConnectionPoolListener(new TestConnectionPoolListener())
-                                      .build();
-MongoClient client = new MongoClient(new ServerAddress(), options);
+MongoClientSettings settings = MongoClientSettings.builder()
+        .applyToConnectionPoolSettings(builder -> 
+                builder.addConnectionPoolListener(new TestConnectionPoolListener()))
+        .build();
+MongoClient client = MongoClients.create(settings);
 ```
 
 A `MongoClient` configured with these options will print a message to `System.out` for each connection pool-related event for each MongoDB

docs/reference/content/driver/tutorials/aggregation.md

@@ -20,7 +20,8 @@ The [aggregation pipeline]({{<docsref "core/aggregation-pipeline">}}) is a frame
 
      ```java
      import com.mongodb.Block;
-     import com.mongodb.MongoClient;
+     import com.mongodb.client.MongoClients;
+     import com.mongodb.client.MongoClient;
      import com.mongodb.client.MongoCollection;
      import com.mongodb.client.MongoDatabase;
      import com.mongodb.client.model.Aggregates;
@@ -49,7 +50,7 @@ Connect to a MongoDB deployment and declare and define a `MongoDatabase` and a `
 For example, include the following code to connect to a standalone MongoDB deployment running on localhost on port `27017` and define `database` to refer to the `test` database and `collection` to refer to the `restaurants` collection.
 
 ```java
-MongoClient mongoClient = new MongoClient();
+MongoClient mongoClient = MongoClients.create();
 MongoDatabase database = mongoClient.getDatabase("test");
 MongoCollection<Document> collection = database.getCollection("restaurants");
 ```