Update reference documentation for the 3.5 release

jyemin · jyemin · commit 4fd397334b08 · 2017-08-02T22:41:09.000-04:00
diff --git a/docs/reference/content/bson/installation-guide.md b/docs/reference/content/bson/installation-guide.md
@@ -22,4 +22,4 @@ This library comprehensively supports [BSON](http://www.bsonspec.org),
 the data storage and network transfer format that MongoDB uses for "documents".
 BSON is short for Binary [JSON](http://json.org/), is a binary-encoded serialization of JSON-like documents.
 
-{{< install artifactId="bson" version="3.4.2" >}}
+{{< install artifactId="bson" version="3.5.0" >}}
diff --git a/docs/reference/content/driver-async/getting-started/installation.md b/docs/reference/content/driver-async/getting-started/installation.md
@@ -23,4 +23,4 @@ The MongoDB Async Driver requires either [Netty](http://netty.io/) or Java 7.
 
 The MongoDB Async Driver provides asynchronous API that can leverage either Netty or Java 7's AsynchronousSocketChannel for fast and non-blocking I/O.
 
-{{< install artifactId="mongodb-driver-async" version="3.5.0-SNAPSHOT" dependencies="true">}}
+{{< install artifactId="mongodb-driver-async" version="3.5.0" dependencies="true">}}
diff --git a/docs/reference/content/driver-async/index.md b/docs/reference/content/driver-async/index.md
@@ -9,7 +9,7 @@ title = "MongoDB Async Driver"
 
 ## MongoDB Async Java Driver Documentation
 
-The following guide provides information on using the callback-based MongoDB Async Java Driver 3.4.
+The following guide provides information on using the callback-based MongoDB Async Java Driver 3.5.
 
 {{% note %}}
 There are two higher level MongoDB Asynchronous Java Drivers available, that users may find easier to work with due to their friendlier APIs:
diff --git a/docs/reference/content/driver-async/reference/monitoring.md b/docs/reference/content/driver-async/reference/monitoring.md
@@ -182,3 +182,78 @@ and when that MongoClient is closed.  In addition, it will print a message when
 * without an available server that will accept writes
 * with an available server that will accept reads using the configured `ReadPreference`
 * without an available server that will accept reads using the configured `ReadPreference`
+
+# Connection Pool Monitoring
+
+The driver supports monitoring of connection pool-related events.
+
+An application registers listeners with a `MongoClient` by configuring `MongoClientSettings` with instances of classes that
+implement the [`ConnectionPoolListener`]({{< apiref "com/mongodb/event/ConnectionPoolListener" >}}) interface.
+
+Consider the following, simplistic, example of a connection pool listener:
+
+```java
+public class TestConnectionPoolListener implements ConnectionPoolListener {
+    @Override
+    public void connectionPoolOpened(final ConnectionPoolOpenedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionPoolClosed(final ConnectionPoolClosedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionCheckedOut(final ConnectionCheckedOutEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionCheckedIn(final ConnectionCheckedInEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void waitQueueEntered(final ConnectionPoolWaitQueueEnteredEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void waitQueueExited(final ConnectionPoolWaitQueueExitedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionAdded(final ConnectionAddedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionRemoved(final ConnectionRemovedEvent event) {
+        System.out.println(event);
+    }
+}
+```
+
+and an instance of `MongoClientSettings` configured with an instance of `TestConnectionPoolListener`:
+
+```java
+List<ServerAddress> seedList = ...
+TestConnectionPoolListener connectionPoolListener = new TestConnectionPoolListener();
+ClusterSettings clusterSettings = ClusterSettings.builder()
+                                          .hosts(seedList)
+                                          .build();
+ConnectionPoolSettings connectionPoolSettings = 
+        ConnectionPoolSettings.builder()
+                              .addConnectionPoolListener(connectionPoolListener)
+                              .build();
+MongoClientSettings settings = MongoClientSettings.builder()
+                                       .clusterSettings(clusterSettings)
+                                       .connectionPoolSettings(connectionPoolSettings)
+                                       .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
+server to which the MongoClient is connected.
diff --git a/docs/reference/content/driver-async/tutorials/ssl.md b/docs/reference/content/driver-async/tutorials/ssl.md
@@ -19,7 +19,7 @@ To use TLS/SSL, you must configure the asynchronous driver to use [Netty](http:/
 
 {{% note %}}
 If your application requires Netty, it must explicitly add a dependency to
-Netty artifacts.  The driver is currently tested against Netty 4.0.
+Netty artifacts.  The driver is currently tested against Netty 4.1.
 {{% /note %}}
 
 ### Via Connection String
@@ -36,7 +36,9 @@ You can also specify the connection string via the [`ConnectionString`]({{< apir
 
 ### Via `MongoClientSettings`
 
-To specify TLS/SSL with  [`MongoClientSettings`]({{< apiref "com/mongodb/async/client/MongoClientSettings.Builder.html#streamFactoryFactory-com.mongodb.connection.StreamFactoryFactory-">}}) , set the ``sslEnabled`` property to ``true``, and the stream factory to [`NettyStreamFactoryFactory`]({{< apiref "com/mongodb/connection/netty/NettyStreamFactoryFactory" >}}), as in
+To specify TLS/SSL with  [`MongoClientSettings`]({{< apiref "com/mongodb/async/client/MongoClientSettings.Builder.html#streamFactoryFactory-com.mongodb.connection.StreamFactoryFactory-">}}) , 
+set the ``sslEnabled`` property to ``true``, and the stream factory to 
+[`NettyStreamFactoryFactory`]({{< apiref "com/mongodb/connection/netty/NettyStreamFactoryFactory" >}}), as in
 
 ```java
 
@@ -65,6 +67,18 @@ Netty may also be configured by setting the `org.mongodb.async.type` system prop
 deprecated as of the 3.1 driver release.
 {{% /note %}}
 
+To override the default [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) used for SSL
+connections, set the `sslContext` property on the `SslSettings`, as in:
+
+```java
+ SSLContext sslContext = ...
+ SslSettings sslSettings = SslSettings.builder()
+                                      .enabled(true)
+                                      .sslContext(sslContext)
+                                      .build();
+ // Pass sslSettings to the MongoClientSettings.Builder
+```
+
 
 ## Disable Hostname Verification
 
diff --git a/docs/reference/content/driver/getting-started/installation.md b/docs/reference/content/driver/getting-started/installation.md
@@ -13,7 +13,7 @@ title = "Installation"
 The recommended way to get started using one of the drivers in your
 project is with a dependency management system.
 
-There are two Maven artifacts available in the 3.4 release. The preferred artifact for new applications is `mongodb-driver`
+There are two Maven artifacts available in the 3.5 release. The preferred artifact for new applications is `mongodb-driver`
 however, we still publish the legacy `mongo-java-driver` uber-jar.
 
 {{< distroPicker >}}
@@ -29,7 +29,7 @@ For OSGi-based applications, use the [mongo-java-driver](#uber-jar-legacy) uber
 
 {{% /note %}}
 
-{{< install artifactId="mongodb-driver" version="3.5.0-SNAPSHOT" dependencies="true">}}
+{{< install artifactId="mongodb-driver" version="3.5.0" dependencies="true">}}
 
 
 ## Uber Jar (Legacy)
@@ -41,4 +41,4 @@ For new applications, the preferred artifact is [mongodb-driver](#mongodb-driver
 The `mongo-java-driver` artifact is a valid OSGi bundle.
 {{% /note %}}
 
-{{< install artifactId="mongo-java-driver" version="3.5.0-SNAPSHOT">}}
+{{< install artifactId="mongo-java-driver" version="3.5.0">}}
diff --git a/docs/reference/content/driver/reference/monitoring.md b/docs/reference/content/driver/reference/monitoring.md
@@ -84,15 +84,13 @@ public class TestCommandListener implements CommandListener {
 ```
 
 
-and an instance of `MongoClientSettings` configured with an instance of `TestCommandListener`:
+and an instance of `MongoClientOptions` configured with an instance of `TestCommandListener`:
 
 ```java
-ClusterSettings clusterSettings = ...
-MongoClientSettings settings = MongoClientSettings.builder()
-                                       .clusterSettings(clusterSettings)
+MongoClientOptions options = MongoClientOptions.builder()
                                        .addCommandListener(new TestCommandListener())
                                        .build();
-MongoClient client = MongoClients.create(settings);
+MongoClient client = new MongoClient(new ServerAddress(), options);
 ```
 
 A `MongoClient` configured with these options will print a message to `System.out` before sending each command to a MongoDB server, and
@@ -104,7 +102,7 @@ The driver implements the
 [SDAM Monitoring specification](https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst),
 allowing an application to be notified when the driver detects changes to the topology of the MongoDB cluster to which it is connected.
 
-An application registers listeners with a `MongoClient` by configuring  `MongoClientSettings` with instances of classes that
+An application registers listeners with a `MongoClient` by configuring  `MongoClientOptions` with instances of classes that
 implement any of the [`ClusterListener`]({{< apiref "com/mongodb/event/ClusterListener" >}}),
  [`ServerListener`]({{< apiref "com/mongodb/event/ServerListener" >}}),
 or [`ServerMonitorListener`]({{< apiref "com/mongodb/event/ServerMonitorListener" >}}) interfaces.
@@ -162,24 +160,86 @@ public class TestClusterListener implements ClusterListener {
 }
 ```
 
-and an instance of `MongoClientSettings` configured with an instance of `TestClusterListener`:
+and an instance of `MongoClientOptions` configured with an instance of `TestClusterListener`:
 
 ```java
 List<ServerAddress> seedList = ...
-ClusterSettings clusterSettings = ClusterSettings.builder()
-                                          .hosts(seedList)
-                                          .addClusterListener(new TestClusterListener(ReadPreference.secondary()))
-                                          .build();
-MongoClientSettings settings = MongoClientSettings.builder()
-                                       .clusterSettings(clusterSettings)
+MongoClientOptions options = MongoClientOptions.builder()
+                                       .addClusterListener(new TestClusterListener(ReadPreference.secondary()))
                                        .build();
-MongoClient client = MongoClients.create(settings);
+MongoClient client = new MongoClient(seedList, options);
 ```
 
-A `MongoClient` configured with these settings will print a message to `System.out` when the MongoClient is created with these options,
+A `MongoClient` configured with these options will print a message to `System.out` when the MongoClient is created with these options,
 and when that MongoClient is closed.  In addition, it will print a message when the client enters a state:
 
 * with an available server that will accept writes
 * without an available server that will accept writes
 * with an available server that will accept reads using the configured `ReadPreference`
 * without an available server that will accept reads using the configured `ReadPreference`
+
+# Connection Pool Monitoring
+
+The driver supports monitoring of connection pool-related events.
+
+An application registers listeners with a `MongoClient` by configuring `MongoClientOptions` with instances of classes that
+implement the [`ConnectionPoolListener`]({{< apiref "com/mongodb/event/ConnectionPoolListener" >}}) interface.
+
+Consider the following, simplistic, example of a connection pool listener:
+
+```java
+public class TestConnectionPoolListener implements ConnectionPoolListener {
+    @Override
+    public void connectionPoolOpened(final ConnectionPoolOpenedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionPoolClosed(final ConnectionPoolClosedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionCheckedOut(final ConnectionCheckedOutEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionCheckedIn(final ConnectionCheckedInEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void waitQueueEntered(final ConnectionPoolWaitQueueEnteredEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void waitQueueExited(final ConnectionPoolWaitQueueExitedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionAdded(final ConnectionAddedEvent event) {
+        System.out.println(event);
+    }
+
+    @Override
+    public void connectionRemoved(final ConnectionRemovedEvent event) {
+        System.out.println(event);
+    }
+}
+```
+
+and an instance of `MongoClientOptions` configured with an instance of `TestConnectionPoolListener`:
+
+```java
+List<ServerAddress> seedList = ...
+MongoClientOptions options = MongoClientOptions.builder()
+                                      .addConnectionPoolListener(new TestConnectionPoolListener())
+                                      .build();
+MongoClient client = new MongoClient(new ServerAddress(), options);
+```
+
+A `MongoClient` configured with these options will print a message to `System.out` for each connection pool-related event for each MongoDB
+server to which the MongoClient is connected.
diff --git a/docs/reference/content/driver/tutorials/jndi.md b/docs/reference/content/driver/tutorials/jndi.md
@@ -28,7 +28,7 @@ The configuration of the `MongoClientFactory` differs depending on the applicati
 
         <module xmlns="urn:jboss:module:1.3" name="org.mongodb">
            <resources>
-               <resource-root path="mongo-java-driver-3.4.2.jar"/>
+               <resource-root path="mongo-java-driver-3.5.0.jar"/>
            </resources>
            <dependencies>
                <module name="javax.api"/>
diff --git a/docs/reference/content/driver/tutorials/ssl.md b/docs/reference/content/driver/tutorials/ssl.md
@@ -35,13 +35,33 @@ MongoClient mongoClient = new MongoClient(uri);
 import com.mongodb.MongoClientOptions;
 ```
 
-To specify TLS/SSL with with [`MongoClientOptions`]({{<apiref "com/mongodb/MongoClientOptions">}}), set the ``sslEnabled`` property to ``true``, as in:
+To specify TLS/SSL with with [`MongoClientOptions`]({{<apiref "com/mongodb/MongoClientOptions">}}), set the `sslEnabled` property to `true`, as in:
 
 ```java
  MongoClientOptions options = MongoClientOptions.builder().sslEnabled(true).build();
  MongoClient client = new MongoClient("localhost", options);
 ```
 
+## Specify `SSLContext` via `MongoClientOptions`
+
+```java
+import javax.net.ssl.SSLContext;
+import com.mongodb.MongoClientOptions;
+import com.mongodb.MongoClient;
+```
+
+To specify the [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) with 
+[`MongoClientOptions`]({{<apiref "com/mongodb/MongoClientOptions">}}), set the `sslContext` property, as in:
+
+```java
+ SSLContext sslContext = ...
+ MongoClientOptions options = MongoClientOptions.builder()
+                                                .sslEnabled(true)
+                                                .sslContext(sslContext)
+                                                .build();
+ MongoClient client = new MongoClient("localhost", options);
+```
+
 ## Disable Hostname Verification
 
 By default, the driver ensures that the hostname included in the
diff --git a/docs/reference/content/index.md b/docs/reference/content/index.md
@@ -6,12 +6,12 @@ type = "index"
 
 ## MongoDB Java Driver Documentation
 
-Welcome to the MongoDB Java driver documentation hub for the 3.4 driver release.
+Welcome to the MongoDB Java driver documentation hub for the 3.5 driver release.
 
 
-### What's New in 3.4
+### What's New in 3.5
 
-For key new features of 3.4, see [What's New]({{< relref "whats-new.md" >}}).
+For key new features of 3.5, see [What's New]({{< relref "whats-new.md" >}}).
 
 ### Upgrade
 
diff --git a/docs/reference/content/upgrading.md b/docs/reference/content/upgrading.md
@@ -2,19 +2,15 @@
 date = "2015-03-19T12:53:39-04:00"
 title = "Upgrade Considerations"
 [menu.main]
-  identifier = "Upgrading to 3.4"
+  identifier = "Upgrading to 3.5"
   weight = 80
   pre = "<i class='fa fa-level-up'></i>"
 +++
 
-## Upgrading from 3.3.x
+## Upgrading from 3.4.x
 
-There is one breaking API change in the 3.4 release: due to the addition of a new BSON type for 128-bit decimal values, a new method
-had to be added to the BSONCallback({{< apiref "org/bson/BSONCallback.html">}}) interface.  Any clients that directly implement that
-interface must add an implementation of the new method in order to be compatible with the 3.4 driver.
-
-Otherwise, the 3.4 release is binary and source compatible with the 3.3 release, except for methods that have been added to interfaces that
-have been marked as unstable.
+The 3.5 release is binary and source compatible with the 3.4 release, except for methods that have been added to interfaces that
+have been marked as unstable, and changes to classes or interfaces that have been marked as internal or annotated as Beta.
 
 ## Upgrading from 2.x
 
@@ -36,6 +32,7 @@ The following table specifies the compatibility of the MongoDB Java driver for u
 
 |Java Driver Version|MongoDB 2.6|MongoDB 3.0 |MongoDB 3.2|MongoDB 3.4|
 |-------------------|-----------|------------|-----------|-----------|
+|Version 3.5        |  ✓  |  ✓  |  ✓  |  ✓  |
 |Version 3.4        |  ✓  |  ✓  |  ✓  |  ✓  |
 |Version 3.3        |  ✓  |  ✓  |  ✓  |     |
 |Version 3.2        |  ✓  |  ✓  |  ✓  |     |
@@ -46,6 +43,7 @@ The following table specifies the compatibility of the MongoDB Java driver for u
 
 |Java Driver Version|Java 5 | Java 6 | Java 7 | Java 8 |
 |-------------------|-------|--------|--------|--------|
+|Version 3.5        |     | ✓ | ✓ | ✓ |
 |Version 3.4        |     | ✓ | ✓ | ✓ |
 |Version 3.3        |     | ✓ | ✓ | ✓ |
 |Version 3.2        |     | ✓ | ✓ | ✓ |
diff --git a/docs/reference/content/whats-new.md b/docs/reference/content/whats-new.md

Original file line number	Diff line number	Diff line change
`@@ -23,4 +23,4 @@ The MongoDB Async Driver requires either [Netty](http://netty.io/) or Java 7.`
`23`	`23`
`24`	`24`	`The MongoDB Async Driver provides asynchronous API that can leverage either Netty or Java 7's AsynchronousSocketChannel for fast and non-blocking I/O.`
`25`	`25`
`26`		`-{{< install artifactId="mongodb-driver-async" version="3.5.0-SNAPSHOT" dependencies="true">}}`
	`26`	`+{{< install artifactId="mongodb-driver-async" version="3.5.0" dependencies="true">}}`