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.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 76390f1e5..34b71badd 100644 --- a/source/connection/network-compression.txt +++ b/source/connection/network-compression.txt @@ -1,95 +1,102 @@ -.. _compression: +.. _java-compression: .. _network-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 the Snappy, Zstandard, and Zlib 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/NetworkCompression.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/NetworkCompression.java + :start-after: start-specify-client-settings + :end-before: end-specify-client-settings + :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/NetworkCompression.java b/source/includes/connect/NetworkCompression.java new file mode 100644 index 000000000..5ef0fa5d0 --- /dev/null +++ b/source/includes/connect/NetworkCompression.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-client-settings +MongoClientSettings settings = MongoClientSettings.builder() + .compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(), + MongoCompressor.createZlibCompressor(), + MongoCompressor.createZstdCompressor())) + .build(); + +MongoClient client = MongoClients.create(settings); +// end-specify-client-settings \ No newline at end of file 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: