DOCSP-48679: strongly recommend Netty

snooty.toml

@@ -36,3 +36,4 @@ mdb-server = "MongoDB Server"
 snappyVersion = "org.xerial.snappy:snappy-java:1.1.10.3"
 zstdVersion = "com.github.luben:zstd-jni:1.5.5-3"
 stable-api = "Stable API"
+netty-version = "io.netty:netty-all:4.1.87.Final"

source/connect-to-mongo/tls.txt

@@ -17,11 +17,27 @@ TLS/SSL
    :depth: 2
    :class: singlecol
 
+Overview
+--------
+
+In this guide, you can learn how to use the **TLS protocol** to secure your
+connection to a MongoDB deployment. TLS is a cryptographic protocol that
+secures communication between your application and MongoDB. To configure
+your connection to use TLS, enable the TLS option and provide your
+certificates for validation when creating a client.
+
 By default, the driver supports TLS/SSL connections to MongoDB
 servers using the underlying support for TLS/SSL provided by the JDK.
-This can be changed either by utilizing the extensibility of the `Java SE
-API <https://docs.oracle.com/javase/8/docs/api/>`__, or by using the
-`Netty API <https://netty.io/4.1/api/>`__.
+This can be changed either by using the `Netty API
+<https://netty.io/4.1/api/>`__ or the extensibility of the `Java SE
+API <https://docs.oracle.com/javase/8/docs/api/>`__.
+
+.. tip::
+
+   We recommend using Netty for asychronous applications, as it supports
+   asynchronous IO and handles high connection volumes effectively. To
+   learn about using Netty to configure your TLS settings, see the
+   :ref:`java-rs-tls-netty-config` section of this guide.
 
 MongoClient API
 ---------------
@@ -68,30 +84,10 @@ To specify TLS/SSL in a ``MongoClientSettings`` instance, set the
        .build();
    MongoClient client = MongoClients.create(settings);
 
-Specify Java SE SSLContext in MongoClientSettings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Include the following import statements:
-
-.. code-block:: java
-
-   import javax.net.ssl.SSLContext;
-   import com.mongodb.MongoClientSettings;
-   import com.mongodb.MongoClient;
-
-To specify the ``javax.net.ssl.SSLContext`` with
-``MongoClientSettings``, set the ``sslContext`` property:
-
-.. code-block:: java
-
-   SSLContext sslContext = ...
-   MongoClientSettings settings = MongoClientSettings.builder()
-       .applyToSslSettings(builder -> builder.enabled(true).context(sslContext))
-       .build();
-   MongoClient client = new MongoClient(settings);
+.. _java-rs-tls-netty-config:
 
-Customize TLS/SSL Configuration through the Netty SslContext
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configure TLS/SSL by Using Netty SslContext
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Include the following import statements:
 
@@ -105,9 +101,9 @@ Include the following import statements:
    import io.netty.handler.ssl.SslContextBuilder;
    import io.netty.handler.ssl.SslProvider;
 
-.. note::
+.. note:: Netty Package Version
 
-   The driver tests with Netty version ``io.netty:netty-all:4.1.87.Final``
+   The driver tests with Netty package version ``{+netty-version+}``
 
 To instruct the driver to use
 `io.netty.handler.ssl.SslContext <https://netty.io/4.1/api/io/netty/handler/ssl/SslContext.html>`__,
@@ -118,21 +114,46 @@ Use ``MongoClientSettings.Builder.transportSettings()``
 and ``NettyTransportSettings.Builder.sslContext()`` to build your settings:
 
 .. code-block:: java
+   :emphasize-lines: 7-9
 
    SslContext sslContext = SslContextBuilder.forClient()
            .sslProvider(SslProvider.OPENSSL)
            .build();
+
    MongoClientSettings settings = MongoClientSettings.builder()
            .applyToSslSettings(builder -> builder.enabled(true))
            .transportSettings(TransportSettings.nettyBuilder()
                               .sslContext(sslContext)
                               .build())
            .build();
+
    MongoClient client = MongoClients.create(settings);
 
 For more details about the ``io.netty.handler.ssl.SslProvider``, see the `Netty
 documentation <https://netty.io/4.1/api/io/netty/handler/ssl/SslProvider.html>`__.
 
+Specify Java SE SSLContext in MongoClientSettings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Include the following import statements:
+
+.. code-block:: java
+
+   import javax.net.ssl.SSLContext;
+   import com.mongodb.MongoClientSettings;
+   import com.mongodb.MongoClient;
+
+To specify the ``javax.net.ssl.SSLContext`` with
+``MongoClientSettings``, set the ``sslContext`` property:
+
+.. code-block:: java
+
+   SSLContext sslContext = ...
+   MongoClientSettings settings = MongoClientSettings.builder()
+       .applyToSslSettings(builder -> builder.enabled(true).context(sslContext))
+       .build();
+   MongoClient client = new MongoClient(settings);
+
 Disable Hostname Verification
 -----------------------------