diff --git a/source/connect.txt b/source/connect.txt index 288ad111..e1a34974 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -18,9 +18,11 @@ Connect to MongoDB :description: Learn how to use the Kotlin Sync driver to connect to MongoDB. :keywords: client, ssl, tls, localhost -.. .. toctree:: -.. :titlesonly: -.. :maxdepth: 1 +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /connect/stable-api .. .. /connect/mongoclient .. /connect/connection-targets @@ -28,7 +30,6 @@ Connect to MongoDB .. /connect/tls .. /connect/network-compression .. /connect/server-selection -.. /connect/stable-api .. /connect/csot Overview diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt new file mode 100644 index 00000000..9c17b6e3 --- /dev/null +++ b/source/connect/stable-api.txt @@ -0,0 +1,135 @@ +.. _kotlin-sync-stable-api: + +============== +{+stable-api+} +============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: compatible, backwards, upgrade + +.. note:: + + The {+stable-api+} feature requires {+mdb-server+} 5.0 or later. + +Overview +-------- + +In this guide, you can learn how to specify **{+stable-api+}** compatibility when +connecting to a MongoDB deployment. + +The {+stable-api+} feature forces the server to run operations with behaviors compatible +with the API version you specify. When you update either your driver or server, +the API version changes, which can change the way these operations behave. +Using the {+stable-api+} ensures consistent responses from the server and +provides long-term API stability for your application. + +The following sections describe how you can enable and customize {+stable-api+} for +your MongoDB client. For more information about the {+stable-api+}, including a list of +the commands it supports, see :manual:`Stable API ` in the +{+mdb-server+} manual. + +Enable the {+stable-api+} +------------------------- + +To enable the {+stable-api+}, perform the following steps: + +1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use + a {+stable-api+} version defined in the ``ServerApiVersion`` enum. +#. Construct a ``MongoClientSettings`` object using the ``MongoClientSettings.Builder`` class. +#. Instantiate a ``MongoClient`` using the ``MongoClient.create()`` method and + pass your ``MongoClientSettings`` instance as a parameter. + +The following code example shows how to specify {+stable-api+} version 1: + +.. literalinclude:: /includes/connect/stable-api.kt + :start-after: start-enable-stable-api + :end-before: end-enable-stable-api + :language: kotlin + :copyable: + :dedent: + +Once you create a ``MongoClient`` instance with +a specified API version, all commands you run with the client use the specified +version. If you must run commands using more than one version of the +{+stable-api+}, create a new ``MongoClient``. + +.. _stable-api-options: + +Configure the {+stable-api+} +---------------------------- + +The following table describes the parameters of the ``ServerApi`` class. You can use these +parameters to customize the behavior of the {+stable-api+}. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 25,75 + + * - Option Name + - Description + + * - strict + - | **Optional**. When ``True``, if you call a command that isn't part of + the declared API version, the driver raises an exception. + | + | Default: **False** + + * - deprecationErrors + - | **Optional**. When ``True``, if you call a command that is deprecated in the + declared API version, the driver raises an exception. + | + | Default: **False** + +The following code example shows how you can set the two options on an instance of ``ServerApi`` +by chaining methods on the ``ServerApi.Builder``: + +.. literalinclude:: /includes/connect/stable-api-options.kt + :start-after: start-stable-api-options + :end-before: end-stable-api-options + :language: kotlin + :copyable: + :dedent: + +Troubleshooting +--------------- + +Unrecognized field 'apiVersion' on server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} raises this exception if you specify an API version and connect to a +MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a +deployment running {+mdb-server+} v5.0 or later. + +Provided apiStrict:true, but the command count is not in API Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} raises this exception if your ``MongoClient`` runs an operation that +isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative +operation supported by the specified {+stable-api+} version, or set the ``strict`` +option to ``False`` when constructing your ``ServerApi`` object. + +API Documentation +----------------- + +For more information about using the {+stable-api+} with {+driver-short+}, see the +following API documentation: + +- `ServerApi <{+core-api+}com/mongodb/ServerApi.html>`__ +- `ServerApi.Builder <{+core-api+}com/mongodb/ServerApi.Builder.html>`__ +- `ServerApiVersion <{+core-api+}com/mongodb/ServerApiVersion.html>`__ +- `ServerAddress <{+core-api+}com/mongodb/ServerAddress.html>`__ +- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__ +- `MongoClientSettings.Builder <{+core-api+}com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClient.create() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/-factory/create.html>`__ diff --git a/source/includes/connect/stable-api-options.kt b/source/includes/connect/stable-api-options.kt new file mode 100644 index 00000000..c5308ec0 --- /dev/null +++ b/source/includes/connect/stable-api-options.kt @@ -0,0 +1,16 @@ +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.* +import com.mongodb.kotlin.client.* +import org.bson.Document + +fun main() { + + // start-stable-api-options + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .strict(true) + .deprecationErrors(true) + .build() + // end-stable-api-options +} \ No newline at end of file diff --git a/source/includes/connect/stable-api.kt b/source/includes/connect/stable-api.kt new file mode 100644 index 00000000..6b1de046 --- /dev/null +++ b/source/includes/connect/stable-api.kt @@ -0,0 +1,31 @@ +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.* +import com.mongodb.kotlin.client.* +import org.bson.Document + +fun main() { + + // start-enable-stable-api + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build() + + // Replace the uri string placeholder with your MongoDB deployment's connection string + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .serverApi(serverApi) + .build() + + val client = MongoClient.create(settings) + // end-enable-stable-api + + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .strict(true) + .deprecationErrors(true) + .build() + +} \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index d4e5834b..e5422311 100644 --- a/source/index.txt +++ b/source/index.txt @@ -62,12 +62,6 @@ What's New For a list of new features and changes in each version, see the :ref:`What's New ` section. -Quick Reference ---------------- - -See driver syntax examples for common MongoDB commands in the -:ref:`Quick Reference ` section. - Write Data to MongoDB --------------------- diff --git a/source/quick-reference.txt b/source/quick-reference.txt deleted file mode 100644 index 95db7041..00000000 --- a/source/quick-reference.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _kotlin-sync-quick-reference: - -=============== -Quick Reference -=============== - -.. TODO \ No newline at end of file