Skip to content

Commit 97d3e5b

Browse files
dacharyccbullinger
dacharyc
and
cbullinger
authored
(DOCSP-39540) Consolidate Partition-Based Sync page (#3279)
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39540 *Staged Page* - [Partition-Based Sync](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39540/sdk/sync/partition-based-sync/) *Page Source* Note for reviewer: I've intentionally omitted some of the information that is present on some of the source pages. There's a lot of discrepancy between SDK docs re: the write copy API to copy between sync and non-synced realms. Some SDKs say you can use it with Flexible Sync, others say it only works with PBS. I started to include it on the page, but then omitted it. I think we should probably only doc it on the "Configure and Open a Synced Realm" page if it supports Flexible Sync. The other thing is - Java and .NET have sections about opening a realm online vs. offline. I originally started to add that to this page, but decided it's outside the scope of PBS - it just happens to use PBS examples. We already have examples on the "Configure and Open a Synced Realm" page about opening a realm offline, so I think that content should only live there. - [Partition-Based Sync - Java](https://www.mongodb.com/docs/atlas/device-sdks/sdk/java/sync/partition-based-sync/) - [Partition-Based Sync - Kotlin](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/sync/partition-based-sync/) - [Partition-Based Sync - .NET](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/sync/partition-based-sync/) - [Partition-Based Sync - Node.js](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/sync/partition-based-sync/) - [Partition-Based Sync - Swift](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/sync/partition-based-sync/) ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [x] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [x] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [x] Shared code boxes have snippets or placeholders for all 9 languages - [x] API description sections have API details or a generic placeholder for all 9 languages - [x] Check related pages for relevant content to include - [x] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [x] Shared code example boxes contain language-specific snippets or placeholders for every language - [x] API reference details contain working API reference links or generic content - [x] Realm naming/language has been updated - [x] All relevant content from individual SDK pages is present on the consolidated page --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com>
1 parent a0659fc commit 97d3e5b

28 files changed

+518
-68
lines changed

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#. Create a
2+
:dotnet-sdk:`PartitionSyncConfiguration <reference/Realms.Sync.PartitionSyncConfiguration.html>`
3+
object that includes the :ref:`partition value <partition-value>` and
4+
the :dotnet-sdk:`User <reference/Realms.Sync.User.html>` object.
5+
6+
#. Open a synced database *asynchronously* by calling the
7+
:dotnet-sdk:`GetInstanceAsync() <reference/Realms.Realm.html#Realms_Realm_GetInstanceAsync_Realms_RealmConfigurationBase_System_Threading_CancellationToken_>`
8+
method, or *synchronously* with the :dotnet-sdk:`GetInstance() <reference/Realms.Realm.html#Realms_Realm_GetInstance_System_String_>`
9+
method. Pass in the ``PartitionSyncConfiguration`` object.
10+
11+
The following code demonstrates these steps:

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. procedure::
2+
3+
.. step:: Update the SyncConfiguration
4+
5+
Change your
6+
:dotnet-sdk:`PartitionSyncConfiguration <reference/Realms.Sync.PartitionSyncConfiguration.html>`
7+
to a
8+
:dotnet-sdk:`FlexibleSyncConfiguration <reference/Realms.Sync.FlexibleSyncConfiguration.html>`.
9+
10+
.. step:: Add Properties to Object Models
11+
12+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
13+
14+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
15+
16+
.. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
To configure settings for a database, create a
2+
:java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>` with a
3+
:java-sdk:`SyncConfiguration.Builder <io/realm/mongodb/sync/SyncConfiguration.Builder.html>`.
4+
5+
The following example configures a synced database with:
6+
7+
- Partition-Based Sync
8+
- Synchronous reads explicitly allowed on the UI thread
9+
- Synchronous writes explicitly allowed on the UI thread
10+
- Explicit waiting for all backend changes to synchronize to the device
11+
before returning an open database
12+
- Automatic compaction when launching the database to save file space
13+
14+
.. include:: /includes/java-synchronous-reads-writes-ui-thread-java.rst

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
To configure settings for a database, create a
2+
:java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>` with a
3+
:java-sdk:`SyncConfiguration.Builder <io/realm/mongodb/sync/SyncConfiguration.Builder.html>`.
4+
5+
The following example configures a synced database with:
6+
7+
- Partition-Based Sync
8+
- Synchronous reads explicitly allowed on the UI thread
9+
- Synchronous writes explicitly allowed on the UI thread
10+
- Explicit waiting for all backend changes to synchronize to the device
11+
before returning an open database
12+
- Automatic compaction when launching the database to save file space
13+
14+
.. include:: /includes/java-synchronous-reads-writes-ui-thread-kotlin.rst

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. procedure::
2+
3+
.. step:: Update the SyncConfiguration
4+
5+
Update your :java-sdk:`SyncConfiguration.Builder
6+
<io/realm/mongodb/sync/SyncConfiguration.Builder.html>` to use
7+
:ref:`Flexible Sync <sdks-configure-and-open-synced-database>`. This involves
8+
removing the ``partitionValue`` and adding a set of initial subscriptions,
9+
if needed.
10+
11+
.. step:: Add Properties to Object Models
12+
13+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
14+
15+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
16+
17+
Remove automatic Flexible Sync subscriptions. If you did not add initial
18+
subscriptions in the ``SyncConfiguration.Builder``, manually create the
19+
relevant subscriptions.
20+
21+
.. 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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To open a database with Partition-Based Sync, call
2+
:js-sdk:`Realm.open() <classes/Realm-1.html#open>`.
3+
Pass in a :js-sdk:`Configuration <types/BaseConfiguration.html>`
4+
object, which must include the ``sync`` property defining a
5+
:js-sdk:`SyncConfiguration <types/PartitionSyncConfiguration.html>` object.
6+
In the ``SyncConfiguration``, you must include include ``user`` and
7+
``partitionValue``.

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. procedure::
2+
3+
.. step:: Update the SyncConfiguration
4+
5+
Add ``flexible:true`` to your
6+
:js-sdk:`SyncConfiguration <types/FlexibleSyncConfiguration.html>` object
7+
where you :ref:`open a synced database <sdks-configure-and-open-synced-database>`.
8+
9+
.. step:: Add Properties to Object Models
10+
11+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
12+
13+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
14+
15+
.. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To open a :ref:`Partition-Based Sync <partition-based-sync>` database,
2+
pass a user, a partition, and a set of SDK object schemas to
3+
:kotlin-sync-sdk:`SyncConfiguration.Builder()
4+
<io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>`.
5+
Then, pass the configuration to :kotlin-sdk:`Realm.open()
6+
<io.realm.kotlin/-realm/-companion/open.html>` to open
7+
an instance of the database:

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. procedure::
2+
3+
.. step:: Update the SyncConfiguration
4+
5+
Update your :kotlin-sync-sdk:`SyncConfiguration.Builder()
6+
<io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>`
7+
to use Flexible Sync where you :ref:`open a synced database
8+
<sdks-configure-and-open-synced-database>`. This involves removing the
9+
``partitionValue`` and adding a set of initial subscriptions, if needed.
10+
11+
.. step:: Add Properties to Object Models
12+
13+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
14+
15+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
16+
17+
.. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
The first time you log in and open a synced database, log in the
2+
user, and pass the user's :objc-sdk:`RLMSyncConfiguration
3+
<Classes/RLMRealmConfiguration.html#/c:objc(cs)RLMRealmConfiguration(py)syncConfiguration>`
4+
object with the desired :objc-sdk:`partitionValue
5+
<Classes/RLMSyncConfiguration.html#/c:objc(cs)RLMSyncConfiguration(py)partitionValue>`
6+
to :objc-sdk:`+[RLMRealm realmWithConfiguration:error:]
7+
<Classes/RLMRealm.html#/c:objc(cs)RLMRealm(cm)realmWithConfiguration:error:>`.
8+
9+
This opens a synced database on the device. The database
10+
attempts to sync with your App in the background to check for changes
11+
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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. procedure::
2+
3+
.. step:: Update the Sync Configuration
4+
5+
Switch to a :objc-sdk:`RLMUser -flexibleSyncConfiguration
6+
<Classes/RLMUser.html#/c:objc(cs)RLMUser(im)flexibleSyncConfiguration>`
7+
where you :ref:`open a synced database
8+
<sdks-configure-and-open-synced-database>`.
9+
10+
.. step:: Add Properties to Object Models
11+
12+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
13+
14+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
15+
16+
.. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

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

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

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. procedure::
2+
3+
.. step:: Update the Sync Configuration
4+
5+
Switch to a ``flexibleSyncConfiguration()`` where you :ref:`open a synced
6+
database <sdks-configure-and-open-synced-database>`.
7+
8+
.. step:: Add Properties to Object Models
9+
10+
.. include:: /includes/pbs-to-fs-migration-add-relevant-properties-to-models.rst
11+
12+
.. step:: Remove Automatic Subscriptions and Manually Create New Ones
13+
14+
.. include:: /includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst

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

Lines changed: 7 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,17 @@
1-
To open a synced realm, call
1+
To open a synced database, call
22
:java-sdk:`getInstanceAsync()
33
<io/realm/Realm.html#getInstanceAsync-io.realm.RealmConfiguration-io.realm.Realm.Callback->`,
44
passing in a :java-sdk:`SyncConfiguration <io/realm/mongodb/sync/SyncConfiguration.html>`
5-
object. The following code demonstrates how to create a realm with
6-
specific sync settings created using a ``SyncConfiguration`` object:
7-
8-
.. tabs-realm-languages::
9-
10-
.. tab::
11-
:tabid: kotlin
12-
13-
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.kt
14-
:language: kotlin
15-
:copyable: false
5+
object.
166

17-
.. tab::
18-
:tabid: java
19-
20-
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.java
21-
:language: java
22-
:copyable: false
23-
24-
The code above shows how to open the realm *asynchronously*
25-
by using :java-sdk:`getInstanceAsync()
26-
<io/realm/Realm.html#getInstanceAsync-io.realm.RealmConfiguration-io.realm.Realm.Callback->`.
27-
You can also open a realm synchronously by using :java-sdk:`getInstance()
7+
You can also open a database synchronously by using :java-sdk:`getInstance()
288
<io/realm/Realm.html#getInstance-io.realm.RealmConfiguration->`, which
29-
returns an open realm before synchronizing all data from the backend.
9+
returns an open database before synchronizing all data from the backend.
3010
However, this may lead to temporary data inconsistencies while the
3111
remote data is downloaded, and is generally not recommended. You can
3212
use the :java-sdk:`waitForInitialRemoteData() <io/realm/mongodb/sync/SyncConfiguration.Builder.html#waitForInitialRemoteData-->`
3313
configuration option to force the SDK to fetch remote data before
34-
opening the realm to avoid these inconsistencies.
14+
opening the database to avoid these inconsistencies.
3515

36-
The :ref:`partition value <partition-value>` specifies which subset of your data to sync.
37-
This is typically a user ID, project ID, store ID, or some other category identifier in
38-
your app that has particular relevance to the current user.
16+
The following code demonstrates how to create a database with
17+
specific sync settings created using a ``SyncConfiguration`` object:

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. important:: Synchronous Reads and Writes on the UI Thread
2+
3+
By default, you can only read or write to a database in your
4+
application's UI thread using asynchronous transactions. That is,
5+
you can only use ``Realm`` methods whose name ends with the word
6+
``Async`` in the main thread of your Android application unless you
7+
explicitly allow the use of synchronous methods.
8+
9+
This restriction exists for the benefit of your application users:
10+
performing read and write operations on the UI thread can lead to
11+
unresponsive or slow UI interactions, so it's usually best to handle
12+
these operations either asynchronously or in a background thread.
13+
However, if your application requires the use of synchronous
14+
database reads or writes on the UI thread, you can explicitly allow
15+
the use of synchronous methods with the following
16+
``SyncConfiguration`` options:
17+
18+
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.java
19+
:language: java
20+
:emphasize-lines: 2,3
21+
:copyable: false

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. important:: Synchronous Reads and Writes on the UI Thread
2+
3+
By default, you can only read or write to a database in your
4+
application's UI thread using asynchronous transactions. That is,
5+
you can only use ``Realm`` methods whose name ends with the word
6+
``Async`` in the main thread of your Android application unless you
7+
explicitly allow the use of synchronous methods.
8+
9+
This restriction exists for the benefit of your application users:
10+
performing read and write operations on the UI thread can lead to
11+
unresponsive or slow UI interactions, so it's usually best to handle
12+
these operations either asynchronously or in a background thread.
13+
However, if your application requires the use of synchronous
14+
database reads or writes on the UI thread, you can explicitly allow
15+
the use of synchronous methods with the following
16+
``SyncConfiguration`` options:
17+
18+
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.allow-reads-writes-ui-thread.kt
19+
:language: kotlin
20+
:emphasize-lines: 2,3
21+
:copyable: false

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

Lines changed: 0 additions & 35 deletions
This file was deleted.

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
.. note:: Partition-Based Sync Only
22

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

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33
This method only supports copying a Partition-Based Sync configuration for
44
another Partition-Based Sync user, or a Flexible Sync configuration for another
55
Flexible Sync user. You cannot use this method to convert between a
6-
Partition-Based Sync realm and a Flexible Sync realm or vice-versa.
6+
Partition-Based Sync database and a Flexible Sync database or vice-versa.

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add relevant properties to your object models to use in your Flexible Sync
2+
subscriptions. For example, you might add an ``ownerId`` property to enable
3+
a user to sync only their own data.

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
When you migrate from Partition-Based Sync to Flexible Sync, the SDK
2+
automatically creates hidden Sync subscriptions for your app. The
3+
next time you add or change subscriptions, we recommend that you:
4+
5+
1. :ref:`Remove the automatically-generated subscriptions <sdks-remove-sync-subscriptions>`.
6+
2. :ref:`Manually add the relevant subscriptions in your client codebase <sdks-add-sync-subscriptions>`.
7+
8+
This enables you to see all of your subscription logic together in your
9+
codebase for future iteration and debugging.
10+
11+
For more information about the automatically-generated Sync
12+
subscriptions, refer to :ref:`realm-sync-migrate-client`.

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
5+
- id: csharp
6+
content: |
7+
8+
.. literalinclude:: /examples/generated/dotnet/OpenARealmExamples.snippet.open-synced-realm.cs
9+
:language: csharp
10+
11+
- id: java
12+
content: |
13+
14+
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.configure-a-realm.java
15+
:language: java
16+
17+
- id: java-kotlin
18+
content: |
19+
20+
.. literalinclude:: /examples/generated/java/sync/OpenARealmTest.snippet.configure-a-realm.kt
21+
:language: kotlin
22+
23+
- id: javascript
24+
content: |
25+
26+
.. literalinclude:: /examples/generated/node/open-and-close-a-realm.snippet.open-partition-based.js
27+
:language: javascript
28+
29+
- id: kotlin
30+
content: |
31+
32+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-a-synced-realm.kt
33+
:language: kotlin
34+
35+
- id: objectivec
36+
content: |
37+
38+
.. literalinclude:: /examples/generated/code/start/Sync.snippet.init-synced-realm.m
39+
:language: objectivec
40+
41+
- id: swift
42+
content: |
43+
44+
.. literalinclude:: /examples/generated/code/start/Sync.snippet.open-realm-partition-based-sync.swift
45+
:language: swift
46+
47+
- id: typescript
48+
content: |
49+
50+
.. literalinclude:: /examples/generated/node/open-and-close-a-realm.snippet.open-partition-based.ts
51+
:language: typescript

0 commit comments

Comments
 (0)