diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/AppClientTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/AppClientTest.kt index 27962bebcdc..72a21bedcfd 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/AppClientTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/AppClientTest.kt @@ -15,6 +15,10 @@ import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFailsWith import kotlin.test.assertTrue +import kotlin.time.Duration.Companion.minutes +import kotlin.time.Duration.Companion.seconds + + class AppClientTest: RealmTest() { @Test @@ -34,18 +38,61 @@ class AppClientTest: RealmTest() { val config = // :snippet-start: configure-app-client // Creates an App with custom configuration values - AppConfiguration.Builder(YOUR_APP_ID) // Replace with your App ID + AppConfiguration.Builder(YOUR_APP_ID) // Specify your custom configuration values .appName("my-app-name") .appVersion("1.0.0") .baseUrl("http://localhost:9090") .build() // :snippet-end: + println(config.enableSessionMultiplexing) assertEquals(config.appName, "my-app-name") assertEquals(config.baseUrl, "http://localhost:9090") assertEquals(config.appVersion, "1.0.0") } + @Test + fun multiplexingTest() { + // :snippet-start: enable-multiplexing + val config = AppConfiguration.Builder(YOUR_APP_ID) + .enableSessionMultiplexing(true) + .build() + // :snippet-end: + assertTrue(config.enableSessionMultiplexing) + // :snippet-start: enable-multiplexing-with-timeout + val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID) + .enableSessionMultiplexing(true) + .syncTimeouts { + connectionLingerTime = 10.seconds // Overrides default 30 secs + } + .build() + // :snippet-end: + assertTrue(configCustomLingerTime.enableSessionMultiplexing) + assertEquals(configCustomLingerTime.syncTimeoutOptions.connectionLingerTime.inWholeSeconds, 30) + } + + @Test + fun syncTimeoutTest() { + // :snippet-start: sync-timeout-configuration + val config = AppConfiguration.Builder(YOUR_APP_ID) + .syncTimeouts { + connectTimeout = 1.minutes + connectionLingerTime = 15.seconds + pingKeepalivePeriod = 30.seconds + pongKeepalivePeriod = 1.minutes + fastReconnectLimit = 30.seconds + } + .build() + // :snippet-end: + with(config.syncTimeoutOptions) { + assertEquals(1.minutes, connectTimeout) + assertEquals(15.seconds, connectionLingerTime) + assertEquals(30.seconds, pingKeepalivePeriod) + assertEquals(1.minutes, pongKeepalivePeriod) + assertEquals(30.seconds, fastReconnectLimit) + } + } + @Test fun encryptAppMetadata() { val myEncryptionKey = getEncryptionKey() diff --git a/source/examples/generated/kotlin/AppClientTest.snippet.configure-app-client.kt b/source/examples/generated/kotlin/AppClientTest.snippet.configure-app-client.kt index cba5512f895..2437d428c2d 100644 --- a/source/examples/generated/kotlin/AppClientTest.snippet.configure-app-client.kt +++ b/source/examples/generated/kotlin/AppClientTest.snippet.configure-app-client.kt @@ -1,5 +1,5 @@ // Creates an App with custom configuration values -AppConfiguration.Builder(YOUR_APP_ID) // Replace with your App ID +AppConfiguration.Builder(YOUR_APP_ID) // Specify your custom configuration values .appName("my-app-name") .appVersion("1.0.0") diff --git a/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt b/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt new file mode 100644 index 00000000000..ad866f6e3c4 --- /dev/null +++ b/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt @@ -0,0 +1,6 @@ +val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID) + .enableSessionMultiplexing(true) + .syncTimeouts { + connectionLingerTime = 10.seconds // Overrides default 30 secs + } + .build() diff --git a/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing.kt b/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing.kt new file mode 100644 index 00000000000..d31be8b3dca --- /dev/null +++ b/source/examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing.kt @@ -0,0 +1,3 @@ +val config = AppConfiguration.Builder(YOUR_APP_ID) + .enableSessionMultiplexing(true) + .build() diff --git a/source/examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt b/source/examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt new file mode 100644 index 00000000000..c24d9d682f8 --- /dev/null +++ b/source/examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt @@ -0,0 +1,9 @@ +val config = AppConfiguration.Builder(YOUR_APP_ID) + .syncTimeouts { + connectTimeout = 1.minutes + connectionLingerTime = 15.seconds + pingKeepalivePeriod = 30.seconds + pongKeepalivePeriod = 1.minutes + fastReconnectLimit = 30.seconds + } + .build() diff --git a/source/examples/generated/kotlin/Serialization.snippet.call-function-experimental-serializer.kt b/source/examples/generated/kotlin/Serialization.snippet.call-function-experimental-serializer.kt index 3bc9bd70e10..8c3d7385fe6 100644 --- a/source/examples/generated/kotlin/Serialization.snippet.call-function-experimental-serializer.kt +++ b/source/examples/generated/kotlin/Serialization.snippet.call-function-experimental-serializer.kt @@ -2,5 +2,3 @@ val address = user.functions.call
("getMailingAddressForPerson"){ add(Person("Bob", "Smith")) } - -assertEquals(address.street, "123 Any Street") diff --git a/source/examples/generated/kotlin/Serialization.snippet.call-function-stable-serializer.kt b/source/examples/generated/kotlin/Serialization.snippet.call-function-stable-serializer.kt index 80be55dfb65..1adf4456b2e 100644 --- a/source/examples/generated/kotlin/Serialization.snippet.call-function-stable-serializer.kt +++ b/source/examples/generated/kotlin/Serialization.snippet.call-function-stable-serializer.kt @@ -1,4 +1,2 @@ // The `getMailingAddress` function takes a first name and last name and returns an address as a BsonDocument val address = user.functions.call("getMailingAddress", "Bob", "Smith") - -assertEquals(address["street"], BsonString("123 Any Street")) diff --git a/source/examples/generated/kotlin/Serialization.snippet.define-serializable-class.kt b/source/examples/generated/kotlin/Serialization.snippet.define-serializable-class.kt index 99fd4465ac5..a47331c29ed 100644 --- a/source/examples/generated/kotlin/Serialization.snippet.define-serializable-class.kt +++ b/source/examples/generated/kotlin/Serialization.snippet.define-serializable-class.kt @@ -1,6 +1,8 @@ @Serializable class Address( - val street: String, + // The `street` field in the Atlas document is a string, + // but is coming back as an `Int` since upgrading to realm-kotlin 1.13.0 + val street: Int, val city: String, val state: String, val country: String, diff --git a/source/sdk/kotlin/app-services/connect-to-app-services-backend.txt b/source/sdk/kotlin/app-services/connect-to-app-services-backend.txt index e624931487c..cbc98b6baca 100644 --- a/source/sdk/kotlin/app-services/connect-to-app-services-backend.txt +++ b/source/sdk/kotlin/app-services/connect-to-app-services-backend.txt @@ -4,6 +4,14 @@ Connect to Atlas App Services - Kotlin SDK ========================================== +.. meta:: + :keywords: code example + :description: Initialize your app client and connect to the Atlas App Services backend using the Kotlin SDK. + +.. facet:: + :name: genre + :values: tutorial + .. contents:: On this page :local: :backlinks: none @@ -72,6 +80,76 @@ and call the ``.build()`` method to pass a configuration object: .. include:: /includes/multiple-app-client-details-and-app-config-cache.rst +Share Sync Connections +~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: Applies to Atlas Device Sync + + This configuration option applies to apps using Device Sync. + For more information on using Device Sync with + the Kotlin SDK, refer to :ref:``. + +.. versionadded:: 1.13.0 + +By default, the SDK opens a separate connection to the server for +each synced realm. In Kotlin v1.13.0 and later, you can enable +**session multiplexing**. When enabled, the SDK +shares a connection to the server for all synced realms opened with +a single App Services user. Sharing a connection across multiple +sessions reduces resources and can improve performance. + +Multiplexing is disabled by default. You can enable it on the +``AppConfiguration`` using the `.enableSessionMultiplexing() +<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-app-configuration/-builder/index.html#-839865185%2FFunctions%2F380376748>`__ +method, which accepts a Boolean value. + +.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.enable-session-multiplexing.kt + :language: kotlin + +When all sessions are closed, the shared connection does not immediately close. +Instead, it remains open for the ``connectionLingerTime``, which defaults to +30 seconds. You can override this duration by passing a new value to +`SyncTimeoutOptions.connectionLingerTime() +<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-timeout-options/connection-linger-time.html>`__ +on the ``AppConfiguration``. + +.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.enable-multiplexing-with-timeout.kt + :language: kotlin + +For more information, refer to the +:ref:`kotlin-configure-sync-timeouts` section on this page. + +.. _kotlin-configure-sync-timeouts: + +Configure Sync Timeouts +~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: Applies to Atlas Device Sync + + This configuration option applies to apps using Device Sync. + For more information on using Device Sync with + the Kotlin SDK, refer to :ref:``. + +.. versionadded:: 1.13.0 + +In Kotlin v1.13.0 and later, you can override the default +timeout settings used when syncing data between the Atlas backend +and the client app. + +You can set various sync timeout settings on the +``AppConfiguration`` using the `.syncTimeouts() +<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-app-configuration/-builder/index.html#90306255%2FFunctions%2F380376748>`__ +method. Pass specific timeout property values you want to override. The +configured timeouts apply to all sync sessions in the app. + +.. literalinclude:: /examples/generated/kotlin/AppClientTest.snippet.sync-timeout-configuration.kt + :language: kotlin + +For a complete list of the available timeout properties and their +definitions, refer to the +`SyncTimeoutOptionsBuilder <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-timeout-options-builder/index.html>`__ +API reference. + .. _kotlin-encrypt-app-metadata: Encrypt App Metadata diff --git a/source/sdk/kotlin/sync/open-a-synced-realm.txt b/source/sdk/kotlin/sync/open-a-synced-realm.txt index 4712f08a85d..d188345bf31 100644 --- a/source/sdk/kotlin/sync/open-a-synced-realm.txt +++ b/source/sdk/kotlin/sync/open-a-synced-realm.txt @@ -4,12 +4,24 @@ Configure & Open a Synced Realm - Kotlin SDK ============================================ +.. meta:: + :keywords: code example + :description: Configure and open a synced database for apps using Atlas Device Sync. + +.. facet:: + :name: genre + :values: tutorial + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol +This page describes how to open a synced database--and the various +configuration options available-- your App client and connect to the Atlas +App Services backend using the Kotlin SDK. + Prerequisites ------------- @@ -39,7 +51,6 @@ an instance of the realm: .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-a-flexible-sync-realm.kt :language: kotlin - :copyable: false For more information on bootstrapping the realm with initial subscriptions and managing your synced realm subscriptions, @@ -56,7 +67,14 @@ To adjust specific configuration settings, use the options provided by .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.configure-a-flexible-sync-realm.kt :language: kotlin - :copyable: false + +.. versionadded:: 1.13.0 + Sync timeout configuration options added + +In Kotlin v1.13.0, you can override various default timeouts used for sync +operations. You can set these timeouts in the ``App`` client +configuration, and they apply to all sync sessions in the app. +To learn how, refer to :ref:``. .. _kotlin-download-changes-before-open: