Skip to content

Commit 7fb6948

Browse files
mongodbenrustagircbullinger
authored
(DOCSP-29268): Kotlin Network compression page (#77)
# Pull Request Info [PR Reviewing Guidelines](https://github.com/mongodb/docs-java/blob/master/REVIEWING.md) JIRA - https://jira.mongodb.org/browse/DOCSP-29268 [Staging](https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/DOCSP-29268/fundamentals/connection/network-compression/) ## Self-Review Checklist - [x] Is this free of any warnings or errors in the RST? - [x] Did you run a spell-check? - [ ] Did you run a grammar-check? - [x] Are all the links working? --------- Co-authored-by: Rea Radhika Rustagi <[email protected]> Co-authored-by: cbullinger <[email protected]> Co-authored-by: Rea Rustagi <[email protected]>
1 parent 56161f2 commit 7fb6948

10 files changed

+241
-19
lines changed

‎examples/build.gradle.kts

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,17 @@ repositories {
1616

1717
dependencies {
1818
implementation("org.mongodb:mongodb-driver-kotlin-coroutine:$kotlin_mongodb_version")
19-
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
19+
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1")
2020
testImplementation(kotlin("test"))
2121
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0-Beta")
2222
implementation("org.mongodb:mongodb-driver-kotlin-coroutine:4.10.0-SNAPSHOT")
23-
implementation("org.slf4j:slf4j-api:1.7.32")
24-
implementation("ch.qos.logback:logback-classic:1.2.6")
23+
implementation("org.slf4j:slf4j-api:2.0.5")
24+
implementation("ch.qos.logback:logback-classic:1.4.7")
2525
implementation("io.github.cdimascio:dotenv-kotlin:6.4.1")
2626
implementation("io.netty:netty-all:4.1.91.Final")
27-
implementation("io.netty:netty-tcnative-boringssl-static:2.0.53.Final:${osdetector.classifier}")
27+
implementation("io.netty:netty-tcnative-boringssl-static:2.0.59.Final:${osdetector.classifier}")
28+
implementation("org.xerial.snappy:snappy-java:1.1.10.0")
29+
implementation("com.github.luben:zstd-jni:1.5.5-4")
2830
}
2931

3032
tasks.test {

‎examples/src/test/kotlin/AggExpressionsTest.kt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ import com.mongodb.client.model.mql.*
77
import com.mongodb.client.model.mql.MqlValues.current
88
import com.mongodb.client.model.mql.MqlValues.of
99
import com.mongodb.kotlin.client.coroutine.MongoClient
10-
import io.github.cdimascio.dotenv.dotenv
1110
import kotlinx.coroutines.flow.toList
1211
import kotlinx.coroutines.runBlocking
1312
import org.bson.Document

‎examples/src/test/kotlin/CollationsTest.kt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

22
import com.mongodb.client.model.*
33
import com.mongodb.kotlin.client.coroutine.MongoClient
4-
import io.github.cdimascio.dotenv.dotenv
4+
import config.getConfig
55
import kotlinx.coroutines.flow.first
66
import kotlinx.coroutines.flow.toList
77
import kotlinx.coroutines.runBlocking
@@ -28,8 +28,8 @@ internal class CollationTest {
2828
// :snippet-end:
2929

3030
companion object {
31-
val dotenv = dotenv()
32-
val client: MongoClient = MongoClient.create(dotenv["MONGODB_CONNECTION_URI"])
31+
val config = getConfig()
32+
val client: MongoClient = MongoClient.create(config.connectionUri)
3333
val database = client.getDatabase("example_db")
3434
val nameCollection = database.getCollection<FirstName>("names")
3535
val collationExampleCollection = database.getCollection<CollationExample>("collation_examples")

‎examples/src/test/kotlin/NetworkCompressionTest.kt

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
import com.mongodb.*
2+
import com.mongodb.kotlin.client.coroutine.MongoClient
3+
import config.getConfig
4+
import kotlinx.coroutines.runBlocking
5+
import org.bson.BsonInt64
6+
import org.bson.Document
7+
import org.junit.jupiter.api.AfterAll
8+
import org.junit.jupiter.api.Assertions.*
9+
import org.junit.jupiter.api.TestInstance
10+
import java.util.*
11+
import kotlin.test.*
12+
13+
14+
// :replace-start: {
15+
// "terms": {
16+
// "CONNECTION_URI_PLACEHOLDER": "\"<connection string>\"",
17+
// "${uri}&": "mongodb+srv://<user>:<password>@<cluster-url>/?"
18+
// }
19+
// }
20+
21+
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
22+
internal class NetworkCompressionTest {
23+
24+
/* NOTE: Network compression tests are not run by default. To run these tests,
25+
* you need access to a deployment that has a username and password.
26+
* Set up your .env variable with this connection string, then replace
27+
* the @Ignore annotation with @Test on the tests you want to run.
28+
*/
29+
30+
companion object {
31+
private val config = getConfig()
32+
val CONNECTION_URI_PLACEHOLDER = config.connectionUri
33+
var higherScopedClient: MongoClient? = null
34+
35+
@AfterAll
36+
@JvmStatic
37+
fun afterAll() {
38+
runBlocking {
39+
higherScopedClient?.close()
40+
}
41+
}
42+
}
43+
44+
@Ignore
45+
fun connectionStringCompressionTest() = runBlocking {
46+
47+
val uri = CONNECTION_URI_PLACEHOLDER
48+
// :snippet-start: connection-string-compression-example
49+
// Replace the placeholders with values from your MongoDB deployment's connection string
50+
val connectionString = ConnectionString("${uri}&compressors=snappy,zlib,zstd")
51+
52+
lateinit var higherScopedCommandResult: Document // :remove:
53+
// Create a new client with your settings
54+
val mongoClient = MongoClient.create(connectionString)
55+
// :snippet-end:
56+
val database = mongoClient.getDatabase("admin")
57+
try {
58+
// Send a ping to confirm a successful connection
59+
val command = Document("ping", BsonInt64(1))
60+
val commandResult = database.runCommand(command)
61+
println("Pinged your deployment. You successfully connected to MongoDB!")
62+
higherScopedCommandResult = commandResult
63+
} catch (me: MongoException) {
64+
System.err.println(me)
65+
}
66+
higherScopedClient = mongoClient
67+
assertEquals(1, higherScopedCommandResult["ok"].toString().toInt())
68+
}
69+
70+
@Ignore
71+
fun mongoClientSettingsCompressionTest() = runBlocking {
72+
73+
// :snippet-start: mongoclientsettings-compression-example
74+
// Replace the placeholder with your MongoDB deployment's connection string
75+
val uri = CONNECTION_URI_PLACEHOLDER
76+
77+
val settings = MongoClientSettings.builder()
78+
.applyConnectionString(ConnectionString(uri))
79+
.compressorList(
80+
listOf(
81+
MongoCompressor.createSnappyCompressor(),
82+
MongoCompressor.createZlibCompressor(),
83+
MongoCompressor.createZstdCompressor())
84+
)
85+
.build()
86+
87+
lateinit var higherScopedCommandResult: Document // :remove:
88+
// Create a new client with your settings
89+
val mongoClient = MongoClient.create(settings)
90+
// :snippet-end:
91+
val database = mongoClient.getDatabase("admin")
92+
try {
93+
// Send a ping to confirm a successful connection
94+
val command = Document("ping", BsonInt64(1))
95+
val commandResult = database.runCommand(command)
96+
println("Pinged your deployment. You successfully connected to MongoDB!")
97+
higherScopedCommandResult = commandResult
98+
} catch (me: MongoException) {
99+
System.err.println(me)
100+
}
101+
higherScopedClient = mongoClient
102+
assertEquals(1, higherScopedCommandResult["ok"].toString().toInt())
103+
}
104+
}
105+
// :replace-end:

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,6 @@ stable-api = "Stable API"
3131
mongocrypt-version = "1.7.3"
3232
nettyVersion = "io.netty:netty-all:4.1.79.Final"
3333
snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4"
34-
zstdVersion = "com.github.luben:zstd-jni:1.5.2-3"
34+
zstdVersion = "com.github.luben:zstd-jni:1.5.5-2"
3535
logbackVersion = "1.2.11"
3636
log4j2Version = "2.17.1"

‎source/examples/generated/NetworkCompressionTest.snippet.connection-string-compression-example.kt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Replace the placeholders with values from your MongoDB deployment's connection string
2+
val connectionString = ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd")
3+
4+
// Create a new client with your settings
5+
val mongoClient = MongoClient.create(connectionString)

‎source/examples/generated/NetworkCompressionTest.snippet.mongoclientsettings-compression-example.kt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Replace the placeholder with your MongoDB deployment's connection string
2+
val uri = "<connection string>"
3+
4+
val settings = MongoClientSettings.builder()
5+
.applyConnectionString(ConnectionString(uri))
6+
.compressorList(
7+
listOf(
8+
MongoCompressor.createSnappyCompressor(),
9+
MongoCompressor.createZlibCompressor(),
10+
MongoCompressor.createZstdCompressor())
11+
)
12+
.build()
13+
14+
// Create a new client with your settings
15+
val mongoClient = MongoClient.create(settings)

‎source/fundamentals/connection.txt

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Connection Guide
99
/fundamentals/connection/connect
1010
/fundamentals/connection/connection-options
1111
/fundamentals/connection/mongoclientsettings
12+
/fundamentals/connection/network-compression
1213
/fundamentals/connection/tls
1314

1415
.. contents:: On this page
@@ -27,11 +28,9 @@ sections:
2728
- :ref:`Connect to MongoDB <connect-to-mongodb>`
2829
- :ref:`View a List of Connection Options <connection-options>`
2930
- :ref:`Specify Connection Behavior with the MongoClient Class <specify-mongoclient-settings>`
31+
- :ref:`Enable Network Compression <network-compression>`
3032
- :ref:`Enable TLS/SSL on a Connection <tls-ssl>`
3133

32-
.. TODO:(DOCSP-29268) Add enable network compression back
33-
.. - :ref:`Enable Network Compression <network-compression>`
34-
3534
.. TODO:(DOCSP-29261) Add auth docs back in
3635
.. For information about authenticating with a MongoDB instance,
3736
.. see :ref:`<authentication-mechanisms>` and :ref:`<enterprise-authentication-mechanisms>`.

‎source/fundamentals/connection/mongoclientsettings.txt

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -96,12 +96,8 @@ connection behavior:
9696
- Sets the :ref:`command listeners <command-events-kotlin>`.
9797

9898
* - ``compressorList()``
99-
- Sets the compressors to use for compressing
100-
messages to the server. (`Reference docs <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#compressorList(java.util.List)>`__
101-
102-
.. TODO(DOCSP-29268) set sentence above to
103-
.. Sets the :ref:`compressors <compression>` to use for compressing
104-
.. messages to the server.
99+
- Sets the :ref:`compressors <network-compression>` to use for compressing
100+
messages to the server.
105101

106102
* - ``credential()``
107103
- Sets the :ref:`credential <authentication-mechanisms-kotlin>`. (`Reference docs <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#credential(com.mongodb.MongoCredential)>`__
@@ -396,7 +392,6 @@ settings to modify the driver's behavior:
396392
- Sets the minimum amount of connections associated with a connection
397393
pool.
398394

399-
400395
.. note::
401396

402397
This ``maxSize`` and ``minSize`` settings apply to each server

‎source/fundamentals/connection/network-compression.txt

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
.. _compression:
2+
.. _network-compression:
3+
4+
===================
5+
Network Compression
6+
===================
7+
8+
.. contents:: On this page
9+
:local:
10+
:backlinks: none
11+
:depth: 1
12+
:class: singlecol
13+
14+
The {+driver-long+} provides a connection option to compress messages,
15+
This reduces the amount of data passed over the network between MongoDB
16+
and your application.
17+
18+
The driver supports the following algorithms:
19+
20+
1. `Snappy <https://google.github.io/snappy/>`__: available in MongoDB 3.4 and later.
21+
#. `Zlib <https://zlib.net/>`__: available in MongoDB 3.6 and later.
22+
#. `Zstandard <https://github.com/facebook/zstd/>`__: available in MongoDB 4.2 and later.
23+
24+
The driver tests against the following versions of these libraries:
25+
26+
- ``{+snappyVersion+}``
27+
- ``{+zstdVersion+}``
28+
29+
If you specify multiple compression algorithms, the driver selects the
30+
first one that is supported by the MongoDB instance that the driver is
31+
connected to.
32+
33+
.. note::
34+
35+
If your application requires Snappy or Zstandard compression, you must add
36+
:ref:`explicit dependencies <compression-dependencies>` for those algorithms.
37+
38+
.. _enable-compression:
39+
40+
Specify Compression Algorithms
41+
------------------------------
42+
43+
You can enable compression on your connection by specifying the
44+
algorithms in the following ways:
45+
46+
- Adding the ``compressors`` parameter to your ``ConnectionString`` instance
47+
- Calling the ``compressorList()`` method from the ``MongoClientSettings`` builder
48+
49+
.. tabs::
50+
51+
.. tab:: ConnectionString
52+
:tabid: specify compressors in connection string
53+
54+
To enable compression on your connection in a `ConnectionString
55+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
56+
instance, specify the ``compressors`` parameter. You can specify
57+
one or more of the following values for the ``compressors`` parameter:
58+
59+
- ``"snappy"`` for `Snappy <https://google.github.io/snappy/>`__ compression
60+
- ``"zlib"`` for `Zlib <https://zlib.net/>`__ compression
61+
- ``"zstd"`` for `Zstandard <https://github.com/facebook/zstd/>`__ compression
62+
63+
The following example shows how to specify Snappy, Zlib, and
64+
Zstandard as the compression algorithms for a connection:
65+
66+
.. literalinclude:: /examples/generated/NetworkCompressionTest.snippet.connection-string-compression-example.kt
67+
:language: kotlin
68+
:emphasize-lines: 2
69+
70+
.. tab:: MongoClientSettings
71+
:tabid: specify compressors in MongoClientSettings
72+
73+
To enable compression using within your `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__,
74+
call the `compressorList() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#compressorList(java.util.List)>`__
75+
builder method and pass one or more `MongoCompressor <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCompressor.html>`__
76+
instances as a parameter.
77+
78+
You can specify compression algorithms by calling the following
79+
methods from ``MongoCompressor``:
80+
81+
- ``createSnappyCompressor()`` for `Snappy <https://google.github.io/snappy/>`__ compression
82+
- ``createZlibCompressor()`` for `Zlib <https://zlib.net/>`__ compression
83+
- ``createZstdCompressor()`` for `Zstandard <https://github.com/facebook/zstd/>`__ compression
84+
85+
The following example shows how to specify Snappy, Zlib, and
86+
Zstandard as the compression algorithms for a connection:
87+
88+
.. literalinclude:: /examples/generated/NetworkCompressionTest.snippet.mongoclientsettings-compression-example.kt
89+
:language: kotlin
90+
:emphasize-lines: 8-10
91+
92+
.. _compression-dependencies:
93+
94+
Compression Algorithm Dependencies
95+
----------------------------------
96+
97+
The JDK supports `Zlib <https://zlib.net/>`__ compression natively, but
98+
`Snappy <https://google.github.io/snappy/>`__ and
99+
`Zstandard <https://github.com/facebook/zstd/>`__ depend on open source
100+
implementations. See
101+
`snappy-java <https://github.com/xerial/snappy-kotlin>`__ and
102+
`zstd-java <https://github.com/luben/zstd-jni>`__ for details.

0 commit comments

Comments
 (0)