DOCSP-48679: strongly recommend Netty (#124)

(cherry picked from commit 2f0b2ea)
(cherry picked from commit 39ea353)

Author: rustagir

snooty.toml

@@ -1,16 +1,14 @@
 name = "java-rs"
 title = "Java Reactive Streams Driver"
 
-intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
-                "https://www.mongodb.com/docs/atlas/objects.inv"
-              ]
+intersphinx = [
+    "https://www.mongodb.com/docs/manual/objects.inv",
+    "https://www.mongodb.com/docs/atlas/objects.inv",
+]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
-toc_landing_pages = [
-    "/tutorials/connect/",
-    "/tutorials/write-ops/",
-    ]
+toc_landing_pages = ["/tutorials/connect/", "/tutorials/write-ops/"]
 
 [constants]
 driver-short = "Java Reactive Streams driver"
@@ -20,3 +18,12 @@ full-version = "{+version+}.4"
 api = "https://mongodb.github.io/mongo-java-driver/{+version+}/apidocs"
 rs-docs = "https://www.reactive-streams.org/reactive-streams-1.0.4-javadoc/org/reactivestreams"
 driver-source-gh = "https://github.com/mongodb/mongo-java-driver"
+java-rs = "Java Reactive Streams"
+string-data-type = "``String``"
+bool = "``boolean``"
+pr = "Project Reactor"
+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/tutorials/connect/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:: Prefer Netty for Asynchronous Apps
+
+   We recommend using Netty for asychronous applications because it supports
+   asynchronous I/O 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
 -----------------------------