(DOCSP-39540) Consolidate Partition-Based Sync page

source/includes/api-details/csharp/sync/pbs-open-synced-database-description.rst

@@ -0,0 +1,11 @@
+#. Create a 
+   :dotnet-sdk:`PartitionSyncConfiguration <reference/Realms.Sync.PartitionSyncConfiguration.html>` 
+   object that includes the :ref:`partition value <partition-value>` and 
+   the :dotnet-sdk:`User <reference/Realms.Sync.User.html>` object.
+
+#. Open a synced database *asynchronously* by calling the 
+   :dotnet-sdk:`GetInstanceAsync() <reference/Realms.Realm.html#Realms_Realm_GetInstanceAsync_Realms_RealmConfigurationBase_System_Threading_CancellationToken_>` 
+   method, or *synchronously* with the :dotnet-sdk:`GetInstance() <reference/Realms.Realm.html#Realms_Realm_GetInstance_System_String_>` 
+   method. Pass in the ``PartitionSyncConfiguration`` object.
+
+The following code demonstrates these steps:

source/includes/api-details/csharp/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,16 @@
+.. procedure::
+
+   .. step:: Update the SyncConfiguration
+
+      Change your 
+      :dotnet-sdk:`PartitionSyncConfiguration <reference/Realms.Sync.PartitionSyncConfiguration.html>`
+      to a
+      :dotnet-sdk:`FlexibleSyncConfiguration <reference/Realms.Sync.FlexibleSyncConfiguration.html>`.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/api-details/java/sync/pbs-open-synced-database-java-description.rst

@@ -0,0 +1,14 @@
+To configure settings for a database, create a
+:java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>` with a
+:java-sdk:`SyncConfiguration.Builder <io/realm/mongodb/sync/SyncConfiguration.Builder.html>`.
+
+The following example configures a synced database with:
+
+- Partition-Based Sync
+- Synchronous reads explicitly allowed on the UI thread
+- Synchronous writes explicitly allowed on the UI thread
+- Explicit waiting for all backend changes to synchronize to the device
+  before returning an open database
+- Automatic compaction when launching the database to save file space
+
+.. include:: /includes/java-synchronous-reads-writes-ui-thread-java.rst

source/includes/api-details/java/sync/pbs-open-synced-database-kotlin-description.rst

@@ -0,0 +1,14 @@
+To configure settings for a database, create a
+:java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>` with a
+:java-sdk:`SyncConfiguration.Builder <io/realm/mongodb/sync/SyncConfiguration.Builder.html>`.
+
+The following example configures a synced database with:
+
+- Partition-Based Sync
+- Synchronous reads explicitly allowed on the UI thread
+- Synchronous writes explicitly allowed on the UI thread
+- Explicit waiting for all backend changes to synchronize to the device
+  before returning an open database
+- Automatic compaction when launching the database to save file space
+
+.. include:: /includes/java-synchronous-reads-writes-ui-thread-kotlin.rst

source/includes/api-details/java/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,21 @@
+.. procedure::
+
+   .. step:: Update the SyncConfiguration
+
+      Update your :java-sdk:`SyncConfiguration.Builder 
+      <io/realm/mongodb/sync/SyncConfiguration.Builder.html>` to use 
+      :ref:`Flexible Sync <sdks-configure-and-open-synced-database>`. This involves
+      removing the ``partitionValue`` and adding a set of initial subscriptions, 
+      if needed.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      Remove automatic Flexible Sync subscriptions. If you did not add initial 
+      subscriptions in the ``SyncConfiguration.Builder``, manually create the
+      relevant subscriptions.
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/api-details/javascript/sync/pbs-open-synced-database-js-ts-description.rst

@@ -0,0 +1,7 @@
+To open a database with Partition-Based Sync, call
+:js-sdk:`Realm.open() <classes/Realm-1.html#open>`. 
+Pass in a :js-sdk:`Configuration <types/BaseConfiguration.html>`
+object, which must include the ``sync`` property defining a 
+:js-sdk:`SyncConfiguration <types/PartitionSyncConfiguration.html>` object. 
+In the ``SyncConfiguration``, you must include include ``user`` and
+``partitionValue``.

source/includes/api-details/javascript/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,15 @@
+.. procedure::
+
+   .. step:: Update the SyncConfiguration
+
+      Add ``flexible:true`` to your 
+      :js-sdk:`SyncConfiguration <types/FlexibleSyncConfiguration.html>` object 
+      where you :ref:`open a synced database <sdks-configure-and-open-synced-database>`.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/api-details/kotlin/sync/pbs-open-synced-database-description.rst

@@ -0,0 +1,7 @@
+To open a :ref:`Partition-Based Sync <partition-based-sync>` database,
+pass a user, a partition, and a set of SDK object schemas to
+:kotlin-sync-sdk:`SyncConfiguration.Builder()
+<io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>`.
+Then, pass the configuration to :kotlin-sdk:`Realm.open()
+<io.realm.kotlin/-realm/-companion/open.html>` to open
+an instance of the database:

source/includes/api-details/kotlin/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,17 @@
+.. procedure::
+
+   .. step:: Update the SyncConfiguration
+
+      Update your :kotlin-sync-sdk:`SyncConfiguration.Builder()
+      <io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>` 
+      to use Flexible Sync where you :ref:`open a synced database
+      <sdks-configure-and-open-synced-database>`. This involves removing the
+      ``partitionValue`` and adding a set of initial subscriptions, if needed.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/api-details/objectivec/sync/pbs-open-synced-database-description.rst

@@ -0,0 +1,11 @@
+The first time you log in and open a synced database, log in the
+user, and pass the user's :objc-sdk:`RLMSyncConfiguration 
+<Classes/RLMRealmConfiguration.html#/c:objc(cs)RLMRealmConfiguration(py)syncConfiguration>` 
+object with the desired :objc-sdk:`partitionValue 
+<Classes/RLMSyncConfiguration.html#/c:objc(cs)RLMSyncConfiguration(py)partitionValue>` 
+to :objc-sdk:`+[RLMRealm realmWithConfiguration:error:]
+<Classes/RLMRealm.html#/c:objc(cs)RLMRealm(cm)realmWithConfiguration:error:>`.
+
+This opens a synced database on the device. The database
+attempts to sync with your App in the background to check for changes 
+on the server, or upload changes that the user has made.

source/includes/api-details/objectivec/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,16 @@
+.. procedure::
+
+   .. step:: Update the Sync Configuration
+
+      Switch to a :objc-sdk:`RLMUser -flexibleSyncConfiguration
+      <Classes/RLMUser.html#/c:objc(cs)RLMUser(im)flexibleSyncConfiguration>`
+      where you :ref:`open a synced database
+      <sdks-configure-and-open-synced-database>`.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/api-details/swift/sync/pbs-open-synced-database-description.rst

@@ -0,0 +1,9 @@
+Pass a logged-in user's :swift-sdk:`configuration <Structs/Realm/Configuration.html>` 
+object with the desired :ref:`partition value <partition-value>` to 
+:swift-sdk:`realm initializers 
+<Structs/Realm.html#/s:10RealmSwift0A0V13configuration5queueA2C13ConfigurationV_So012OS_dispatch_D0CSgtKcfc>`.
+
+You can optionally :ref:`specify whether a database should download 
+changes before opening <sdks-download-changes-before-open>`. If you do not
+specify download behavior, this opens a database with data that is on
+the device, and attempts to sync changes in the background.

source/includes/api-details/swift/sync/pbs-update-client-code-after-migration-procedure.rst

@@ -0,0 +1,14 @@
+.. procedure::
+
+   .. step:: Update the Sync Configuration
+
+      Switch to a ``flexibleSyncConfiguration()`` where you :ref:`open a synced
+      database <sdks-configure-and-open-synced-database>`.
+
+   .. step:: Add Properties to Object Models
+
+      .. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
+
+   .. step:: Remove Automatic Subscriptions and Manually Create New Ones
+
+      .. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

source/includes/java-open-synced-realm.rst

@@ -1,38 +1,17 @@
-To open a synced realm, call 
+To open a synced database, call 
 :java-sdk:`getInstanceAsync()
 <io/realm/Realm.html#getInstanceAsync-io.realm.RealmConfiguration-io.realm.Realm.Callback->`, 
 passing in a :java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>` 
-object. The following code demonstrates how to create a realm with 
-specific sync settings created using a ``SyncConfiguration`` object:
-
-.. tabs-realm-languages::
-
-   .. tab::
-       :tabid: kotlin
-
-       .. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.kt
-         :language: kotlin
-         :copyable: false
+object.
 
-   .. tab::
-       :tabid: java
-
-       .. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.java
-         :language: java
-         :copyable: false
-
-The code above shows how to open the realm *asynchronously* 
-by using :java-sdk:`getInstanceAsync()
-<io/realm/Realm.html#getInstanceAsync-io.realm.RealmConfiguration-io.realm.Realm.Callback->`. 
-You can also open a realm synchronously by using :java-sdk:`getInstance()
+You can also open a database synchronously by using :java-sdk:`getInstance()
 <io/realm/Realm.html#getInstance-io.realm.RealmConfiguration->`, which
-returns an open realm before synchronizing all data from the backend.
+returns an open database before synchronizing all data from the backend.
 However, this may lead to temporary data inconsistencies while the
 remote data is downloaded, and is generally not recommended. You can
 use the :java-sdk:`waitForInitialRemoteData() <io/realm/mongodb/sync/SyncConfiguration.Builder.html#waitForInitialRemoteData-->`
 configuration option to force the SDK to fetch remote data before
-opening the realm to avoid these inconsistencies.
+opening the database to avoid these inconsistencies.
 
-The :ref:`partition value <partition-value>` specifies which subset of your data to sync.
-This is typically a user ID, project ID, store ID, or some other category identifier in
-your app that has particular relevance to the current user. 
+The following code demonstrates how to create a database with 
+specific sync settings created using a ``SyncConfiguration`` object:

source/includes/java-synchronous-reads-writes-ui-thread-java.rst

@@ -0,0 +1,21 @@
+.. important:: Synchronous Reads and Writes on the UI Thread
+
+   By default, you can only read or write to a database in your
+   application's UI thread using asynchronous transactions. That is,
+   you can only use ``Realm`` methods whose name ends with the word
+   ``Async`` in the main thread of your Android application unless you
+   explicitly allow the use of synchronous methods.
+
+   This restriction exists for the benefit of your application users:
+   performing read and write operations on the UI thread can lead to
+   unresponsive or slow UI interactions, so it's usually best to handle
+   these operations either asynchronously or in a background thread.
+   However, if your application requires the use of synchronous
+   database reads or writes on the UI thread, you can explicitly allow
+   the use of synchronous methods with the following
+   ``SyncConfiguration`` options:
+
+.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.java
+   :language: java
+   :emphasize-lines: 2,3
+   :copyable: false

source/includes/java-synchronous-reads-writes-ui-thread-kotlin.rst

@@ -0,0 +1,21 @@
+.. important:: Synchronous Reads and Writes on the UI Thread
+
+   By default, you can only read or write to a database in your
+   application's UI thread using asynchronous transactions. That is,
+   you can only use ``Realm`` methods whose name ends with the word
+   ``Async`` in the main thread of your Android application unless you
+   explicitly allow the use of synchronous methods.
+
+   This restriction exists for the benefit of your application users:
+   performing read and write operations on the UI thread can lead to
+   unresponsive or slow UI interactions, so it's usually best to handle
+   these operations either asynchronously or in a background thread.
+   However, if your application requires the use of synchronous
+   database reads or writes on the UI thread, you can explicitly allow
+   the use of synchronous methods with the following
+   ``SyncConfiguration`` options:
+
+.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.kt
+   :language: kotlin
+   :emphasize-lines: 2,3
+   :copyable: false

source/includes/note-writecopy-local-to-sync.rst

@@ -1,5 +1,6 @@
 .. note:: Partition-Based Sync Only
 
-   This method only supports converting between a non-sync realm and 
+   This method only supports converting between a non-sync database and 
    Partition-Based Sync. If your app uses Flexible Sync, you must manually 
-   iterate through the objects in one realm and copy them into the other realm.
+   iterate through the objects in one database and copy them into the other
+   database.

source/includes/note-writecopy-same-type-sync-only.rst

@@ -3,4 +3,4 @@
    This method only supports copying a Partition-Based Sync configuration for 
    another Partition-Based Sync user, or a Flexible Sync configuration for another
    Flexible Sync user. You cannot use this method to convert between a 
-   Partition-Based Sync realm and a Flexible Sync realm or vice-versa.
+   Partition-Based Sync database and a Flexible Sync database or vice-versa.

source/includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst

@@ -0,0 +1,3 @@
+Add relevant properties to your object models to use in your Flexible Sync 
+subscriptions. For example, you might add an ``ownerId`` property to enable
+a user to sync only their own data.

source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

@@ -0,0 +1,12 @@
+When you migrate from Partition-Based Sync to Flexible Sync, the SDK
+automatically creates hidden Sync subscriptions for your app. The 
+next time you add or change subscriptions, we recommend that you:
+
+1. :ref:`Remove the automatically-generated subscriptions <sdks-remove-sync-subscriptions>`. 
+2. :ref:`Manually add the relevant subscriptions in your client codebase <sdks-add-sync-subscriptions>`.
+
+This enables you to see all of your subscription logic together in your 
+codebase for future iteration and debugging.
+
+For more information about the automatically-generated Sync 
+subscriptions, refer to :ref:`realm-sync-migrate-client`.

source/includes/sdk-examples/sync/pbs-open-synced-database.rst

@@ -0,0 +1,51 @@
+.. tabs-drivers::
+
+   tabs:
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/OpenARealmExamples.snippet.open-synced-realm.cs
+            :language: csharp
+
+     - id: java
+       content: |
+
+         .. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.configure-a-realm.java
+            :language: java
+
+     - id: java-kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.configure-a-realm.kt
+            :language: kotlin
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/open-and-close-a-realm.snippet.open-partition-based.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-a-synced-realm.kt
+            :language: kotlin
+
+     - id: objectivec
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Sync.snippet.init-synced-realm.m
+            :language: objectivec
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Sync.snippet.open-realm-partition-based-sync.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/open-and-close-a-realm.snippet.open-partition-based.ts
+            :language: typescript