DOCSP-39689 Network Compression standardization

snooty.toml

@@ -1,9 +1,10 @@
 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/"
 
@@ -29,4 +30,6 @@ string-data-type = "``String``"
 bool = "``boolean``"
 pr = "Project Reactor"
 mdb-server = "MongoDB Server"
-stable-api = "Stable API"
+snappyVersion = "org.xerial.snappy:snappy-java:1.1.10.3"
+zstdVersion = "com.github.luben:zstd-jni:1.5.5-3"
+stable-api = "Stable API"

source/connect-to-mongo/network-compression.txt

@@ -0,0 +1,98 @@
+.. _java-rs-compression:
+.. _java-rs-network-compression:
+
+========================
+Compress Network Traffic
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: zlib, zstandard, zstd, snappy
+
+The {+driver-short+} provides a connection option to compress messages, which reduces the amount
+of data passed over the network between MongoDB and your application.
+
+The driver supports the following algorithms:
+
+- `Snappy <https://google.github.io/snappy/>`__: available in MongoDB 3.4 and later.
+- `Zlib <https://zlib.net/>`__: available in MongoDB 3.6 and later.
+- `Zstandard <https://github.com/facebook/zstd/>`__: available in MongoDB 4.2 and later.
+
+The driver tests against the following versions of these libraries:
+
+- ``{+snappyVersion+}``
+- ``{+zstdVersion+}``
+
+If you specify multiple compression algorithms, the driver selects the first one
+in the list supported by your MongoDB instance.
+
+.. note::
+
+   Applications that require Snappy or Zstandard compression must
+   :ref:`add explicit dependencies <java-rs-compression-dependencies>` for those
+   algorithms.
+
+.. _enable-compression:
+
+Specify Compression Algorithms
+------------------------------
+
+You can enable compression for the connection to your MongoDB instance
+by specifying the algorithms in one of two ways. Select the
+:guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
+see the corresponding syntax:
+
+- In the ``compressors`` parameter of your connection string
+- In the ``compressorList`` method chained to the ``MongoClientSettings.builder()`` method
+
+The following example shows how to specify all compression algorithms:
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/connect/network-compression.java
+         :start-after: start-specify-connection-string
+         :end-before: end-specify-connection-string
+         :language: java
+
+   .. tab:: MongoClientSettings
+      :tabid: mongoclientsettings
+
+      .. literalinclude:: /includes/connect/network-compression.java
+         :start-after: start-specify-uri
+         :end-before: end-specify-uri
+         :language: java
+
+.. _java-rs-compression-dependencies:
+
+Compression Algorithm Dependencies
+----------------------------------
+
+The JDK natively supports `Zlib <https://zlib.net/>`__ compression. However,
+Snappy and Zstandard depend on open source Java implementations. To learn more
+about these implementations, see the following Github pages:
+
+- `snappy-java <https://github.com/xerial/snappy-java>`__
+- `zstd-java <https://github.com/luben/zstd-jni>`__
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `MongoClient <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClient.html>`__
+- `createSnappyCompressor() <{+api+}/mongodb-driver-core/com/mongodb/MongoCompressor.html#createSnappyCompressor()>`__
+- `createZlibCompressor() <{+api+}//mongodb-driver-core/com/mongodb/MongoCompressor.html#createZlibCompressor()>`__
+- `createZstdCompressor() <{+api+}/mongodb-driver-core/com/mongodb/MongoCompressor.html#createZstdCompressor()>`__

source/connect.txt

@@ -26,7 +26,7 @@ Connect to MongoDB
    /connect-to-mongo/choose-connection-target/
    /connect-to-mongo/connection-options/
    /connect-to-mongo/tls/
-   /connect-to-mongo/compression/
+   /connect-to-mongo/network-compression
    /connect-to-mongo/stable-api/
 
 Overview

source/includes/connect/network-compression.java

@@ -0,0 +1,16 @@
+// start-specify-connection-string
+ConnectionString connectionString = new ConnectionString(
+        "mongodb+srv://<db_username>:<db_password>@<cluster-url>/?compressors=snappy,zlib,zstd");
+
+MongoClient client = MongoClients.create(connectionString);
+// end-specify-connection-string
+
+// start-specify-uri
+MongoClientSettings settings = MongoClientSettings.builder()
+        .compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(),
+                MongoCompressor.createZlibCompressor(),
+                MongoCompressor.createZstdCompressor()))
+        .build();
+
+MongoClient client = MongoClients.create(settings);
+// end-specify-uri