From d62e22e540855777bf210d04a3568b582cf2927a Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 12:17:45 -0500 Subject: [PATCH 1/6] DOCSP-47032: Network compression --- snooty.toml | 1 + source/connection/network-compression.txt | 120 +++++++++--------- .../includes/connect/network-compression.java | 16 +++ 3 files changed, 80 insertions(+), 57 deletions(-) create mode 100644 source/includes/connect/network-compression.java diff --git a/snooty.toml b/snooty.toml index 82b743182..a362f72bb 100644 --- a/snooty.toml +++ b/snooty.toml @@ -26,6 +26,7 @@ full-version = "{+version+}.0" mdb-server = "MongoDB Server" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" +core-api = "https://mongodb.github.io/mongo-java-driver/{+version+}/apidocs/mongodb-driver-core" stable-api = "Stable API" mongocrypt-version = "{+full-version+}" nettyVersion = "io.netty:netty-all:4.1.87.Final" diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index 76390f1e5..b66ab5b40 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -1,95 +1,101 @@ -.. _compression: -.. _network-compression: +.. _java-compression: -=================== -Network Compression -=================== +======================== +Compress Network Traffic +======================== -You can enable a driver option to compress messages which reduces the amount -of data passed over the network between MongoDB and your application. +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol -The driver supports the following algorithms: +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: zlib, zstandard, zstd, snappy -1. `Snappy `__: available in MongoDB 3.4 and later. +Overview +-------- -2. `Zlib `__: available in MongoDB 3.6 and later. +In this guide, you can learn how to use the {+driver-short+} to enable network +compression. The driver provides a connection option to compress messages, which +reduces the amount of data passed over the network between MongoDB and your application. -3. `Zstandard `__: available in MongoDB 4.2 and later. +The driver supports the following compression algorithms: + +- `Snappy `__: Available in {+mdb-server+} v3.4 and later. +- `Zlib `__: Available in {+mdb-server+} v3.6 and later. +- `Zstandard `__: Available in {+mdb-server+} v4.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 the MongoDB instance to which it is -connected. +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 ` for those - algorithms. + add explicit dependencies for those algorithms. To learn more, + see the :ref:`java-compression-dependencies` section of this guide. -.. _enable-compression: +.. _java-compression-specify: Specify Compression Algorithms ------------------------------ You can enable compression for the connection to your MongoDB instance -by specifying the algorithms in one of two ways: adding the parameter to your -connection string using ``ConnectionString`` or by calling the method in the -``MongoClientSettings.Builder`` class. - -.. tabs:: +by specifying the algorithms in one of the following ways: - .. tab:: ConnectionString - :tabid: connectionstring - - To enable compression using the `ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__, - add the parameter ``compressors`` in the connection string passed to - ``MongoClients.create()``. You can specify one or more compression - algorithms, separating them with commas: +- Use the ``compressors`` parameter in your connection string +- Chain the ``compressorList`` method to the ``MongoClientSettings.builder()`` method - .. code-block:: java +This example shows how to specify all compression algorithms. Select the +:guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to +see the corresponding syntax: - ConnectionString connectionString = new ConnectionString("mongodb+srv://:@/?compressors=snappy,zlib,zstd"); - MongoClient mongoClient = MongoClients.create(connectionString); +.. tabs:: - Specify compression algorithms using the following strings: + .. tab:: Connection String + :tabid: connectionstring - - "snappy" for `Snappy `__ compression - - "zlib" for `Zlib `__ compression - - "zstd" for `Zstandard `__ compression + .. literalinclude:: /includes/connect/network-compression.java + :start-after: start-specify-connection-string + :end-before: end-specify-connection-string + :language: java .. tab:: MongoClientSettings :tabid: mongoclientsettings - To enable compression using the `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__, - pass the `compressorList() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#compressorList(java.util.List)>`__ - builder method a list of `MongoCompressor <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCompressor.html>`__ - instances. You can specify one or more compression algorithms in the list: - - .. code-block:: java - :emphasize-lines: 2-4 - - MongoClientSettings settings = MongoClientSettings.builder() - .compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(), - MongoCompressor.createZlibCompressor(), - MongoCompressor.createZstdCompressor())) - .build(); - MongoClient client = MongoClients.create(settings); + .. literalinclude:: /includes/connect/network-compression.java + :start-after: start-specify-uri + :end-before: end-specify-uri + :language: java -.. _compression-dependencies: +.. _java-compression-dependencies: Compression Algorithm Dependencies ---------------------------------- -The JDK supports `Zlib `__ compression natively, but -`Snappy `__ and -`Zstandard `__ depend on open source -implementations. See -`snappy-java `__ and -`zstd-java `__ for details. +The JDK natively supports `Zlib `__ compression. However, +Snappy and Zstandard depend on open source Java implementations. To learn more +about these implementations, see the following Github repositories: + +- `snappy-java `__ +- `zstd-java `__ + +API Documentation +----------------- +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `createSnappyCompressor() <{+core-api+}/com/mongodb/MongoCompressor.html#createSnappyCompressor()>`__ +- `createZlibCompressor() <{+core-api+}/com/mongodb/MongoCompressor.html#createZlibCompressor()>`__ +- `createZstdCompressor() <{+core-api+}/com/mongodb/MongoCompressor.html#createZstdCompressor()>`__ \ No newline at end of file diff --git a/source/includes/connect/network-compression.java b/source/includes/connect/network-compression.java new file mode 100644 index 000000000..2461ea265 --- /dev/null +++ b/source/includes/connect/network-compression.java @@ -0,0 +1,16 @@ +// start-specify-connection-string +ConnectionString connectionString = new ConnectionString( + "mongodb+srv://:@/?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 \ No newline at end of file From 6185da045537c94e8a6a0139acff62badbbaf972 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 13:12:45 -0500 Subject: [PATCH 2/6] fixes --- source/connection.txt | 2 +- source/connection/network-compression.txt | 8 ++++---- source/versioning/whats-new.txt | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/connection.txt b/source/connection.txt index d34dc63f2..a4a40d423 100644 --- a/source/connection.txt +++ b/source/connection.txt @@ -31,7 +31,7 @@ sections: - :ref:`Connect to MongoDB ` - :ref:`View a List of Connection Options ` - :ref:`Specify Connection Behavior with the MongoClient Class ` -- :ref:`Enable Network Compression ` +- :ref:`Enable Network Compression ` - :ref:`Enable TLS/SSL on a Connection ` - :ref:`Connect to MongoDB by Using a SOCKS5 Proxy ` - :ref:`Connect to MongoDB by Using a JNDI Datasource ` diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index b66ab5b40..5080e64c8 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -53,11 +53,11 @@ You can enable compression for the connection to your MongoDB instance by specifying the algorithms in one of the following ways: - Use the ``compressors`` parameter in your connection string -- Chain the ``compressorList`` method to the ``MongoClientSettings.builder()`` method +- Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method -This example shows how to specify all compression algorithms. Select the -:guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to -see the corresponding syntax: +This example shows how to specify the Snappy, Zstandard, and Zlib compression +algorithms. Select thev:guilabel:`Connection String` or :guilabel:`MongoClientSettings` +tab to see the corresponding syntax: .. tabs:: diff --git a/source/versioning/whats-new.txt b/source/versioning/whats-new.txt index 129e425b2..96382a091 100644 --- a/source/versioning/whats-new.txt +++ b/source/versioning/whats-new.txt @@ -420,7 +420,7 @@ New features of the 4.11 driver release include: - Added Atlas Search index management helpers. To learn more, see :ref:`Atlas Search Indexes `. - Updated Snappy and Zstd compression library dependency versions. To learn - more about the current dependency versions, see :ref:`network-compression`. + more about the current dependency versions, see :ref:`java-compression`. - Added ``getElapsedTime()`` methods to the following classes to monitor the duration of connection pool events: From c17d0256569d96053904fc96edca8f5bb7979450 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 13:14:11 -0500 Subject: [PATCH 3/6] typo --- source/connection/network-compression.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index 5080e64c8..b60e35465 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -56,7 +56,7 @@ by specifying the algorithms in one of the following ways: - Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method This example shows how to specify the Snappy, Zstandard, and Zlib compression -algorithms. Select thev:guilabel:`Connection String` or :guilabel:`MongoClientSettings` +algorithms. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the corresponding syntax: .. tabs:: From c2ea31d2094e9fdf39ca33e4d51f051ce4eb3304 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 16:37:33 -0500 Subject: [PATCH 4/6] LM feedback --- source/connection/network-compression.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index b60e35465..b76562754 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -52,8 +52,8 @@ Specify Compression Algorithms You can enable compression for the connection to your MongoDB instance by specifying the algorithms in one of the following ways: -- Use the ``compressors`` parameter in your connection string -- Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method +- Use the ``compressors`` parameter in your connection string. +- Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method. This example shows how to specify the Snappy, Zstandard, and Zlib compression algorithms. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` From a1c90a270ea27e8f2580dac8d7c6dfca727bd574 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 5 Mar 2025 11:03:36 -0500 Subject: [PATCH 5/6] change file name --- source/connection/network-compression.txt | 5 +++-- .../{network-compression.java => NetworkCompression.java} | 0 2 files changed, 3 insertions(+), 2 deletions(-) rename source/includes/connect/{network-compression.java => NetworkCompression.java} (100%) diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index b76562754..310ffb96a 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -1,4 +1,5 @@ .. _java-compression: +.. _network-compression: ======================== Compress Network Traffic @@ -64,7 +65,7 @@ tab to see the corresponding syntax: .. tab:: Connection String :tabid: connectionstring - .. literalinclude:: /includes/connect/network-compression.java + .. literalinclude:: /includes/connect/NetworkCompression.java :start-after: start-specify-connection-string :end-before: end-specify-connection-string :language: java @@ -72,7 +73,7 @@ tab to see the corresponding syntax: .. tab:: MongoClientSettings :tabid: mongoclientsettings - .. literalinclude:: /includes/connect/network-compression.java + .. literalinclude:: /includes/connect/NetworkCompression.java :start-after: start-specify-uri :end-before: end-specify-uri :language: java diff --git a/source/includes/connect/network-compression.java b/source/includes/connect/NetworkCompression.java similarity index 100% rename from source/includes/connect/network-compression.java rename to source/includes/connect/NetworkCompression.java From 3dda87ad12554a09f1fe8415865dce37315bfc52 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 5 Mar 2025 16:32:28 -0500 Subject: [PATCH 6/6] tech feedback --- source/connection/network-compression.txt | 6 +++--- source/includes/connect/NetworkCompression.java | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connection/network-compression.txt b/source/connection/network-compression.txt index 310ffb96a..34b71badd 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -74,8 +74,8 @@ tab to see the corresponding syntax: :tabid: mongoclientsettings .. literalinclude:: /includes/connect/NetworkCompression.java - :start-after: start-specify-uri - :end-before: end-specify-uri + :start-after: start-specify-client-settings + :end-before: end-specify-client-settings :language: java .. _java-compression-dependencies: @@ -85,7 +85,7 @@ Compression Algorithm Dependencies The JDK natively supports `Zlib `__ compression. However, Snappy and Zstandard depend on open source Java implementations. To learn more -about these implementations, see the following Github repositories: +about these implementations, see the following GitHub repositories: - `snappy-java `__ - `zstd-java `__ diff --git a/source/includes/connect/NetworkCompression.java b/source/includes/connect/NetworkCompression.java index 2461ea265..5ef0fa5d0 100644 --- a/source/includes/connect/NetworkCompression.java +++ b/source/includes/connect/NetworkCompression.java @@ -5,7 +5,7 @@ MongoClient client = MongoClients.create(connectionString); // end-specify-connection-string -// start-specify-uri +// start-specify-client-settings MongoClientSettings settings = MongoClientSettings.builder() .compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(), MongoCompressor.createZlibCompressor(), @@ -13,4 +13,4 @@ .build(); MongoClient client = MongoClients.create(settings); -// end-specify-uri \ No newline at end of file +// end-specify-client-settings \ No newline at end of file