From 13dffdb889410bb4d40c10e6392448c985a63d31 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 11:16:09 -0400 Subject: [PATCH 01/25] Scaffold Sync Subscriptions page --- ...iptions-subscribe-to-query-description.rst | 11 + ...tions-subscribe-to-query-not-supported.rst | 3 + ...s-subscribe-to-query-js-ts-description.rst | 13 + ...iptions-subscribe-to-query-description.rst | 2 + ...iptions-subscribe-to-query-description.rst | 3 + ...-sync-subscriptions-subscribe-to-query.rst | 60 ++ source/sdk/sync/manage-sync-subscriptions.txt | 571 ++++++++++++++++++ 7 files changed, 663 insertions(+) create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst create mode 100644 source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..e6faa6f4c6 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,11 @@ +To subscribe to a query, pass the following arguments to ``subscribe()``: + +- ``RealmResults query``: Required. A ``RealmResults`` object that you can + create using the :ref:`Realm Query Language `. +- ``String name``: Optional. Name for the subscription that you can refer to. +- ``bool update``: Optional. When true, adding a subscription with an existing + name replaces the existing query with the new query. When false, the SDK + throws an exception for duplicate subscriptions. Only use with named + subscriptions. + +In the following example, we subscribe to two new named queries. diff --git a/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst b/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst new file mode 100644 index 0000000000..e51a3ebe76 --- /dev/null +++ b/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst @@ -0,0 +1,3 @@ +The selected language does not support the API that enables you to subscribe +to a query. Instead, refer to :ref:`manually manage queries +`. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst new file mode 100644 index 0000000000..fceca4706a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst @@ -0,0 +1,13 @@ +To subscribe to a query: + +#. Query for the objects that you want to read and write. +#. Call ``subscribe()`` on the query results to create a sync subscription for + objects matching the query. +#. Pass a ``SubscriptionOptions`` object. + +Most of the time, you should give your subscriptions a name. If you don't, the +name is set to :mdn:`null `. + +If you use ``filtered()`` on an unnamed query subscription, the subscription +identifier is based on the ``filtered`` query. This means that every time your +query string changes, ``subscribe()`` will create a new subscription. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..1f1f04a4d5 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,2 @@ +To subscribe to a ``RealmQuery`` or ``RealmResults`` set, call the +:kotlin-sdk:`.subscribe() ` method. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..bb032761e0 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,3 @@ +Use the :swift-sdk:`.subscribe() +` +method to create a subscription for objects matching the query. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst new file mode 100644 index 0000000000..4da480a49e --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-basic.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-unnamed.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-basic.ts + :language: typescript diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 436c09a9a3..edf75b2f67 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -4,12 +4,583 @@ Manage Sync Subscriptions ========================= +.. meta:: + :description: Provide a short description of the consolidated page. This is critical for SEO. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol +.. tabs-selector:: drivers + +Atlas Device Sync uses subscriptions and permissions to determine what +data to sync with your client application. + +After you :ref:`open a synced database `, +you must add subscriptions before you can read to and write from the database. + +You can manually add, update, and remove subscriptions to determine which +data syncs to the client device. Or you can subscribe to queries instead of +or in addition to manually managing subscriptions. + +Subscriptions +------------- + +When you configure Device Sync in Atlas, you specify which fields your +client application can query using **subscriptions**. + +Each subscription corresponds to a query on **queryable fields** for a +specific object type. See :ref:`Queryable Fields ` +in the Device Sync documentation for more information. + +For each query subscription, the SDK looks for data matching the query. +Data matching the subscription, where the user has the appropriate +permissions, syncs between clients and the backend application. + +You can construct queries with RQL, or one of the SDK-idiomatic query engines. + +- :ref:`realm-query-language` +- :ref:`java-filter-data` +- :ref:`dotnet-linq` +- :ref:`sdks-filter-data-swift` + +Subscribe to Object Types +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Subscription sets are based on your :ref:`data model object types `. +You might have multiple subscriptions if you have many types of SDK objects. +You can also have multiple subscriptions on the same object type. + +However, note the following if you use :ref:`relationships +` or :ref:`asymmetric objects +` in your app: + +Object Links +```````````` + +You must add both an object and its linked object to the subscription +set to see a linked object. + +If your subscription results contain an object with a property that links +to an object not contained in the results, the link appears to be nil. +The SDK does not provide a way to distinguish whether that property's value is +legitimately nil, or whether the object it links to exists but is out of +view of the query subscription. + +Asymmetric Objects +`````````````````` + +If your app uses :ref:`Data Ingest ` to +unidirectionally sync **asymmetric objects**, you *cannot* create subscriptions +for those objects. If your app contains asymmetric objects and non-asymmetric +objects in the same database, you can add subscription queries for the +non-asymmetric objects. + +Permissions +~~~~~~~~~~~ + +Subscriptions work hand-in-hand with permissions to determine what data to +Sync to your client application. The client application only sees the +subset of data that matches your subscriptions which *also* matches the +permissions of the logged-in user. For more information about the intersection +of subscriptions and user permissions, refer to :ref:`sdks-write-synced-database`. + +This page details how to manage client subscriptions for Device Sync. +For information about setting up permissions for Device Sync, see: +:ref:`Device Sync Rules & Permissions `. + +Manage Subscriptions in Your Client App +--------------------------------------- + +In the client application, you add, update, and remove subscriptions to specific +queries on the queryable fields. This determines which data syncs to the +client device. + +You can: + +- Add subscriptions with an optional subscription name: + + - You can subscribe to query ``Results``. This + automatically adds the subscription to the subscription set. + - Manually add a subscription to the subscription set with the subscribe API. + Use this API if you need more control over subscriptions for performance + optimization or business-logic reasons. See :ref:`Performance Considerations + ` for more information. + +- React to subscription state +- Update subscriptions with new queries +- Remove individual subscriptions or all subscriptions for an object type + +.. _sdks-sync-results-subscribe-api: + +Subscribe to Queries +-------------------- + +To simplify subscription management, the SDK offers APIs to subscribe and +unsubscribe from a query's ``Results`` set. These APIs abstract away the +details of manually adding and removing subscriptions. This API is not +available for all languages. If your preferred language does not provide this +API, refer to :ref:`sdks-manually-manage-subscriptions`. + +.. important:: The Subscribe to Queries API is in Preview + + The APIs described here are currently in Preview. These APIs may be subject + to change in the future. + +Subscribe to a Query +~~~~~~~~~~~~~~~~~~~~ + +With an :ref:`authenticated user ` and a +:ref:`Sync configuration `, you can +open a synced database and query for the objects you want to read and write. +You can subscribe to the query to create a subscription for objects matching +the query. + +This creates an unnamed subscription and adds it to the subscription set, +similar to :ref:`manually creating a subscription +`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst + +Subscribe to a Query with a Subscription Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your app works with multiple subscriptions, or if you want to update +a subscription, you may want to add a name when you subscribe to a query. + +You can later use this name to :ref:`update a subscription's query +`, :ref:`check for a subscription by +name `, or :ref:`remove the +query by name `. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift + :language: swift + +Wait for a Query Subscription to Sync +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you subscribe to a query's ``Results`` set, that set does not contain +objects until it syncs. If your app creates objects, you may not need to +download synced data before the user works with it. However, if your app +requires data from the server before the user can work with it, you can +specify that a subscription should ``waitForSync``: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-wait-for-sync.swift + :language: swift + +This option uses the ``RLMWaitForSyncMode`` enum, whose cases are: + +- .onCreation: Wait to download matching objects when your app creates the + subscription. Otherwise, return without waiting for new downloads. The + app must have an internet connection the first time you add the subscription. +- .always: Wait to download matching objects when ``.subscribe()`` is executed. + The app must have an internet connection when ``.subscribe()`` is executed. +- .never: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value of type :apple:`TimeInterval +`. + +Unsubscribe from a Query +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can unsubscribe from a query's ``Results`` set using the +:swift-sdk:`.unsubscribe() +` API: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-api-unsubscribe.swift + :language: swift + +This removes the subscription from the ``MutableSubscriptionSet``, +similar to :ref:`manually removing a subscription `. + +A ``Results`` set may still contain objects after calling ``.unsubscribe()`` +if another subscription exists that contains overlapping objects. + +Calling ``.unsubscribe()`` does not wait for objects to be removed from the +realm. There is no API to wait for ``.unsubscribe()`` to sync with the server. + +Subscribe to an Actor-Confined Query +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can subscribe to an actor-confined query on the MainActor: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-main-actor.swift + :language: swift + +Or subscribe to a query on a custom actor: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-custom-actor.swift + :language: swift + +For more information about actor-confined realms, refer to +:ref:`swift-actor-isolated-realm`. + +.. _sdks-manually-manage-subscriptions: + +Manually Manage Subscriptions +----------------------------- + +You can use the ``subscriptions`` API to manually manage a set of +subscriptions to specific queries on queryable fields. + +You can: + +- Add subscriptions +- React to subscription state +- Update subscriptions with new queries +- Remove individual subscriptions or all subscriptions for an object type + +Data matching the subscription, where the user has the appropriate +permissions, syncs between devices and the backend application. + +You can specify an optional string name for your subscription. + +When you create a subscription, Realm looks for data matching a query on a +specific object type. You can have multiple subscription sets on different +object types. You can also have multiple queries on the same object type. + +.. example:: + + You can create a subscription with an explicit name. Then, you can + search for that subscription by name to update or remove it. + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-by-name.swift + :language: swift + + If you do not specify a ``name`` for a subscription, you can search + for the subscription by the query string. + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-without-name.swift + :language: swift + +.. note:: Duplicate subscriptions + + Subscription names must be unique. Trying to append a subscription + with the same name as an existing subscription throws an error. + + If you do not explicitly name a subscription, and instead subscribe + to the same unnamed query more than once, Realm does not persist + duplicate queries to the subscription set. + + If you subscribe to the same query more than once under different names, + Realm persists both subscriptions to the subscription set. + +.. _sdks-sync-subscriptions-add-subscription: + +Add a Subscription +~~~~~~~~~~~~~~~~~~ + +Add a subscription in a subscriptions update block. You append each +new subscription to the client's Realm subscriptions. + +.. include:: /includes/swift-concurrency-mainactor.rst + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-single-subscription.swift + :language: swift + +You can add multiple subscriptions within a subscription update block, +including subscriptions of different object types. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-multiple-subscriptions.swift + :language: swift + +.. _ios-sync-add-initial-subscriptions: + +Bootstrap the Realm with Initial Subscriptions +`````````````````````````````````````````````` + +.. versionadded:: 10.28.0 + +You must have at least one subscription before you can read from or write +to the realm. You can bootstrap a realm with an initial subscription set +when you open it with the :swift-sdk:`flexibleSyncConfiguration() +`. +Pass the ``initialSubscriptions`` parameter with the subscription queries +you want to use to bootstrap the realm: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions.swift + :language: swift + +If your app needs to rerun this initial subscription every time the app starts, +you can pass an additional parameter - ``rerunOnOpen``. This is a bool that +denotes whether the initial subscription should re-run every time the +app starts. You might need to do this to re-run dynamic time ranges +or other queries that require a re-computation of static variables for the +subscription. + +In this example, we don't want users to be overwhelmed by irrelevant tasks, +so we'll load only tasks due within the previous 7 days and the next 7 days. +Tasks that were due more than a week ago are no longer relevant, and tasks +that are due further out than the next week are also not relevant. With +``rerunOnOpen`` here, the query dynamically recalculates the relevant +objects to sync based on the desired date range every time the app starts. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions-rerun-on-open.swift + :language: swift + +Subscribe to All Objects of a Specific Type +``````````````````````````````````````````` + +In addition to syncing all objects that match a given query, you can subscribe +to all objects of a specific type. You do this by appending a subscription +without providing a query. + +For example, if you don't want to see a specific team, but instead want to +subscribe to all the ``Team`` objects, you could do this: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift + :language: swift + +.. _ios-check-existing-subscriptions-before-adding: + +Check for Existing Subscriptions Before Adding a Subscription +````````````````````````````````````````````````````````````` + +If your application flow appends the same named subscription to the subscription +set every time you run the application, this is disallowed. In this case, +add a check for an existing subscription before appending it: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.check-before-adding-subscription.swift + :language: swift + +.. _ios-sync-check-subscription-state: +.. _ios-sync-react-to-subscription-changes: + +Wait for Subscription Changes to Sync +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Updating the subscription set locally is only one component +of changing a subscription. After the local subscription change, the realm +synchronizes with the server to resolve any updates to the data due to +the subscription change. This could mean adding or removing data from the +synced realm. + +Pre Async/Await +``````````````` + +If your application does not use Swift's async/await feature, you can react +to subscription changes syncing with the server using the ``onComplete`` +block. This block is called after subscriptions are synchronized with the +server. If you want to react to subscription state changes by redrawing a +UI, for example, or taking another action based on changes to the data set, +take those actions in ``onComplete``. This is also where you can handle +optional errors that occur during synchronization. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-subscription-with-oncomplete.swift + :language: swift + +Async/Await +``````````` + +If your application uses async/await, you don't need the ``onComplete`` +block. The update executes asynchronously and throws an +error if the update cannot complete successfully. + +.. code-block:: swift + + @MainActor + func changeSubscription() async throws { + let subscriptions = realm.subscriptions + try await subcriptions.update { + subscriptions.remove { + QuerySubscription { + $0.assignee == "Joe Doe" + } + } + } + } + +.. include:: /includes/swift-concurrency-mainactor.rst + +Subscription Set State +~~~~~~~~~~~~~~~~~~~~~~ + +Use the :swift-sdk:`SubscriptionSet.state +` +property to read the current state of the subscription set. + +The ``superseded`` state is a :swift-sdk:`SyncSubscriptionState +` +that can occur when another thread updates a subscription on a different +instance of the subscription set. If the state becomes ``superseded``, you must +obtain a new instance of the subscription set before you can update it. + +.. include:: /includes/note-sync-state-complete.rst + +.. _ios-update-subscriptions-with-new-query: + +Update Subscriptions with a New Query +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can update a subscription's query using ``updateQuery``. In this example, +we search for a subscription matching our query and then update it with a +new query. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription.swift + :language: swift + +You can also :swift-sdk:`search for a subscription by name +` +. In this example, we search for a subscription query by name and then +update it with a new query. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription-by-name.swift + :language: swift + +.. _ios-remove-subscriptions: + +Remove Subscriptions +~~~~~~~~~~~~~~~~~~~~ + +To remove subscriptions, you can: + +- Remove a single subscription query +- Remove all subscriptions to a specific object type +- Remove all unnamed subscriptions +- Remove all subscriptions + +When you remove a subscription query, Realm asynchronously removes the +synced data that matched the query from the client device. + +.. _ios-remove-query-by-name: + +Remove a Single Subscription +```````````````````````````` + +You can remove a specific subscription query in a subscription update block +using ``remove``. Specify the query by name or use the query as a string +to find the appropriate subscription query to remove. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-single-subscription.swift + :language: swift + +Remove All Subscriptions to an Object Type +`````````````````````````````````````````` + +If you want to remove all subscriptions to a specific object type, use the +``removeAll`` method with ``ofType`` in a subscription update block. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-subscriptions-to-object-type.swift + :language: swift + +Remove All Unnamed Subscriptions +````````````````````````````````` + +.. versionadded:: 10.43.0 + +You may want to remove unnamed subscriptions that are transient or dynamically +generated, but leave named subscriptions in place. + +You can remove all unnamed subscriptions from the subscription set by +setting ``unnamedOnly`` to ``true`` when you call the ``removeAll`` method: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-unnamed-subscriptions.swift + :language: swift + +Remove All Subscriptions +```````````````````````` + +To remove all subscriptions from the subscription set, use the ``removeAll`` +method in a subscription update block. + +.. important:: + + If you remove all subscriptions and do not add a new one, you'll + get an error. A realm opened with a flexible sync configuration needs + at least one subscription to sync with the server. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-subscriptions.swift + :language: swift + +.. _sdks-sync-subscription-performance-considerations: + +Performance Considerations +-------------------------- + +API Efficiency +~~~~~~~~~~~~~~ + +Adding several subscriptions with the ``.subscribe()`` and ``.unsubscribe()`` +APIs described in the :ref:`swift-flexible-sync-results-subscribe-api` section +is less efficient than performing batch updates when you manually +manage subscriptions. On every ``.subscribe()``, the Swift SDK opens a new +update block. For better performance adding multiple +subscriptions, use the ``subscriptions.update`` API described in the +:ref:`ios-sync-subscribe-to-queryable-fields` section. + +Group Updates for Improved Performance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/sync-memory-performance.rst + +.. _swift-flexible-sync-rql-limitations: + +Flexible Sync RQL Requirements and Limitations +----------------------------------------------- + +.. include:: /includes/flex-sync-limitations.rst + Placeholder page for information about managing Flexible Sync subscriptions. .. _sdks-add-sync-subscriptions: From 3dc1603b6f0c234e7f4c88b9fa62bfcf259188e6 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 13:14:35 -0400 Subject: [PATCH 02/25] Fix snooty build errors to get to a clean build --- source/sdk/sync/configure-and-open-synced-database.txt | 5 +++++ source/sdk/sync/manage-sync-subscriptions.txt | 6 +++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/sdk/sync/configure-and-open-synced-database.txt b/source/sdk/sync/configure-and-open-synced-database.txt index d073d7040d..b0f0a6c227 100644 --- a/source/sdk/sync/configure-and-open-synced-database.txt +++ b/source/sdk/sync/configure-and-open-synced-database.txt @@ -24,3 +24,8 @@ Placeholder page for configuring and opening a synced database. Download Changes Before Open ---------------------------- + +.. _sdks-open-synced-database-offline: + +Open a Synced Database Offline +------------------------------ diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index edf75b2f67..8773bf2dd7 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -235,7 +235,7 @@ This option uses the ``RLMWaitForSyncMode`` enum, whose cases are: The app must have an internet connection when ``.subscribe()`` is executed. - .never: Never wait to download matching objects. The app needs an internet connection for the user to authenticate the first time the app launches, but - can :ref:`open offline ` on subsequent + can :ref:`open offline ` on subsequent launches using cached credentials. You can optionally specify a ``timeout`` value of type :apple:`TimeInterval @@ -562,12 +562,12 @@ API Efficiency ~~~~~~~~~~~~~~ Adding several subscriptions with the ``.subscribe()`` and ``.unsubscribe()`` -APIs described in the :ref:`swift-flexible-sync-results-subscribe-api` section +APIs described in the :ref:`sdks-sync-results-subscribe-api` section is less efficient than performing batch updates when you manually manage subscriptions. On every ``.subscribe()``, the Swift SDK opens a new update block. For better performance adding multiple subscriptions, use the ``subscriptions.update`` API described in the -:ref:`ios-sync-subscribe-to-queryable-fields` section. +:ref:`sdks-manually-manage-subscriptions` section. Group Updates for Improved Performance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 798ffab742a7fb77c7655dbeaadeb7b4cf1752f1 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 13:49:40 -0400 Subject: [PATCH 03/25] Add subscribe to query with name section --- ...bscribe-to-query-with-name-description.rst | 7 ++ ...e-to-query-with-name-js-ts-description.rst | 7 ++ ...bscribe-to-query-with-name-description.rst | 1 + ...bscribe-to-query-with-name-description.rst | 4 + ...criptions-subscribe-to-query-with-name.rst | 61 ++++++++++ ...-sync-subscriptions-subscribe-to-query.rst | 5 +- source/sdk/sync/manage-sync-subscriptions.txt | 114 ++++++++++++++---- 7 files changed, 173 insertions(+), 26 deletions(-) create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..8af0b49ddc --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1,7 @@ +To subscribe to a query with a name, pass the following arguments to ``subscribe()``: + +- ``RealmResults query``: Required. A ``RealmResults`` object that you can create using the + :ref:`Realm Query Language `. +- ``String name``: Optional. Name for the subscription that you can refer to. + +In the following example, we subscribe to two new named queries. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst new file mode 100644 index 0000000000..055e5a5a88 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst @@ -0,0 +1,7 @@ +To subscribe to a query: + +#. Query for the objects that you want to read and write. +#. Call ``subscribe()`` on the query results to create a sync subscription for + objects matching the query. +#. Pass a ``SubscriptionOptions`` object that contains the ``name`` property to + ``subscribe()``. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..c09b1846de --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1 @@ +To add a name to the subscription, pass a string when you call ``.subscribe()``. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..e267599a3e --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1,4 @@ +To give a query subscription a name, supply a string name argument for the +``name`` parameter when you call the :swift-sdk:`.subscribe() +` +method. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst new file mode 100644 index 0000000000..8f537be6f5 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-named-query.kt + :language: kotlin + :emphasize-lines: 3 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst index 4da480a49e..b7b71da242 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -18,8 +18,9 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart - :language: dart + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false - id: java content: | diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 8773bf2dd7..263baa622e 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -34,11 +34,14 @@ You can manually add, update, and remove subscriptions to determine which data syncs to the client device. Or you can subscribe to queries instead of or in addition to manually managing subscriptions. -Subscriptions -------------- +What are Subscriptions? +----------------------- When you configure Device Sync in Atlas, you specify which fields your -client application can query using **subscriptions**. +client application can query. The SDK tracks these queries through a +**subscription**. When you subscribe to a query, the SDK automatically tracks +changes to data matching that subscription, and uploads and downloads relevant +data. Each subscription corresponds to a query on **queryable fields** for a specific object type. See :ref:`Queryable Fields ` @@ -48,7 +51,12 @@ For each query subscription, the SDK looks for data matching the query. Data matching the subscription, where the user has the appropriate permissions, syncs between clients and the backend application. -You can construct queries with RQL, or one of the SDK-idiomatic query engines. +The SDK tracks these queries through a **subscription set**, which is a +collection of subscriptions. You can add, remove, and update subscriptions in +the subscription set. + +You can construct subscription queries with RQL, or one of the SDK-idiomatic +query engines. - :ref:`realm-query-language` - :ref:`java-filter-data` @@ -111,33 +119,35 @@ You can: - Add subscriptions with an optional subscription name: - - You can subscribe to query ``Results``. This - automatically adds the subscription to the subscription set. + - You can subscribe to a database query. This automatically adds the + subscription to the subscription set. - Manually add a subscription to the subscription set with the subscribe API. Use this API if you need more control over subscriptions for performance optimization or business-logic reasons. See :ref:`Performance Considerations ` for more information. -- React to subscription state -- Update subscriptions with new queries -- Remove individual subscriptions or all subscriptions for an object type +- React to subscription state changes. +- Update subscriptions with new queries. +- Remove individual subscriptions or all subscriptions for an object type. .. _sdks-sync-results-subscribe-api: Subscribe to Queries -------------------- -To simplify subscription management, the SDK offers APIs to subscribe and -unsubscribe from a query's ``Results`` set. These APIs abstract away the -details of manually adding and removing subscriptions. This API is not -available for all languages. If your preferred language does not provide this -API, refer to :ref:`sdks-manually-manage-subscriptions`. +To simplify subscription management, the SDK offers APIs to subscribe to and +unsubscribe from a query directly. These APIs abstract away the details of +manually adding and removing subscriptions. This API is not available for all +languages. If your preferred language does not provide this API, refer to +:ref:`sdks-manually-manage-subscriptions`. .. important:: The Subscribe to Queries API is in Preview The APIs described here are currently in Preview. These APIs may be subject to change in the future. +.. _sdks-subscribe-to-query: + Subscribe to a Query ~~~~~~~~~~~~~~~~~~~~ @@ -151,6 +161,13 @@ This creates an unnamed subscription and adds it to the subscription set, similar to :ref:`manually creating a subscription `. +.. tip:: + + If your app works with multiple subscriptions, or if you want to update + a subscription, you should add a name when you subscribe to a query. For + details, refer to the :ref:`sdks-subscribe-to-query-with-name` section on + this page. + .. tabs-drivers:: .. tab:: @@ -200,19 +217,68 @@ similar to :ref:`manually creating a subscription .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +.. _sdks-subscribe-to-query-with-name: + Subscribe to a Query with a Subscription Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your app works with multiple subscriptions, or if you want to update -a subscription, you may want to add a name when you subscribe to a query. +a subscription, you should add a name when you subscribe to a query. -You can later use this name to :ref:`update a subscription's query -`, :ref:`check for a subscription by -name `, or :ref:`remove the -query by name `. +You can later use this name to: -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift - :language: swift +- :ref:`Check for an existing subscription by name ` +- :ref:`Update a subscription's query ` +- :ref:`Remove the query by name ` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query--with-name-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst Wait for a Query Subscription to Sync ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -392,7 +458,7 @@ subscribe to all the ``Team`` objects, you could do this: .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift :language: swift -.. _ios-check-existing-subscriptions-before-adding: +.. _sdks-check-existing-subscriptions-before-adding: Check for Existing Subscriptions Before Adding a Subscription ````````````````````````````````````````````````````````````` @@ -468,7 +534,7 @@ obtain a new instance of the subscription set before you can update it. .. include:: /includes/note-sync-state-complete.rst -.. _ios-update-subscriptions-with-new-query: +.. _sdks-update-subscriptions-with-new-query: Update Subscriptions with a New Query ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -503,7 +569,7 @@ To remove subscriptions, you can: When you remove a subscription query, Realm asynchronously removes the synced data that matched the query from the client device. -.. _ios-remove-query-by-name: +.. _sdks-remove-query-by-name: Remove a Single Subscription ```````````````````````````` From 3340d72bb87c55b6615b04c778a5f2ff2713e8e2 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 15:33:31 -0400 Subject: [PATCH 04/25] Add wait for sync details --- ...uery-subscriptions-to-sync-description.rst | 21 ++++++ ...-query-subscription-to-sync-escription.rst | 16 ++++ ...query-subscription-to-sync-description.rst | 17 +++++ ...query-subscription-to-sync-description.rst | 22 ++++++ ...s-wait-for-query-subscriptions-to-sync.rst | 62 ++++++++++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 73 ++++++++++++++----- 6 files changed, 191 insertions(+), 20 deletions(-) create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst create mode 100644 source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst new file mode 100644 index 0000000000..3836c62430 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst @@ -0,0 +1,21 @@ +When you do need specify the desired sync behavior, configure the +:flutter-sdk:`waitForSyncMode ` option. + +This example uses the ``firstTime`` option, which is the default behavior. +A subscription with ``firstTime`` behavior only waits for sync to finish when a +subscription is first created. + +.. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-first-time-subscribe-api.dart + :language: dart + :emphasize-lines: 5 + +The other supported ``waitForSyncMode`` options are: + +- ``always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can open offline on subsequent launches using cached credentials. + +You can optionally specify a :flutter-sdk:`cancellationToken ` +to limit how long the sync download runs. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst new file mode 100644 index 0000000000..6f4f742c8c --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst @@ -0,0 +1,16 @@ +When you call the ``.subscribe()`` method on a query, you can optionally +specify the ``WaitForSync`` behavior, which is an enum of options describing +different sync behaviors. + +The supported ``WaitForSync`` options are: + +- ``FirstTime``: Wait for sync to finish when a subscription is first created. +- ``Always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``Never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value to limit how long the sync +download runs. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..344909a423 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,17 @@ +To wait for a query subscription to sync, pass the ``waitForSync`` parameter +when you call the :swift-sdk:`.subscribe() +` +method. This takes a ``WaitForSyncMode`` enum argument, whose cases are: + +- **.onCreation**: Wait to download matching objects when your app creates the + subscription. Otherwise, return without waiting for new downloads. The + app must have an internet connection the first time you add the subscription. +- **.always**: Wait to download matching objects when ``.subscribe()`` is executed. + The app must have an internet connection when ``.subscribe()`` is executed. +- **.never**: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value of type :apple:`TimeInterval +`. diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..4a96cf8a8e --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,22 @@ +When you call the ``.subscribe()`` method on a query, you can optionally +specify the ``WaitForSync`` behavior, which is an enum of options describing +different sync behaviors. + +This example uses the ``FirstTime`` option, which is the default behavior. +A subscription with ``FirstTime`` behavior only waits for sync to finish when a +subscription is first created. + +.. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-wait-first.ts + :language: typescript + +The other supported ``WaitForSync`` options are: + +- ``Always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``Never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value to limit how long the sync +download runs. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst new file mode 100644 index 0000000000..7035c4c165 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-with-timeout-subscribe-api.dart + :language: dart + :emphasize-lines: 5-6 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-wait-for-sync.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-with-timeout.ts + :language: typescript diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 263baa622e..6e09e1704f 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -246,7 +246,7 @@ You can later use this name to: .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query--with-name-description.rst + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst .. tab:: :tabid: java @@ -283,29 +283,62 @@ You can later use this name to: Wait for a Query Subscription to Sync ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you subscribe to a query's ``Results`` set, that set does not contain -objects until it syncs. If your app creates objects, you may not need to -download synced data before the user works with it. However, if your app -requires data from the server before the user can work with it, you can -specify that a subscription should ``waitForSync``: +When you subscribe to a query, that query's results do not contain objects +until the subscription syncs with Atlas. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-wait-for-sync.swift - :language: swift +If your app creates objects, you may not need to download synced data before +the user works with it. However, if your app requires data from Atlas before +the user can work with your app, you can specify that the SDK should wait for +the subscription query data to sync before proceeding. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst -This option uses the ``RLMWaitForSyncMode`` enum, whose cases are: + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst + + .. tab:: + :tabid: typescript -- .onCreation: Wait to download matching objects when your app creates the - subscription. Otherwise, return without waiting for new downloads. The - app must have an internet connection the first time you add the subscription. -- .always: Wait to download matching objects when ``.subscribe()`` is executed. - The app must have an internet connection when ``.subscribe()`` is executed. -- .never: Never wait to download matching objects. The app needs an internet - connection for the user to authenticate the first time the app launches, but - can :ref:`open offline ` on subsequent - launches using cached credentials. + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst -You can optionally specify a ``timeout`` value of type :apple:`TimeInterval -`. +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst Unsubscribe from a Query ~~~~~~~~~~~~~~~~~~~~~~~~ From 2556731299175258db71ae0432e1eade3ae60ecb Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 16:10:57 -0400 Subject: [PATCH 05/25] Add details about unsubscribing from queries --- ...ons-unsubscribe-from-query-description.rst | 2 + ...uery-subscription-to-sync-description.rst} | 0 ...subscribe-from-query-js-ts-description.rst | 1 + ...uery-subscription-to-sync-description.rst} | 0 ...iptions-subscribe-to-query-description.rst | 13 +++ ...s-unsubscribe-from-query-not-supported.rst | 3 + ...ons-unsubscribe-from-query-description.rst | 4 + ...-sync-subscriptions-subscribe-to-query.rst | 3 +- ...c-subscriptions-unsubscribe-from-query.rst | 62 ++++++++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 82 +++++++++++++++---- 10 files changed, 155 insertions(+), 15 deletions(-) create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst rename source/includes/api-details/dart/sync/{manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst => manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst} (100%) create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst rename source/includes/api-details/javascript/sync/{manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst => manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst} (100%) create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst new file mode 100644 index 0000000000..2ff60fb92c --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst @@ -0,0 +1,2 @@ +You can unsubscribe from a query's results using :flutter-sdk:`unsubscribe() +`. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst similarity index 100% rename from source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst rename to source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst new file mode 100644 index 0000000000..777a390204 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst @@ -0,0 +1 @@ +To unsubscribe from a query's results, call the ``unsubscribe()`` method. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst similarity index 100% rename from source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-escription.rst rename to source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst index 1f1f04a4d5..3598a6621a 100644 --- a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -1,2 +1,15 @@ To subscribe to a ``RealmQuery`` or ``RealmResults`` set, call the :kotlin-sdk:`.subscribe() ` method. + +.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + :language: kotlin + +Update a Query Subscription +``````````````````````````` + +You can update a named query subscription with a new query +by setting ``updateExisting`` to ``true``. + +This updates the subscription automatically, instead of requiring you to +:ref:`manually update the subscription ` +in the subscription set. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst new file mode 100644 index 0000000000..c68cb245d1 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst @@ -0,0 +1,3 @@ +Kotlin does not currently support the unsubscribe API. Instead, you can +:ref:`manually remove subscriptions ` from the +subscription set. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst new file mode 100644 index 0000000000..5d1e903325 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst @@ -0,0 +1,4 @@ +You can unsubscribe from a query's ``Results`` set by calling +:swift-sdk:`.unsubscribe() +` on the query. +This removes the subscription from the ``MutableSubscriptionSet``. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst index b7b71da242..ae4331383c 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -45,8 +45,9 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-query-by-name.kt :language: kotlin + :emphasize-lines: 9 - id: swift content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst new file mode 100644 index 0000000000..5f964999fe --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscription-unsubscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-api-unsubscribe.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-unsubscribe.ts + :language: typescript diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 6e09e1704f..e13c8af169 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -130,6 +130,8 @@ You can: - Update subscriptions with new queries. - Remove individual subscriptions or all subscriptions for an object type. +Subscriptions persist across user sessions unless you unsubscribe from them. + .. _sdks-sync-results-subscribe-api: Subscribe to Queries @@ -161,6 +163,8 @@ This creates an unnamed subscription and adds it to the subscription set, similar to :ref:`manually creating a subscription `. +Subscriptions persist across user sessions unless you unsubscribe from them. + .. tip:: If your app works with multiple subscriptions, or if you want to update @@ -280,6 +284,8 @@ You can later use this name to: .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst +.. _sdks-wait-for-query-subscription-to-sync: + Wait for a Query Subscription to Sync ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -306,7 +312,7 @@ the subscription query data to sync before proceeding. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst .. tab:: :tabid: java @@ -321,7 +327,7 @@ the subscription query data to sync before proceeding. .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst .. tab:: :tabid: kotlin @@ -336,28 +342,75 @@ the subscription query data to sync before proceeding. .. tab:: :tabid: typescript - .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync-description.rst + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst +.. _sdks-unsubscribe-from-query: + Unsubscribe from a Query ~~~~~~~~~~~~~~~~~~~~~~~~ -You can unsubscribe from a query's ``Results`` set using the -:swift-sdk:`.unsubscribe() -` API: +You can unsubscribe from a query that you have previously subscribed to. +Unsubscribing removes the suscription from the subscription set, similar to +:ref:`manually removing a subscription `. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-api-unsubscribe.swift - :language: swift +A query results set may still contain objects after calling the unsubscribe +method if the subscription set contains another overlapping subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst + + .. tab:: + :tabid: typescript -This removes the subscription from the ``MutableSubscriptionSet``, -similar to :ref:`manually removing a subscription `. + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst -A ``Results`` set may still contain objects after calling ``.unsubscribe()`` -if another subscription exists that contains overlapping objects. +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst -Calling ``.unsubscribe()`` does not wait for objects to be removed from the -realm. There is no API to wait for ``.unsubscribe()`` to sync with the server. +The unsubscribe method returns before objects matching the removed subscription +are deleted from the database. Sync continues in the background based on the +new set of subscriptions. There is no API to wait for the unsubscribe method +to sync with the server. Subscribe to an Actor-Confined Query ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -588,6 +641,7 @@ update it with a new query. :language: swift .. _ios-remove-subscriptions: +.. _sdks-remove-subscriptions: Remove Subscriptions ~~~~~~~~~~~~~~~~~~~~ From 210bb7ec71d63183e2d43b03623edb07a5b5e3d7 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 16:19:50 -0400 Subject: [PATCH 06/25] Move Swift-specific info into a Swift include --- ...criptions-subscribe-to-query-description.rst | 17 +++++++++++++++++ ...ge-sync-subscriptions-subscribe-to-query.rst | 2 +- source/sdk/sync/manage-sync-subscriptions.txt | 16 ---------------- 3 files changed, 18 insertions(+), 17 deletions(-) diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst index bb032761e0..344d761a4b 100644 --- a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -1,3 +1,20 @@ Use the :swift-sdk:`.subscribe() ` method to create a subscription for objects matching the query. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-unnamed.swift + :language: swift + +Subscribe to an Actor-Confined Query +```````````````````````````````````` + +You can subscribe to actor-confined queries. For more information about +working with actor-confined database instances, refer to +:ref:`swift-actor-isolated-realm`. + +You can subscribe to an actor-confined query on the MainActor. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-main-actor.swift + :language: swift + +Or subscribe to a query on a custom actor. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst index ae4331383c..6cccdfe02a 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -52,7 +52,7 @@ - id: swift content: | - .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-unnamed.swift + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-custom-actor.swift :language: swift - id: typescript diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index e13c8af169..57606aca3e 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -412,22 +412,6 @@ are deleted from the database. Sync continues in the background based on the new set of subscriptions. There is no API to wait for the unsubscribe method to sync with the server. -Subscribe to an Actor-Confined Query -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can subscribe to an actor-confined query on the MainActor: - -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-main-actor.swift - :language: swift - -Or subscribe to a query on a custom actor: - -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-custom-actor.swift - :language: swift - -For more information about actor-confined realms, refer to -:ref:`swift-actor-isolated-realm`. - .. _sdks-manually-manage-subscriptions: Manually Manage Subscriptions From 260c3a744ad2431f9dbd52e7d57f5bb29fd2d0b8 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 17:55:55 -0400 Subject: [PATCH 07/25] Add info about adding subscriptions --- ...criptions-add-subscription-description.rst | 10 ++ ...ge-sync-subscriptions-add-subscription.rst | 20 +++ ...criptions-add-subscription-description.rst | 11 ++ ...ge-sync-subscriptions-add-subscription.rst | 12 ++ ...ons-add-subscription-js-ts-description.rst | 11 ++ ...criptions-add-subscription-description.rst | 10 ++ ...criptions-add-subscription-description.rst | 10 ++ ...bscriptions-add-multiple-subscriptions.rst | 64 +++++++ ...c-subscriptions-add-named-subscription.rst | 61 +++++++ ...ge-sync-subscriptions-add-subscription.rst | 58 +++++++ ...subscriptions-add-unnamed-subscription.rst | 63 +++++++ ...tions-subscribe-to-all-objects-of-type.rst | 62 +++++++ source/sdk/sync/manage-sync-subscriptions.txt | 157 +++++++++++++----- 13 files changed, 507 insertions(+), 42 deletions(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..6b5e2e0206 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``add`` method with the object type to append the new subscription + to the subscription set. Optionally, add a query to subscribe to only a + subset of the objects that match the query. + +.. include:: /includes/note-cpp-supports-subset-of-rql.rst diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst new file mode 100644 index 0000000000..4d094bc13a --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst @@ -0,0 +1,20 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's :dotnet-sdk:`Realm.Subscriptions ` + property. +#. Open a subscription ``Update`` block. +#. Create a subscription to a specific object type. Optionally add a query to + subscribe to only a subset of the objects that match the query. +#. Call the ``Subscriptions.Add`` method with the subscription you just created + to append the new subscription to the subscription set. + +Alternately, to add a subscription to an existing subscription set, create +the query and then call :dotnet-sdk:`IQueryable.SubscribeAsync() +`. + +The ``SubscribeAsync`` method is shorthand for using :dotnet-sdk:`SubscriptionSet.Update() +` +to create an update block, and then calling the :dotnet-sdk:`SubscriptionSet.Add() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..3cf9f96457 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,11 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property to interact with the + :flutter-sdk:`SubscriptionSet `. +#. Open a subscription ``update`` block by calling + :flutter-sdk:`SubscriptionSet.update() `. +#. Call the ``add`` method to append the new subscription to the + subscription set. +#. Pass a ``RealmResults`` query that you can create using the + :ref:`Realm Query Language query `. Optionally, add a query name. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst new file mode 100644 index 0000000000..b382351c85 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst @@ -0,0 +1,12 @@ +To add a subscription: + +1. Open the synced database. +#. Call the ``getSubscriptions()`` method to interact with the subscription set. +#. Open a subscription ``update`` block using + :java-sdk:`SubscriptionSet.update() + `. +#. Use the :java-sdk:`MutableSubscriptionSet.addOrUpdate() + ` + method to append the new subscription to the subscription set. +#. Call ``Subscription.create()`` with a query to a specific object type. + Optionally, add a name for the query. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst new file mode 100644 index 0000000000..a839d6898a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst @@ -0,0 +1,11 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's :js-sdk:`realm.subscriptions + ` property. +#. Open a subscription ``update`` block. +#. Create a subscription to a specific object type. Optionally add a query to + subscribe to only a subset of the objects that match the query. +#. Call the ``add()`` method with the subscription you just created + to append the new subscription to the subscription set. Optionally, you can + name the subscription. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..eeb87c49aa --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``add`` method to append the new subscription to the + subscription set. +#. Pass a query with the name of the object type. Optionally, use + :ref:`Realm Query Language query ` to query only a subset of the objects. + You can also add an optional query name. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..064327fcec --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``append`` method to append the new subscription to the + subscription set. +#. Pass a ``QuerySubscription`` with the name of the object + type. Optionally, use the ``.where`` or ``NSPredicate`` query API to + subscribe to only a subset of the objects of the type. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst new file mode 100644 index 0000000000..1868a70916 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + While you can add a single query using ``SubscribeAsync``, you can + only batch multiple queries within a ``SubscriptionSet.Update`` block. + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.update-multiple-subscriptions.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-multiple-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst new file mode 100644 index 0000000000..16b8a5a7c5 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-objects-matching-a-query.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-named-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-by-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst new file mode 100644 index 0000000000..9e5d1d2ef3 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.subasync.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-single-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst new file mode 100644 index 0000000000..02a7d487b1 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-without-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst new file mode 100644 index 0000000000..937aa11ef7 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 57606aca3e..1a69e582e0 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -417,50 +417,36 @@ to sync with the server. Manually Manage Subscriptions ----------------------------- -You can use the ``subscriptions`` API to manually manage a set of -subscriptions to specific queries on queryable fields. +As an alternative to the subscribe to a query API, you can manually manage the +subscriptions in a subscription set. You can: - Add subscriptions -- React to subscription state +- React to subscription state change - Update subscriptions with new queries - Remove individual subscriptions or all subscriptions for an object type Data matching the subscription, where the user has the appropriate -permissions, syncs between devices and the backend application. +permissions, syncs between devices and Atlas. You can specify an optional string name for your subscription. -When you create a subscription, Realm looks for data matching a query on a +When you create a subscription, the SDK looks for data matching a query on a specific object type. You can have multiple subscription sets on different object types. You can also have multiple queries on the same object type. -.. example:: - - You can create a subscription with an explicit name. Then, you can - search for that subscription by name to update or remove it. - - .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-by-name.swift - :language: swift - - If you do not specify a ``name`` for a subscription, you can search - for the subscription by the query string. - - .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-without-name.swift - :language: swift - .. note:: Duplicate subscriptions Subscription names must be unique. Trying to append a subscription with the same name as an existing subscription throws an error. If you do not explicitly name a subscription, and instead subscribe - to the same unnamed query more than once, Realm does not persist + to the same unnamed query more than once, the SDK does not persist duplicate queries to the subscription set. If you subscribe to the same query more than once under different names, - Realm persists both subscriptions to the subscription set. + the SDK persists both subscriptions to the subscription set. .. _sdks-sync-subscriptions-add-subscription: @@ -468,23 +454,123 @@ Add a Subscription ~~~~~~~~~~~~~~~~~~ Add a subscription in a subscriptions update block. You append each -new subscription to the client's Realm subscriptions. +new subscription to the client's SDK subscriptions. -.. include:: /includes/swift-concurrency-mainactor.rst +Subscriptions persist across user sessions unless you remove them from the +subscription set. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-single-subscription.swift - :language: swift +If your app is adding subscriptions for the first time, some SDK languages +provide a special parameter to :ref:`set initial subscriptions +` or recalculate initial subscriptions on app +launch. + +.. tip:: + + If your app works with multiple subscriptions, or if you want to update + a subscription, you should add a name when you subscribe to a query. For + details, refer to the :ref:`sdks-add-named-subscription` section on + this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst + +.. _sdks-add-unnamed-subscription: + +Add Unnamed Subscription +```````````````````````` + +If your app doesn't need to update or remove subscriptions, you can add a +subscription without a name. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst + +.. _sdks-add-named-subscription: + +Add a Named Subscription +```````````````````````` + +If your app might need to update or remove subscriptions, you should add a +name when you create a subscription. You can use the name to find and update +or remove the appropriate subscription later. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst + +.. _sdks-add-multiple-subscriptions: + +Add Multiple Subscriptions +`````````````````````````` You can add multiple subscriptions within a subscription update block, including subscriptions of different object types. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-multiple-subscriptions.swift - :language: swift +Performing query updates requires Atlas to recalculate which documents match the +query. We strongly advise designing your application to minimize updates. You +can do this by batching additions and changes to the subscription set. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst + +.. _sdks-subscribe-to-all-objects-of-type: + +Subscribe to All Objects of a Specific Type +``````````````````````````````````````````` + +In addition to syncing all objects that match a given query, you can subscribe +to all objects of a specific type. You do this by appending a subscription +without providing a query. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst .. _ios-sync-add-initial-subscriptions: +.. _sdks-set-initial-subscriptions: -Bootstrap the Realm with Initial Subscriptions -`````````````````````````````````````````````` +Set Initial Subscriptions +````````````````````````` .. versionadded:: 10.28.0 @@ -515,19 +601,6 @@ objects to sync based on the desired date range every time the app starts. .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions-rerun-on-open.swift :language: swift -Subscribe to All Objects of a Specific Type -``````````````````````````````````````````` - -In addition to syncing all objects that match a given query, you can subscribe -to all objects of a specific type. You do this by appending a subscription -without providing a query. - -For example, if you don't want to see a specific team, but instead want to -subscribe to all the ``Team`` objects, you could do this: - -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift - :language: swift - .. _sdks-check-existing-subscriptions-before-adding: Check for Existing Subscriptions Before Adding a Subscription From 92deef7846b424cac6c2bef56663c7cb70e7e714 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 11 Jul 2024 18:01:32 -0400 Subject: [PATCH 08/25] Fix snooty build errors --- ... manage-sync-subscriptions-add-subscription-description.rst} | 0 source/sdk/sync/manage-sync-subscriptions.txt | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename source/includes/api-details/java/sync/{manage-sync-subscriptions-add-subscription.rst => manage-sync-subscriptions-add-subscription-description.rst} (100%) diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst similarity index 100% rename from source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription.rst rename to source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 1a69e582e0..ed7f38c009 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -481,7 +481,7 @@ launch. .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-add-subscription-description.rst + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst .. tab:: :tabid: dart From 5e8cbbe8bd04395e5675322c3c2ac1591a1be504 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 12:37:12 -0400 Subject: [PATCH 09/25] Add details about setting initial subscriptions --- ...riptions-add-subscription-description.rst} | 0 ...-set-initial-subscriptions-description.rst | 8 ++ ...et-initial-subscriptions-not-supported.rst | 3 + ...nitial-subscriptions-js-ts-description.rst | 10 +++ ...-set-initial-subscriptions-description.rst | 22 +++++ ...-set-initial-subscriptions-description.rst | 22 +++++ ...ubscriptions-set-initial-subscriptions.rst | 60 +++++++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 88 +++++++++++++------ 8 files changed, 184 insertions(+), 29 deletions(-) rename source/includes/api-details/csharp/sync/{manage-sync-subscriptions-add-subscription.rst => manage-sync-subscriptions-add-subscription-description.rst} (100%) create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst create mode 100644 source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst similarity index 100% rename from source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription.rst rename to source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..096ded9576 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,8 @@ +You can bootstrap the database with an initial subscription set +when you open it with a :dotnet-sdk:`FlexibleSyncConfiguration +`. Set the +:dotnet-sdk:`PopulateInitialSubscriptions +` +parameter to a callback that is invoked when the database instance is created. +Add the queries you want to use to bootstrap the database, as shown in the +following example. diff --git a/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst b/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst new file mode 100644 index 0000000000..e1e62323ee --- /dev/null +++ b/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst @@ -0,0 +1,3 @@ +The selected language does not provide a dedicated API to set initial +subscriptions. Instead, refer to the :ref:`sdks-sync-subscriptions-add-subscription` +section on this page. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst new file mode 100644 index 0000000000..014f56125a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst @@ -0,0 +1,10 @@ +To set initial subscriptions, include the ``initialSubscriptions`` field in +your realm's :js-sdk:`SyncConfiguration `. +Within the ``initialSubscriptions`` object, add an ``update`` +field set to a callback that subscribes to queries. + +By default, initial subscriptions are only created the first time the database +is opened. If your app needs to rerun this initial subscription every time the app +starts, you can set ``rerunOnOpen`` to ``true``. You might need to do this to +re-run dynamic time ranges or other queries that require a re-computation of +static variables for the subscription. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..af1d87010f --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,22 @@ +You can bootstrap the database with an initial subscription set when you open +it with the +:kotlin-sync-sdk:`SyncConfiguration() `. + +Pass the ``initialSubscriptions`` parameter with the +subscription queries you want to use to bootstrap the database: + +.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.initialize-subscribe-query-realm-app.kt + :language: kotlin + +If your app needs to rerun this initial subscription every +time the app starts, you can pass an additional parameter: +``rerunOnOpen``. This is a boolean that denotes whether the +initial subscription should re-run every time the +app starts. You might need to do this to re-run dynamic time +ranges or other queries that require a re-computation of +static variables for the subscription. + +In this example, we only want incomplete tasks. With +``rerunOnOpen`` set to ``true``, the query dynamically +recalculates the relevant objects to sync based on the +desired query results every time the app starts. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..71668ef9b7 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,22 @@ +You can set initial subscriptions through the +:swift-sdk:`flexibleSyncConfiguration() +`. +Pass the ``initialSubscriptions`` parameter with the subscription queries +you want to use to bootstrap the database: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions.swift + :language: swift + +If your app needs to rerun this initial subscription every time the app starts, +you can pass an additional parameter - ``rerunOnOpen``. This is a bool that +denotes whether the initial subscription should re-run every time the +app starts. You might need to do this to re-run dynamic time ranges +or other queries that require a re-computation of static variables for the +subscription. + +In this example, we don't want users to be overwhelmed by irrelevant tasks, +so we'll load only tasks due within the previous 7 days and the next 7 days. +Tasks that were due more than a week ago are no longer relevant, and tasks +that are due further out than the next week are also not relevant. With +``rerunOnOpen`` here, the query dynamically recalculates the relevant +objects to sync based on the desired date range every time the app starts. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst new file mode 100644 index 0000000000..35a32bb632 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.bootstrap-a-subscription.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.set-initial-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.initialize-subscribe-query-realm-app-rerun.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions-rerun-on-open.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.set-initial-subscriptions.ts + :language: typescript diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index ed7f38c009..3a2e56b856 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -460,9 +460,9 @@ Subscriptions persist across user sessions unless you remove them from the subscription set. If your app is adding subscriptions for the first time, some SDK languages -provide a special parameter to :ref:`set initial subscriptions -` or recalculate initial subscriptions on app -launch. +provide a special parameter to set initial subscriptions or recalculate +initial subscriptions on app launch. For details, skip to the +:ref:`set initial subscriptions ` on this page. .. tip:: @@ -566,40 +566,70 @@ without providing a query. .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst -.. _ios-sync-add-initial-subscriptions: .. _sdks-set-initial-subscriptions: Set Initial Subscriptions ````````````````````````` -.. versionadded:: 10.28.0 - You must have at least one subscription before you can read from or write -to the realm. You can bootstrap a realm with an initial subscription set -when you open it with the :swift-sdk:`flexibleSyncConfiguration() -`. -Pass the ``initialSubscriptions`` parameter with the subscription queries -you want to use to bootstrap the realm: +to the database. You can bootstrap the database with an initial subscription +set when you open it. This ensures your app can start working with the database +successfully right away. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions.swift - :language: swift +.. tabs-drivers:: -If your app needs to rerun this initial subscription every time the app starts, -you can pass an additional parameter - ``rerunOnOpen``. This is a bool that -denotes whether the initial subscription should re-run every time the -app starts. You might need to do this to re-run dynamic time ranges -or other queries that require a re-computation of static variables for the -subscription. - -In this example, we don't want users to be overwhelmed by irrelevant tasks, -so we'll load only tasks due within the previous 7 days and the next 7 days. -Tasks that were due more than a week ago are no longer relevant, and tasks -that are due further out than the next week are also not relevant. With -``rerunOnOpen`` here, the query dynamically recalculates the relevant -objects to sync based on the desired date range every time the app starts. - -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions-rerun-on-open.swift - :language: swift + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst + +At any point after setting initial subscriptions, you can: + +- :ref:`Add more subscriptions to the subscription set. ` +- :ref:`Update existing subscriptions in the subscription set. ` +- :ref:`Remove subscriptions from the subscription set. ` .. _sdks-check-existing-subscriptions-before-adding: From e1f1678c0b72afa6560fe70e41f924bc25fbecdf Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 12:58:51 -0400 Subject: [PATCH 10/25] Add details around duplicate subscriptions --- ...ns-duplicate-subscriptions-description.rst | 3 + ...ons-duplicate-subscription-description.rst | 9 +++ ...ns-duplicate-subscriptions-description.rst | 16 +++++ source/sdk/sync/manage-sync-subscriptions.txt | 64 ++++++++++++------- 4 files changed, 68 insertions(+), 24 deletions(-) create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst new file mode 100644 index 0000000000..f6dcfc1c71 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst @@ -0,0 +1,3 @@ +If you add a duplicate **unnamed** subscription with the same query, the SDK +automatically removes it; adding an identical **named** subscription is a +no-op. Therefore, in both cases, duplicate subscriptions are ignored. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst new file mode 100644 index 0000000000..37b53635a2 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst @@ -0,0 +1,9 @@ +Subscription names must be unique. Adding a subscription +with the same name as an existing subscription throws an error. + +If you do not explicitly name a subscription, and instead subscribe +to the same unnamed query more than once, the SDD does not persist +duplicate queries to the subscription set. + +If you subscribe to the same query more than once under different names, +the SDK persists both subscriptions to the subscription set. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst new file mode 100644 index 0000000000..caffbff8ab --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst @@ -0,0 +1,16 @@ +Subscription names must be unique. Trying to append a subscription +with the same name as an existing subscription throws an error. + +If you do not explicitly name a subscription, and instead subscribe +to the same unnamed query more than once, the SDK does not persist +duplicate queries to the subscription set. + +If you subscribe to the same query more than once under different names, +the SDK persists both subscriptions to the subscription set. + +If your application flow appends the same named subscription to the subscription +set every time you run the application, add a check for an existing subscription +before appending it. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.check-before-adding-subscription.swift + :language: swift diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 3a2e56b856..b887382d05 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -436,18 +436,6 @@ When you create a subscription, the SDK looks for data matching a query on a specific object type. You can have multiple subscription sets on different object types. You can also have multiple queries on the same object type. -.. note:: Duplicate subscriptions - - Subscription names must be unique. Trying to append a subscription - with the same name as an existing subscription throws an error. - - If you do not explicitly name a subscription, and instead subscribe - to the same unnamed query more than once, the SDK does not persist - duplicate queries to the subscription set. - - If you subscribe to the same query more than once under different names, - the SDK persists both subscriptions to the subscription set. - .. _sdks-sync-subscriptions-add-subscription: Add a Subscription @@ -520,6 +508,46 @@ initial subscriptions on app launch. For details, skip to the .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst +.. Some of the SDKs have special behavior around duplicate subs, but others don't. +.. Adding this tab set to show/hide relevant details. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: typescript + .. _sdks-add-unnamed-subscription: Add Unnamed Subscription @@ -631,18 +659,6 @@ At any point after setting initial subscriptions, you can: - :ref:`Update existing subscriptions in the subscription set. ` - :ref:`Remove subscriptions from the subscription set. ` -.. _sdks-check-existing-subscriptions-before-adding: - -Check for Existing Subscriptions Before Adding a Subscription -````````````````````````````````````````````````````````````` - -If your application flow appends the same named subscription to the subscription -set every time you run the application, this is disallowed. In this case, -add a check for an existing subscription before appending it: - -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.check-before-adding-subscription.swift - :language: swift - .. _ios-sync-check-subscription-state: .. _ios-sync-react-to-subscription-changes: From 84a55a3dd2f8fa369a800c9e69ea727b48d2ca8a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 15:57:22 -0400 Subject: [PATCH 11/25] Add details about waiting for subscription changes to sync --- ...cription-changes-to-sync-not-supported.rst | 1 + ...bscription-changes-to-sync-description.rst | 17 +++ ...bscription-changes-to-sync-description.rst | 11 ++ ...bscription-changes-to-sync-description.rst | 11 ++ ...tion-changes-to-sync-js-ts-description.rst | 10 ++ ...bscription-changes-to-sync-description.rst | 10 ++ ...bscription-changes-to-sync-description.rst | 32 ++++++ ...t-for-subscription-changes-to-sync.rst.rst | 62 +++++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 101 +++++++++++------- 9 files changed, 218 insertions(+), 37 deletions(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst new file mode 100644 index 0000000000..3dfc9d778b --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst @@ -0,0 +1 @@ +C++ does not currently provide an API to wait for subscription changes to sync. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..30ad632f86 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,17 @@ +Use the :dotnet-sdk:`SubscriptionSet.WaitForSynchronizationAsync() +` +method to wait for the server to acknowledge this set of subscriptions. If the +server rejects the change, the :dotnet-sdk:`SubscriptionSetState +` will be an error state, and +an exception will be thrown. + +An exception may occur if: + +- An unsupported query is subscribed to. Subscribing to an unsupported query + will pause synchronization. To resume synchronization, :ref:`remove the + unsupported query `. + +- You are performing an invalid action, such as adding an object that does not + match a subscription. This triggers a :ref:`client reset `: + data is erased from the device, and a new copy of the data is created without + any subscriptions in the set. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..23967457f8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,11 @@ +Use :flutter-sdk:`Realm.subscriptions.waitForSynchronization() ` +to wait for the server to acknowledge this set of subscriptions. +If the server rejects the change, and an exception is thrown. + +An exception may occur if: + +- You subscribe to an unsupported query. Subscribing to an unsupported query will pause synchronization. + To resume synchronization, :ref:`remove the unsupported query `. +- You are performing an invalid action, such as adding an object that does not match a subscription. + This triggers a :ref:`client reset `: data is erased from the device, + and a new copy of the data is created without any subscriptions in the set. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..2afb9f60e3 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,11 @@ +Use the :java-sdk:`waitForInitialRemoteData() +` +builder method to force your application to block until client subscription +data synchronizes to the backend before opening the database. + +Alternately, you could use :java-sdk:`SubscriptionSet.waitForSynchronization() +` +or :java-sdk:`SubscriptionSet.waitForSynchronizationAsync() +` +to delay execution until subscription sync completes after instantiating +a sync connection. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst new file mode 100644 index 0000000000..b0efe1a73d --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst @@ -0,0 +1,10 @@ +You can wait for subscription changes to sync in two ways: + +- ``await`` the call to :js-sdk:`SubscriptionSet.update() + `, which returns a promise + that resolves when the ``SubscriptionSet`` is synchronized, or is rejected if + there was an error during synchronization. +- Explicitly call :js-sdk:`SubscriptionSet.waitForSynchronization() + ` to + wait for the server to acknowledge this set of subscriptions and return the + matching objects, or throw an error. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..3ff1ce2bc3 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,10 @@ +Use the :kotlin-sync-sdk:`SyncConfiguration.waitForInitialRemoteData() +` +builder method to force your application to block until client subscription +data synchronizes to the backend before opening the database. + +Alternately, you can use :kotlin-sync-sdk:`SubscriptionSet.waitForSynchronization() +` +to delay execution until subscription sync completes after instantiating +a sync connection. + diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..6392d63492 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,32 @@ +Async/Await +``````````` + +If your application uses async/await, you don't need the ``onComplete`` +block. The update executes asynchronously and throws an +error if the update cannot complete successfully. + +.. code-block:: swift + + @MainActor + func changeSubscription() async throws { + let subscriptions = realm.subscriptions + try await subcriptions.update { + subscriptions.remove { + QuerySubscription { + $0.assignee == "Joe Doe" + } + } + } + } + +Completion +`````````` + +If your application does not use Swift's async/await feature, you can react +to subscription changes syncing with the server using the ``onComplete`` +block. This block is called after subscriptions are synchronized with the +server. If you want to react to subscription state changes by redrawing a +UI, for example, or taking another action based on changes to the data set, +take those actions in ``onComplete``. This is also where you can handle +optional errors that occur during synchronization. + diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst new file mode 100644 index 0000000000..a6c833fe07 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.wait-for-synchronization.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-for-subscription-change.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.wait-for-subscription-sync.java + :language: java + :emphasize-lines: 10 + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.wait-for-subscription-sync.kt + :language: kotlin + :emphasize-lines: 11-14 + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.wait-for-subscription-changes.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-subscription-with-oncomplete.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index b887382d05..600c53efc8 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -231,7 +231,6 @@ a subscription, you should add a name when you subscribe to a query. You can later use this name to: -- :ref:`Check for an existing subscription by name ` - :ref:`Update a subscription's query ` - :ref:`Remove the query by name ` @@ -522,7 +521,7 @@ initial subscriptions on app launch. For details, skip to the .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst .. tab:: :tabid: java @@ -543,7 +542,7 @@ initial subscriptions on app launch. For details, skip to the .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst .. tab:: :tabid: typescript @@ -659,54 +658,82 @@ At any point after setting initial subscriptions, you can: - :ref:`Update existing subscriptions in the subscription set. ` - :ref:`Remove subscriptions from the subscription set. ` -.. _ios-sync-check-subscription-state: -.. _ios-sync-react-to-subscription-changes: +.. _sdks-wait-for-subscription-changes-to-sync: Wait for Subscription Changes to Sync ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Updating the subscription set locally is only one component -of changing a subscription. After the local subscription change, the realm +Updating the subscription set on the device is only one component +of changing a subscription. After the client app subscription change, the SDK synchronizes with the server to resolve any updates to the data due to the subscription change. This could mean adding or removing data from the -synced realm. +synced database. -Pre Async/Await -``````````````` +**Adding New Subscriptions** -If your application does not use Swift's async/await feature, you can react -to subscription changes syncing with the server using the ``onComplete`` -block. This block is called after subscriptions are synchronized with the -server. If you want to react to subscription state changes by redrawing a -UI, for example, or taking another action based on changes to the data set, -take those actions in ``onComplete``. This is also where you can handle -optional errors that occur during synchronization. +If your app creates objects, you may not need to download synced data before +the user works with it. However, if your app requires data from Atlas before +the user can work with your app, you can specify that the SDK should wait for +the subscription changes to sync before proceeding. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-subscription-with-oncomplete.swift - :language: swift +**Updating Existing Subscriptions** + +When you update an existing subscription, this could mean adding new data or +removing data from the synced database. If this involves things like changing +user permissions to add or remove data, or if your app otherwise makes these +changes visible to users in the UI, you may want to wait for subscription +changes to update before proceeding with app execution. Otherwise, the changes +may appear to the user as unexpected changes to the data set later during +"normal" app execution. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk -Async/Await -``````````` + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst -If your application uses async/await, you don't need the ``onComplete`` -block. The update executes asynchronously and throws an -error if the update cannot complete successfully. + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: java -.. code-block:: swift + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: typescript - @MainActor - func changeSubscription() async throws { - let subscriptions = realm.subscriptions - try await subcriptions.update { - subscriptions.remove { - QuerySubscription { - $0.assignee == "Joe Doe" - } - } - } - } + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst -.. include:: /includes/swift-concurrency-mainactor.rst +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst Subscription Set State ~~~~~~~~~~~~~~~~~~~~~~ From 111e12a01e1c80eed4088432c61af04415b98a21 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 17:02:54 -0400 Subject: [PATCH 12/25] Add info about Subscription Set State --- ...s-subscription-set-state-not-supported.rst | 1 + ...heck-subscriptionset-state-description.rst | 9 +++ ...ons-subscription-set-state-description.rst | 8 ++ ...ons-subscription-set-state-description.rst | 17 +++++ ...bscription-set-state-js-ts-description.rst | 13 ++++ ...ons-subscription-set-state-description.rst | 9 +++ ...ons-subscription-set-state-description.rst | 9 +++ source/includes/note-sync-state-complete.rst | 15 ---- source/sdk/sync/manage-sync-subscriptions.txt | 76 ++++++++++++++++--- 9 files changed, 133 insertions(+), 24 deletions(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst delete mode 100644 source/includes/note-sync-state-complete.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst new file mode 100644 index 0000000000..39726ed371 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst @@ -0,0 +1 @@ +C++ does not currently provide an API to check the state of a subscription set. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst new file mode 100644 index 0000000000..970bb40b92 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst @@ -0,0 +1,9 @@ +Use the :dotnet-sdk:`SubscriptionSet.State +` +property to read the current state of the subscription set. + +The ``Superseded`` state is a :dotnet-sdk:`SubscriptionSetState +` that can occur when another +thread updates a subscription on a different instance of the subscription set. +If the state becomes ``Superseded``, you must obtain a new instance of the +subscription set before you can update it. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..6b9a6dcd3d --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,8 @@ +Use the :flutter-sdk:`Realm.subscriptions.state ` +property to read the current state of the subscription set. + +The ``superseded`` state is a :flutter-sdk:`SubscriptionSetState +` that can occur when another thread updates a +subscription on a different instance of the subscription set. If the state +becomes ``superseded``, you must obtain a new instance of the subscription set +before you can update it. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..92eca87599 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,17 @@ +You can watch the state of the subscription set with the +:java-sdk:`SubscriptionSet.State ` enum. +You can use subscription state to: + +- Show a progress indicator while data is downloading +- Find out when a subscription set becomes superseded + +You can access the state of your application's subscription set using +:java-sdk:`SubscriptionSet.getState() `. + +Superseded +`````````` + +``SUPERSEDED`` is a ``SubscriptionSet.State`` that can occur when another +thread writes a subscription on a different instance of the +subscription set. If the state becomes ``SUPERSEDED``, you must obtain +a new instance of the subscription set before you can write to it. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst new file mode 100644 index 0000000000..6803e3ba45 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst @@ -0,0 +1,13 @@ +You can check the :js-sdk:`subscription state ` +to see if the server has acknowledged the subscription and the device has +downloaded the data locally. + +You can use subscription state to: + +- Trigger error handling +- Show if the transaction is pending or has completed +- Find out when a subscription set is superseded, and you should obtain a + new instance of the subscription set to write a subscription change + +The :js-sdk:`SubscriptionSetState enum ` +provides information about the status of a subscription. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..92a9b7dc97 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,9 @@ +Use the :kotlin-sync-sdk:`SubscriptionSet.state +` +property to read the current state of the subscription set. + +``SUPERCEDED`` (sic -- note alternate spelling) is a :kotlin-sync-sdk:`SubscriptionSetState +` +that can occur when another thread writes a subscription on a different instance +of the subscription set. If the state becomes ``SUPERCEDED``, you must obtain a +new instance of the subscription set before you can write to it. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..4a77164174 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,9 @@ +Use the :swift-sdk:`SubscriptionSet.state +` +property to read the current state of the subscription set. + +The ``superseded`` state is a :swift-sdk:`SyncSubscriptionState +` +that can occur when another thread updates a subscription on a different +instance of the subscription set. If the state becomes ``superseded``, you must +obtain a new instance of the subscription set before you can update it. diff --git a/source/includes/note-sync-state-complete.rst b/source/includes/note-sync-state-complete.rst deleted file mode 100644 index 61a660564f..0000000000 --- a/source/includes/note-sync-state-complete.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. note:: Subscription State "Complete" - - The subscription set state "complete" does not mean "sync is done" or "all - documents have been synced". "Complete" means the following two things have - happened: - - - The subscription has become the active subscription set that is currently - being synchronized with the server. - - The documents that matched the subscription *at the time the subscription - was sent to the server* are now on the local device. Note that this does - not necessarily include all documents that currently match the - subscription. - - The Realm SDK does not provide a way to check whether all documents that - match a subscription have synced to the device. diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 600c53efc8..a35efe5246 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -735,20 +735,78 @@ may appear to the user as unexpected changes to the data set later during .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst +.. _sdks-subscription-set-state: + Subscription Set State ~~~~~~~~~~~~~~~~~~~~~~ -Use the :swift-sdk:`SubscriptionSet.state -` -property to read the current state of the subscription set. +You can check the state of the subscription set through to find out the current +status of the subscription set. This provides information about whether +Atlas has registered the subscription that is on the device. It does not +make any guarantees about the state of the documents matching the subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst + + .. tab:: + :tabid: kotlin -The ``superseded`` state is a :swift-sdk:`SyncSubscriptionState -` -that can occur when another thread updates a subscription on a different -instance of the subscription set. If the state becomes ``superseded``, you must -obtain a new instance of the subscription set before you can update it. + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst -.. include:: /includes/note-sync-state-complete.rst + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst + +.. note:: Subscription State "Complete" + + The subscription set state "complete" does not mean "sync is done" or "all + documents have been synced". "Complete" means the following two things have + happened: + + - The subscription has become the active subscription set that is currently + being synchronized with the server. + - The documents that matched the subscription *at the time the subscription + was sent to the server* are now on the device. Note that this does + not necessarily include all documents that currently match the + subscription. + + The SDK does not provide a way to check whether all documents that + match a subscription have synced to the device. .. _sdks-update-subscriptions-with-new-query: From cd331962c2c647e8786cdbf4e79f95f36d022317 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 17:09:10 -0400 Subject: [PATCH 13/25] Fix name --- ...nc-subscriptions-check-subscription-set-state-description.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/api-details/csharp/sync/{manage-sync-subscriptions-check-subscriptionset-state-description.rst => manage-sync-subscriptions-check-subscription-set-state-description.rst} (100%) diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscription-set-state-description.rst similarity index 100% rename from source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscriptionset-state-description.rst rename to source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscription-set-state-description.rst From 2b7f3f706995eb3316a77e9530f7feadd8906b31 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 12 Jul 2024 17:16:21 -0400 Subject: [PATCH 14/25] No, really, fix the include file name --- ...age-sync-subscriptions-subscription-set-state-description.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/api-details/csharp/sync/{manage-sync-subscriptions-check-subscription-set-state-description.rst => manage-sync-subscriptions-subscription-set-state-description.rst} (100%) diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscription-set-state-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst similarity index 100% rename from source/includes/api-details/csharp/sync/manage-sync-subscriptions-check-subscription-set-state-description.rst rename to source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst From fa41759f27e490a6fb0949a79bef4a4ea40ad773 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Mon, 15 Jul 2024 12:00:30 -0400 Subject: [PATCH 15/25] Add details about updating subscriptions --- ...-change-named-subscription-description.rst | 8 + ...nge-unnamed-subscription-not-supported.rst | 7 + ...-change-named-subscription-description.rst | 12 ++ ...nge-unnamed-subscription-not-supported.rst | 7 + ...-change-named-subscription-description.rst | 10 ++ ...nge-unnamed-subscription-not-supported.rst | 7 + ...-change-named-subscription-description.rst | 5 + ...nge-unnamed-subscription-not-supported.rst | 7 + ...e-named-subscription-js-ts-description.rst | 11 ++ ...named-subscription-js-ts-not-supported.rst | 7 + ...-change-named-subscription-description.rst | 10 ++ ...nge-unnamed-subscription-not-supported.rst | 7 + ...iptions-subscribe-to-query-description.rst | 2 +- ...-change-named-subscription-description.rst | 6 + ...hange-unnamed-subscription-description.rst | 5 + ...ubscriptions-change-named-subscription.rst | 58 +++++++ ...scriptions-change-unnamed-subscription.rst | 61 ++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 142 ++++++++++++++++-- 18 files changed, 355 insertions(+), 17 deletions(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..2906771174 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,8 @@ +To update a subscription set, use the ``subscription().updates()`` function. +This gives you access to a :cpp-sdk:`mutable_sync_subscription_set +` where you can use the +``update_subscription()`` function to update a specific :cpp-sdk:`sync_subscription +`. + +You can change a ``sync_subscription``'s query in an update. You can add, remove, +or update the query string for a given ``sync_subscription``. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..873604f507 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to change an unnamed subscription. If you know +in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and :ref:`create new subscriptions +` with the desired query. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..8c706fa020 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,12 @@ +You can update a named subscription with a new query. To update a subscription's +query, pass the new query and a subscription option with the name of the +subscription that you want to update to the +``SubscriptionSet.Add()`` method. Like adding a new subscription, +you must update a subscription within an update block by calling +``SubscriptionSet.Update()`` method. + +The ``SubscriptionOptions.UpdateExisting`` field must be set to ``true``, or +else attempting to change the subscription throws an exception. + +In the following example, long running tasks are re-defined to be any tasks that +have taken more than 130 minutes. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..a992561df3 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C# does not provide the ability to change an unnamed subscription. If you know +in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..4539d167ee --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,10 @@ +You can update a named subscription with a new query. To update a subscription's +query, open an update block with ``SubscriptionSet.update()``. +In the callback function of the update block, pass the following arguments to ``MutableSubscriptionSet.add()``: + +- The new query +- The name of the subscription that you want to update +- ``update: true`` + +In the following example, long trains are re-defined to be any trains that +have more than 10 cars. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..77d9e230dd --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +Dart does not provide the ability to change an unnamed subscription. If you +know in advance that your app may need to change subscriptions, :ref:`create +the subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..7d5f2b3775 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,5 @@ +You can update subscriptions using :java-sdk:`SubscriptionSet.update() +`. +In this example, we use :java-sdk:`MutableSubscriptionSet.addOrUpdate() +` +to update the query for the subscription named "my frog subscription". diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..71d788c522 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +The Java SDK does not support updating subscriptions created without a name. +If you know in advance that your app may need to change subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can look up unnamed subscriptions by query, :ref:`remove them +from the subscription set `, and :ref:`create a new +subscription ` with the desired query. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst new file mode 100644 index 0000000000..03cb2426f4 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst @@ -0,0 +1,11 @@ +You can update a named subscription with a new query. To update a subscription's +query, pass the new query and a subscription option with the name of the +subscription that you want to update to the ``MutableSubscriptionSet.add()`` +method. Like adding a new subscription, you must update a subscription within a +transaction by calling ``subscriptions.update()``. + +The ``SubscriptionOptions.throwOnUpdate`` field must be set to ``false``, or +else attempting to change the subscription throws an exception. + +In the following example, long-running tasks are re-defined to be any tasks that +have taken more than 180 minutes. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst new file mode 100644 index 0000000000..2a69c057c4 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst @@ -0,0 +1,7 @@ +The JS SDK does not provide the ability to change an unnamed subscription. If +you know in advance that your app may need to change subscriptions, :ref:`create +the subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..44328b0aa0 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,10 @@ +You can update subscriptions using +:kotlin-sync-sdk:`SubscriptionSet.update() +`. + +In this example, we use :kotlin-sync-sdk:`MutableSubscriptionSet.add() +`. +to update the query for the subscription named ``"bob_smith_teams"``. + +You must set the ``updateExisting`` parameter to ``true`` to update +a subscription - otherwise the SDK throws an exception. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..41ff017cf1 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +Kotlin does not provide the ability to change an unnamed subscription. If you +know in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. \ No newline at end of file diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst index 3598a6621a..75aabe9891 100644 --- a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -11,5 +11,5 @@ You can update a named query subscription with a new query by setting ``updateExisting`` to ``true``. This updates the subscription automatically, instead of requiring you to -:ref:`manually update the subscription ` +:ref:`manually update the subscription ` in the subscription set. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..f6bb0a9aac --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,6 @@ +You can :swift-sdk:`search for a subscription by name +`, +and then update the named subscription. + +To change a subscription query, call the ``updateQuery`` method on an existing +query inside a ``subscriptions.update`` block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst new file mode 100644 index 0000000000..fcec0ae0b7 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst @@ -0,0 +1,5 @@ +To change a subscription query, call the ``updateQuery`` method on an existing +query inside a ``subscriptions.update`` block. + +In this example, we search for a subscription matching our query and then +update it with a new query. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst new file mode 100644 index 0000000000..50b96e269f --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.change-subscription-query.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.update-a-subscription.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.update-subscriptions-new-query.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.update-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + :emphasize-lines: 14 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription-by-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst new file mode 100644 index 0000000000..16c919f0b3 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-query.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-query.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-subscriptions-by-query.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index a35efe5246..f81c6312c8 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -231,7 +231,7 @@ a subscription, you should add a name when you subscribe to a query. You can later use this name to: -- :ref:`Update a subscription's query ` +- :ref:`Change a subscription's query ` - :ref:`Remove the query by name ` .. tabs-drivers:: @@ -655,7 +655,7 @@ successfully right away. At any point after setting initial subscriptions, you can: - :ref:`Add more subscriptions to the subscription set. ` -- :ref:`Update existing subscriptions in the subscription set. ` +- :ref:`Change existing subscriptions in the subscription set. ` - :ref:`Remove subscriptions from the subscription set. ` .. _sdks-wait-for-subscription-changes-to-sync: @@ -808,25 +808,134 @@ make any guarantees about the state of the documents matching the subscription. The SDK does not provide a way to check whether all documents that match a subscription have synced to the device. -.. _sdks-update-subscriptions-with-new-query: +.. _sdks-change-subscription-queries: -Update Subscriptions with a New Query -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Change Subscription Queries +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can update a subscription's query using ``updateQuery``. In this example, -we search for a subscription matching our query and then update it with a -new query. +You can change the queries in a subscription set. You might want to do this +when business logic dictates syncing a different subset of objects, such as +when a user unlocks new features in an app. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription.swift - :language: swift +- Change a named query +- Change an unnamed query -You can also :swift-sdk:`search for a subscription by name -` -. In this example, we search for a subscription query by name and then -update it with a new query. +When you change a query, consider how it interacts with any other queries that +may be in the subscription set. You may need to +:ref:`add ` or +:ref:`remove ` other subscriptions, such as: -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription-by-name.swift - :language: swift +- Adding a new subscription when a change to a query introduces new linked objects +- Removing a subscription when an overlapping query inadvertently exposes + objects you don't want to sync + +.. _sdks-change-named-subscription: + +Change a Named Subscription +``````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst + +.. _sdks-change-unnamed-subscription: + +Change an Unnamed Subscription +`````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst .. _ios-remove-subscriptions: .. _sdks-remove-subscriptions: @@ -845,6 +954,7 @@ When you remove a subscription query, Realm asynchronously removes the synced data that matched the query from the client device. .. _sdks-remove-query-by-name: +.. _sdks-remove-single-subscription: Remove a Single Subscription ```````````````````````````` From a91137310cc368fd4a5865574c2382b7cba0fdae Mon Sep 17 00:00:00 2001 From: dacharyc Date: Mon, 15 Jul 2024 18:19:19 -0400 Subject: [PATCH 16/25] Add details about removing subscriptions --- ...nge-unnamed-subscription-not-supported.rst | 2 +- ...s-remove-all-subscriptions-description.rst | 2 + ...criptions-to-object-type-not-supported.rst | 8 + ...ll-unnamed-subscriptions-not-supported.rst | 5 + ...-remove-named-subscription-description.rst | 4 + ...ubscription-by-reference-not-supported.rst | 7 + ...ove-unnamed-subscription-not-supported.rst | 7 + ...s-remove-all-subscriptions-description.rst | 8 + ...bscriptions-to-object-type-description.rst | 14 + ...-all-unnamed-subscriptions-description.rst | 5 + ...-remove-named-subscription-description.rst | 4 + ...-subscription-by-reference-description.rst | 4 + ...emove-unnamed-subscription-description.rst | 7 + ...s-remove-all-subscriptions-description.rst | 2 + ...bscriptions-to-object-type-description.rst | 3 + ...-all-unnamed-subscriptions-description.rst | 4 + ...-remove-named-subscription-description.rst | 3 + ...-subscription-by-reference-description.rst | 4 + ...emove-unnamed-subscription-description.rst | 6 + ...s-remove-all-subscriptions-description.rst | 3 + ...bscriptions-to-object-type-description.rst | 4 + ...ll-unnamed-subscriptions-not-supported.rst | 6 + ...-remove-named-subscription-description.rst | 5 + ...-subscription-by-reference-description.rst | 4 + ...ove-unnamed-subscription-not-supported.rst | 5 + ...ve-all-subscriptiond-js-ts-description.rst | 4 + ...tions-to-object-type-js-ts-description.rst | 5 + ...nnamed-subscriptions-js-ts-description.rst | 3 + ...-remove-named-subscription-description.rst | 5 + ...ription-by-reference-js-ts-description.rst | 5 + ...emove-unnamed-subscription-description.rst | 7 + ...s-remove-all-subscriptions-description.rst | 4 + ...bscriptions-to-object-type-description.rst | 4 + ...-all-unnamed-subscriptions-description.rst | 2 + ...-remove-named-subscription-description.rst | 3 + ...-subscription-by-reference-description.rst | 3 + ...ove-unnamed-subscription-not-supported.rst | 4 + ...s-remove-all-subscriptions-description.rst | 2 + ...bscriptions-to-object-type-description.rst | 4 + ...-all-unnamed-subscriptions-description.rst | 2 + ...-remove-named-subscription-description.rst | 4 + ...-subscription-by-reference-description.rst | 3 + ...emove-unnamed-subscription-description.rst | 3 + ...-remove-named-subscription-description.rst | 5 + ...emove-unnamed-subscription-description.rst | 4 + ...migration-remove-and-add-subscriptions.rst | 4 +- ...emove-all-subscriptions-to-object-type.rst | 60 +++ ...subscriptions-remove-all-subscriptions.rst | 58 +++ ...tions-remove-all-unnamed-subscriptions.rst | 62 ++++ ...ubscriptions-remove-named-subscription.rst | 58 +++ ...tions-remove-subscription-by-reference.rst | 64 ++++ ...scriptions-remove-unnamed-subscription.rst | 63 ++++ source/sdk/sync/manage-sync-subscriptions.txt | 351 ++++++++++++++++-- 53 files changed, 880 insertions(+), 42 deletions(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst create mode 100644 source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst create mode 100644 source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst index 873604f507..65de4b06e9 100644 --- a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -3,5 +3,5 @@ in advance that your app may need to change subscriptions, :ref:`create the subscription with a name `. Alternately, you can :ref:`remove all subscriptions -`, and :ref:`create new subscriptions +`, and :ref:`create new subscriptions ` with the desired query. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..f1a3ed12ff --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all subscriptions in a subscription set using the ``clear()`` +function. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst new file mode 100644 index 0000000000..cbdaf4abf7 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst @@ -0,0 +1,8 @@ +C++ does not provide the ability to remove all subscriptions to a specific +object type. If you know in advance that your app may need to remove +subscriptions, :ref:`create the subscription with a name +`. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst new file mode 100644 index 0000000000..1352044012 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst @@ -0,0 +1,5 @@ +C++ does not provide the ability to remove all unnamed subscriptions. + +Instead, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..1cd8a4af8a --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific subscription by name using the ``remove()`` function +inside a ``subscription().updates()`` block. Removing a subscription by name +throws an error if the subscription does not exist, so you should check for a +subscription before removing it. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst new file mode 100644 index 0000000000..8f03828d03 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to remove a subscription by reference. If +you know in advance that your app may need to remove subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..fe09a2d741 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to remove a single unnamed subscription. If +you know in advance that your app may need to remove subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..ece7173f0e --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,8 @@ +Within an update block, you can remove all subscriptions from the +subscriptions set. Call the :dotnet-sdk:`RemoveAll() +` +method on the ``SubscriptionSet``. + +By default, the ``RemoveAll()`` method only removes unnamed subscriptions. +Set the optional ``removedName`` boolean to ``true`` to also remove named +subscriptions. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..8aecf715e7 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,14 @@ +Within an update block, you can remove remove all unnamed subscriptions of a +class by passing the class name as a string to the +:dotnet-sdk:`RemoveAll("ClassName") +` +method. The ``RemoveAll()`` method has an optional second argument that is a +boolean, ``removedName``, which also removes the named subscriptions if it is +set to ``true``. ``removedName`` is set to false by default. + +Alternatively, you can remove all unnamed subscriptions of an object type +with :dotnet-sdk:`RemoveAll() +`. +The ``RemoveAll()`` method has an optional boolean ``removedName`` argument +that also removes the named subscriptions if it is set to ``true``. The ``removedName`` +argument is set to false by default. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..40e1d2267a --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,5 @@ +Within an update block, you can remove all unnamed subscriptions from the +subscriptions set. Call the :dotnet-sdk:`RemoveAll() +` +method on the ``SubscriptionSet``, with the optional boolean ``removedName`` +argument set to false. This removes only unnamed subscriptions. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..12c9660706 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +Within an update block, you can remove a specific subscription by name. Pass the +name to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..89a887081b --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +Within an update block, you can remove a specific subscription by reference. +Pass the subscription to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..190c5885e8 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,7 @@ +Within an update block, you can remove an unnamed subscription by its query. +Pass the query to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. + +In the following example, the subscription to tasks with an owner named 'Ben' is +removed from the subscriptions set. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..e4e2bef0ea --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +Within a subscription update block, you can remove all subscriptions from the +subscriptions set with :flutter-sdk:`MutableSubscriptionSet.clear() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..48af685b31 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,3 @@ +You can remove all subscriptions for a given SDK object type. Within a +subscription update block, call +:flutter-sdk:`MutableSubscriptionSet.removeByType() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..2cf97aa4c8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,4 @@ +Within a subscription update block, you can remove all unnamed subscriptions +from the subscriptions set by calling :flutter-sdk:`MutableSubscriptionSet.clear() +` with an ``unnamedOnly`` argument +set to ``true``. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..a72c42cf45 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,3 @@ +Within an update block, you can remove a specific subscription by name. Pass +the name to :flutter-sdk:`MutableSubscriptionSet.removeByName() +`. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..14ca6d8c65 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +You can remove a subscription if you have a reference to its :flutter-sdk:`Subscription +` object. +Within a subscription update block, pass the ``Subscription`` reference to +:flutter-sdk:`MutableSubscriptionSet.remove() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..703a0bba83 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,6 @@ +Within an update block, you can remove a specific subscription by query. +Open an update block with ``SubscriptionSet.update()``. Pass the +``Subscription`` to :flutter-sdk:`MutableSubscriptionSet.removeByQuery() +`. + +In the following example, the subscription for all ``Plane`` objects is removed. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..a5d01f3365 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,3 @@ +To remove all subscriptions from the subscription set, use +:java-sdk:`removeAll() ` +with no arguments. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..f9cad38d10 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +If you want to remove all subscriptions to a specific object type, pass +a class to the :java-sdk:`removeAll() +` +method. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst new file mode 100644 index 0000000000..8b4cf26586 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst @@ -0,0 +1,6 @@ +The Java SDK does not provide a method to remove all unnamed subscriptions. + +Instead, you can remove all subscriptions from the subscription set, with +:java-sdk:`removeAll() `. +Then, :ref:`create the new subscriptions +` that your app needs. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..b3bc09b867 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +You can remove a specific subscription query +using :java-sdk:`MutableSubscriptionSet.remove() +`. +The ``remove()`` method takes a subscription name, or a reference to the +subscription itself. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..0c30406c98 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +You can remove a subscription by reference when you pass the +subscription to the :java-sdk:`MutableSubscriptionSet.remove() +` +method. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..bb3ea0c8e7 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,5 @@ +The Java SDK does not provide a method to remove an unnamed subscription +directly. However, you can look up a subscription by query, and pass the +subscription to the :java-sdk:`MutableSubscriptionSet.remove() +` +method to remove it from the subscription set. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst new file mode 100644 index 0000000000..75ec192a8f --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst @@ -0,0 +1,4 @@ +To remove all subscriptions from the subscriptions set, execute a transaction on +the subscriptions set. Call :js-sdk:`removeAll() +` on the +``MutableSubscriptionSet`` within the transaction. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst new file mode 100644 index 0000000000..4cad711bff --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst @@ -0,0 +1,5 @@ +To remove all subscriptions on a specific object type, execute a transaction on +the subscriptions set. Within the transaction, pass the object type as a string +to the :js-sdk:`removeByObjectType +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst new file mode 100644 index 0000000000..62124d90df --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst @@ -0,0 +1,3 @@ +You can remove all unnamed subscriptions from the subscription set by +calling ``.removeUnnamed()`` on ``mutableSubs``. ``.removeUnnamed()`` returns +the number of unnamed subscriptions removed. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..f97ec343a8 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +To remove a specific subscription by name, execute a transaction on the +subscriptions set. Within the transaction, pass the name to the +:js-sdk:`removeByName() +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst new file mode 100644 index 0000000000..c95b0be89f --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst @@ -0,0 +1,5 @@ +If you have a reference to a subscription, you can remove that subscription. To +do so, execute a transaction on the subscriptions set. Within the transaction, +pass the reference variable to the :js-sdk:`removeSubscription +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..656bdcbaab --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,7 @@ +You can remove a specific subscription by query by executing a transaction on +the subscriptions set. Pass the query to the :js-sdk:`remove() +` method on the +``MutableSubscriptionSet`` within a transaction. + +In the following example, the subscription to tasks with an owner named 'Ben' is +removed from the subscriptions set. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..792c44ad45 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,4 @@ +To remove all subscriptions from the subscription set, use +:kotlin-sync-sdk:`MutableSubscriptionSet.removeAll() +` +with no arguments. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..ea1d064208 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +If you want to remove all subscriptions to a specific object type, pass +a class to the :kotlin-sync-sdk:`MutableSubscriptionSet.removeAll() +` +method. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..c28ae9c786 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all unnamed (anonymous) subscriptions from the subscription set by +setting ``anonymousOnly`` to ``true`` when you call the ``removeAll`` method. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..bd58a591ba --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,3 @@ +You can remove a named subscription query by passing the subscription +name to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..897416d887 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,3 @@ +You can remove a subscription by reference by passing the subscription +to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..b6194b8f72 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,4 @@ +Kotlin does not provide an API to directly remove an unnamed subscription. +However, you can you can look up the subscription by query and then pass +the reference to the subscription to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..eeba7ff845 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +To remove all subscriptions from the subscription set, use the ``removeAll`` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..085a21bf36 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +You can remove all subscriptions to a specific object type by calling the +:swift-sdk:`removeAll +` +method with an ``ofType`` argument in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..09f0ebeb74 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all unnamed subscriptions from the subscription set by +setting ``unnamedOnly`` to ``true`` when you call the ``removeAll`` method. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..49f9f3b06c --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific named subscription by passing the name to the +:swift-sdk:`remove() +` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..2489e8372c --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,3 @@ +You can remove a subscription by reference by passing the subscription to the +:swift-sdk:`remove() ` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..f7e20a1eb2 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,3 @@ +You can remove a specific subscription query in a subscription update block +by calling ``remove``. You can find a subscription matching the query to remove +the appropriate subscription. diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..f97ec343a8 --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +To remove a specific subscription by name, execute a transaction on the +subscriptions set. Within the transaction, pass the name to the +:js-sdk:`removeByName() +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..3c3b6ba3ee --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific subscription by query by executing a transaction on +the subscriptions set. Pass the query to the :js-sdk:`remove() +` method on the +``MutableSubscriptionSet`` within a transaction. diff --git a/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst b/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst index 861f97a29e..fd9465f894 100644 --- a/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst +++ b/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst @@ -2,8 +2,8 @@ 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 `. -2. :ref:`Manually add the relevant subscriptions in your client codebase `. +1. :ref:`Remove the automatically-generated subscriptions `. +2. :ref:`Manually add the relevant subscriptions in your client codebase `. This enables you to see all of your subscription logic together in your codebase for future iteration and debugging. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst new file mode 100644 index 0000000000..ff795f25dc --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-all-subscriptions-of-object-type.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-object-type.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions-to-an-object-type.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions-to-an-object-type.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-all-subscriptions-of-object-type.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-subscriptions-to-an-object-type.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-subscriptions-to-object-type.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst new file mode 100644 index 0000000000..65d7fa07e7 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.clear-all-subscriptions.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-all-subscriptions.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-all-subscriptions.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-all-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-subscriptions.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst new file mode 100644 index 0000000000..f12e8a5758 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-remove-unnamed.ts + :language: typescript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-unnamed-subscriptions.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-unnamed-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst new file mode 100644 index 0000000000..91a87b0761 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-subscription-by-name.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-name.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-single-subscription.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-single-subscription.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-subscription-by-name.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-single-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-single-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst new file mode 100644 index 0000000000..c3f3aab125 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-reference.dart + :language: dart + :emphasize-lines: 1, 3 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-subscription-by-reference.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst new file mode 100644 index 0000000000..67b4cc2ae1 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-subscription-by-query.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-query.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-single-subscription.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index f81c6312c8..328d8a2536 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -937,7 +937,6 @@ Change an Unnamed Subscription .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst -.. _ios-remove-subscriptions: .. _sdks-remove-subscriptions: Remove Subscriptions @@ -945,64 +944,350 @@ Remove Subscriptions To remove subscriptions, you can: -- Remove a single subscription query -- Remove all subscriptions to a specific object type +- Remove a specific subscription + - Remove a named subscription + - Remove an unnamed subscription + - Remove a subscription by reference + +- Remove all subscriptions for a specific object type - Remove all unnamed subscriptions - Remove all subscriptions -When you remove a subscription query, Realm asynchronously removes the +When you remove a subscription query, the SDK asynchronously removes the synced data that matched the query from the client device. .. _sdks-remove-query-by-name: -.. _sdks-remove-single-subscription: -Remove a Single Subscription +Remove a Named Subscription ```````````````````````````` -You can remove a specific subscription query in a subscription update block -using ``remove``. Specify the query by name or use the query as a string -to find the appropriate subscription query to remove. +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst + +.. _sdks-remove-unnamed-subscription: + +Remove an Unnamed Subscription +`````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst + +.. _sdks-remove-subscription-by-reference: + +Remove a Subscription by Reference +`````````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-single-subscription.swift - :language: swift +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst + +.. _sdks-remove-all-subscriptions-for-object-type: Remove All Subscriptions to an Object Type `````````````````````````````````````````` -If you want to remove all subscriptions to a specific object type, use the -``removeAll`` method with ``ofType`` in a subscription update block. +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-subscriptions-to-object-type.swift - :language: swift + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscription-to-object-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst + +.. _sdks-remove-all-unnamed-subscriptions: Remove All Unnamed Subscriptions ````````````````````````````````` -.. versionadded:: 10.43.0 - You may want to remove unnamed subscriptions that are transient or dynamically generated, but leave named subscriptions in place. -You can remove all unnamed subscriptions from the subscription set by -setting ``unnamedOnly`` to ``true`` when you call the ``removeAll`` method: +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-unnamed-subscriptions.swift - :language: swift + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst + +.. _sdks-remove-all-subscriptions: Remove All Subscriptions ```````````````````````` -To remove all subscriptions from the subscription set, use the ``removeAll`` -method in a subscription update block. - .. important:: If you remove all subscriptions and do not add a new one, you'll - get an error. A realm opened with a flexible sync configuration needs + get an error. A database opened with a flexible sync configuration needs at least one subscription to sync with the server. -.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-subscriptions.swift - :language: swift +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst .. _sdks-sync-subscription-performance-considerations: @@ -1031,15 +1316,3 @@ Flexible Sync RQL Requirements and Limitations ----------------------------------------------- .. include:: /includes/flex-sync-limitations.rst - -Placeholder page for information about managing Flexible Sync subscriptions. - -.. _sdks-add-sync-subscriptions: - -Add Sync Subscriptions ----------------------- - -.. _sdks-remove-sync-subscriptions: - -Remove Sync Subscriptions -------------------------- From 5a6dd369b42d22a333095b0755fc1acd55d158bf Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 09:55:01 -0400 Subject: [PATCH 17/25] Fix snooty build errors --- ...ptions-remove-all-subscriptions-js-ts-description.rst} | 0 source/sdk/sync/manage-sync-subscriptions.txt | 8 ++++---- 2 files changed, 4 insertions(+), 4 deletions(-) rename source/includes/api-details/javascript/sync/{manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst => manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst} (100%) diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst similarity index 100% rename from source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptiond-js-ts-description.rst rename to source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 328d8a2536..ec7787d834 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -1114,7 +1114,7 @@ Remove a Subscription by Reference .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst @@ -1163,12 +1163,12 @@ Remove All Subscriptions to an Object Type .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscription-to-object-type-description.rst + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -1245,7 +1245,7 @@ Remove All Subscriptions .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-not-supported.rst + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst .. tab:: :tabid: csharp From 2109d0f7cdcad2a65ada602b510658cbd90fce5d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 10:07:15 -0400 Subject: [PATCH 18/25] Update remaining page content for Realm/Flexible Sync naming --- source/includes/flex-sync-limitations.rst | 29 ++++++++++--------- source/sdk/sync/manage-sync-subscriptions.txt | 20 +++++++++---- 2 files changed, 29 insertions(+), 20 deletions(-) diff --git a/source/includes/flex-sync-limitations.rst b/source/includes/flex-sync-limitations.rst index b862e019f2..5b6fe08ff1 100644 --- a/source/includes/flex-sync-limitations.rst +++ b/source/includes/flex-sync-limitations.rst @@ -8,7 +8,7 @@ store, or user, such as ``user_id == $0, “641374b03725038381d2e1fb”``, is a good candidate for an indexed queryable field. However, an indexed queryable field has specific requirements for use in a query subscription: -- The indexed queryable field must be used in every subscription query. It +- The indexed queryable field must be used in *every* subscription query. It cannot be missing from the query. - The indexed queryable field must use an ``==`` or ``IN`` comparison against a constant at least once in the subscription query. For example, @@ -20,7 +20,7 @@ queryable field is directly compared against a constant using ``==`` or ``IN`` at least once. For example, ``store_id IN {1,2,3} AND region=="Northeast"`` or ``store_id == 1 AND (active_promotions < 5 OR num_employees < 10)``. -*Invalid* Flexible Sync queries on an indexed queryable field include queries +*Invalid* Device Sync queries on an indexed queryable field include queries where: - The indexed queryable field does not use ``AND`` with the rest of the query. @@ -37,14 +37,14 @@ where: ``region=="Northeast`` or ``truepredicate`` are invalid because they do not contain the indexed queryable field. -Unsupported Query Operators in Flexible Sync -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unsupported Sync Subscription Query Operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Flexible Sync has some limitations when using RQL operators. When you -write the :ref:`query subscription ` -that determines which data to sync, the server does not support these -query operators. However, you can still use the full range of RQL features -to query the synced data set in the client application. +Device Sync does not support all RQL operators when creating your subscription +queries. When you write the :ref:`query subscription ` +that determines which data to sync to the device, the server does not support +these query operators. However, you can use all RQL operators to query the +data set once it has synced to the client application. .. list-table:: :header-rows: 1 @@ -63,12 +63,12 @@ Case insensitive queries (``[c]``) cannot use indexes effectively. As a result, case insensitive queries are not recommended, since they could lead to performance problems. -Flexible Sync only supports ``@count`` for array fields. +Device Sync only supports ``@count`` for array fields. List Queries ~~~~~~~~~~~~ -Flexible Sync supports querying lists using the ``IN`` operator. +Device Sync supports querying lists using the ``IN`` operator. You can query a list of constants to see if it contains the value of a queryable field: @@ -88,8 +88,9 @@ contains a constant value: .. warning:: - You **cannot** compare two lists with each other in a Flexible Sync query. - Note that this is valid Realm Query Language syntax outside of Flexible Sync queries. + You **cannot** compare two lists with each other in a Device Sync query. + Note that this is valid Realm Query Language syntax outside of Device Sync + queries. .. code-block:: javascript :copyable: false @@ -103,5 +104,5 @@ contains a constant value: Embedded or Linked Objects ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Flexible Sync does not support querying on properties in Embedded Objects +Device Sync does not support querying on properties in Embedded Objects or links. For example, ``obj1.field == "foo"``. diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index ec7787d834..07a31979f2 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -34,6 +34,8 @@ You can manually add, update, and remove subscriptions to determine which data syncs to the client device. Or you can subscribe to queries instead of or in addition to manually managing subscriptions. +.. _sdks-query-subscription-concept: + What are Subscriptions? ----------------------- @@ -55,14 +57,20 @@ The SDK tracks these queries through a **subscription set**, which is a collection of subscriptions. You can add, remove, and update subscriptions in the subscription set. -You can construct subscription queries with RQL, or one of the SDK-idiomatic -query engines. +You can construct subscription queries with Realm Query Language (RQL), or one +of the SDK-idiomatic query engines. - :ref:`realm-query-language` - :ref:`java-filter-data` - :ref:`dotnet-linq` - :ref:`sdks-filter-data-swift` +.. important:: RQL Support in Sync Subscription Queries + + Device Sync does not support the full range of RQL operators when constructing + a subscription query. For details about these limitations, refer to + :ref:`sdks-sync-subscription-query-rql-limitations`. + Subscribe to Object Types ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1300,7 +1308,7 @@ API Efficiency Adding several subscriptions with the ``.subscribe()`` and ``.unsubscribe()`` APIs described in the :ref:`sdks-sync-results-subscribe-api` section is less efficient than performing batch updates when you manually -manage subscriptions. On every ``.subscribe()``, the Swift SDK opens a new +manage subscriptions. On every call to ``.subscribe()``, the SDK opens a new update block. For better performance adding multiple subscriptions, use the ``subscriptions.update`` API described in the :ref:`sdks-manually-manage-subscriptions` section. @@ -1310,9 +1318,9 @@ Group Updates for Improved Performance .. include:: /includes/sync-memory-performance.rst -.. _swift-flexible-sync-rql-limitations: +.. _sdks-sync-subscription-query-rql-limitations: -Flexible Sync RQL Requirements and Limitations ------------------------------------------------ +Sync RQL Requirements and Limitations +------------------------------------- .. include:: /includes/flex-sync-limitations.rst From a70b96de4c9a0143f17a2e199f11f6bcad36f7e9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 10:13:59 -0400 Subject: [PATCH 19/25] Updates per author checklist --- ...-sync-subscriptions-subscribe-to-query-description.rst | 2 +- source/sdk/sync/manage-sync-subscriptions.txt | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst index 75aabe9891..143644eb5f 100644 --- a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -1,5 +1,5 @@ To subscribe to a ``RealmQuery`` or ``RealmResults`` set, call the -:kotlin-sdk:`.subscribe() ` method. +:kotlin-sync-sdk:`.subscribe() ` method. .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt :language: kotlin diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 07a31979f2..d0f714191b 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -5,7 +5,7 @@ Manage Sync Subscriptions ========================= .. meta:: - :description: Provide a short description of the consolidated page. This is critical for SEO. + :description: Create, update, and delete query subscriptions to sync data between client devices and Atlas Device Sync. :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: @@ -116,6 +116,8 @@ This page details how to manage client subscriptions for Device Sync. For information about setting up permissions for Device Sync, see: :ref:`Device Sync Rules & Permissions `. +.. _sdks-manage-subscriptions-in-client: + Manage Subscriptions in Your Client App --------------------------------------- @@ -745,8 +747,8 @@ may appear to the user as unexpected changes to the data set later during .. _sdks-subscription-set-state: -Subscription Set State -~~~~~~~~~~~~~~~~~~~~~~ +Check Subscription Set State +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can check the state of the subscription set through to find out the current status of the subscription set. This provides information about whether From e9007a836b6998bd38b31856ba43fe45dc25d637 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 11:49:31 -0400 Subject: [PATCH 20/25] Add info about accessing and finding subscriptions --- ...ns-access-subscription-set-description.rst | 7 + ...riptions-find-subscription-description.rst | 4 + ...ns-access-subscription-set-description.rst | 5 + ...riptions-find-subscription-description.rst | 8 ++ ...ns-access-subscription-set-description.rst | 5 + ...riptions-find-subscription-description.rst | 7 + ...ns-access-subscription-set-description.rst | 4 + ...riptions-find-subscription-description.rst | 8 ++ ...-access-subscription-js-ts-description.rst | 4 + ...ns-find-subscription-js-ts-description.rst | 8 ++ ...ns-access-subscription-set-description.rst | 4 + ...riptions-find-subscription-description.rst | 10 ++ ...ns-access-subscription-set-description.rst | 5 + ...riptions-find-subscription-description.rst | 10 ++ ...-subscriptions-access-subscription-set.rst | 63 +++++++++ ...e-sync-subscriptions-find-subscription.rst | 64 +++++++++ source/sdk/sync/manage-sync-subscriptions.txt | 128 ++++++++++++++++++ 17 files changed, 344 insertions(+) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst create mode 100644 source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst create mode 100644 source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a4f70e5e3b --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,7 @@ +You can access the subscription set through the ``subscriptions()`` public +member function of a :cpp-sdk:`realm `. This +provides the :cpp-sdk:`sync_subscription_set +` where you can use the +``size()``, ``find()``, or ``update()`` member functions. You perform all +operations to add, find, update, remove, or watch subscriptions through this +property. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..d066d646b6 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,4 @@ +To find a specific subscription, call the ``subscriptions().find()`` method +with the name of a subscription. + +You cannot find unnamed subscriptions in C++. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a0db7d17f2 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +You can access the :dotnet-sdk:`SubscriptionSet +` through the database +:dotnet-sdk:`Subscriptions ` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..b54f892966 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:dotnet-sdk:`Find() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:dotnet-sdk:`Find() +` +method with an IQueryable argument. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a75798c3c8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +you can access a +:flutter-sdk:`SubscriptionSet `, a +collection of subscriptions, through the ``Realm.subscriptions`` property. +You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..6dc9c05997 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,7 @@ +To find a specific subscription by name, call the +:flutter-sdk:`findByName() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:flutter-sdk:`find() ` method with an +RQL query. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..82b79ba8f6 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,4 @@ +You can access the :java-sdk:`SubscriptionSet ` +through the :java-sdk:`Realm.getSubscriptions() ` +method. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..85746ac7ed --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:java-sdk:`find() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:java-sdk:`find() +` method +with a :java-sdk:`RealmQuery ` argument. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst new file mode 100644 index 0000000000..d08316c6ae --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst @@ -0,0 +1,4 @@ +When using a synced database, you can access a ``SubscriptionSet``, a +collection of subscriptions, through the :js-sdk:`realm.subscriptions +` property. You perform all operations to +add, find, update, remove, or watch subscriptions through this property. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst new file mode 100644 index 0000000000..d14b40e8e3 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:js-sdk:`findByName() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:java-sdk:`findByQuery() +` method with a +query to match against. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..0dc2e2e433 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,4 @@ +You can access a :kotlin-sync-sdk:`SubscriptionSet +` through the +database ``subscriptions`` property. You perform all operations to add, find, +update, remove, or watch subscriptions through this property. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..1d706baa57 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,10 @@ +To find a specific subscription by name, call the +:kotlin-sync-sdk:`findByName() +` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:kotlin-sync-sdk:`findByQuery() +` +method with a :kotlin-sdk:`RealmQuery ` +argument. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..520e9d25fb --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +You can access a :swift-sdk:`SyncSubscriptionSet +` through the database :swift-sdk:`subscriptions +` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..7930335256 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,10 @@ +To find a specific subscription by name, call the +:swift-sdk:`subscriptions.first(named: ) +` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling one of +the variants of :kotlin-sync-sdk:`subscriptions.first(ofType: where:) +` +method with the SDK object type and a query, query builder, or NSPredicate +argument. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst new file mode 100644 index 0000000000..6d0b7298f7 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.get-subscriptions.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.get-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst new file mode 100644 index 0000000000..8533d5a8c2 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscription-count-and-find-subscription.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index d0f714191b..4bb973981f 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -142,6 +142,14 @@ You can: Subscriptions persist across user sessions unless you unsubscribe from them. +Initial Subscriptions +~~~~~~~~~~~~~~~~~~~~~ + +Before you can read from or write to a synced database, you must provide at +least one subscription. Some of the SDK languages provide a dedicated API +to make it more convenient to set initial subscriptions. For details, refer +to :ref:`sdks-set-initial-subscriptions`. + .. _sdks-sync-results-subscribe-api: Subscribe to Queries @@ -445,6 +453,126 @@ When you create a subscription, the SDK looks for data matching a query on a specific object type. You can have multiple subscription sets on different object types. You can also have multiple queries on the same object type. +.. _sdks-get-sync-subscriptions: + +Access the Subscription Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can access the subscription set through the database ``subscriptions`` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst + +.. _sdks-find-sync-subscriptions: + +Find a Subscription +~~~~~~~~~~~~~~~~~~~ + +You can find a specific subscription in a subscription set. You might want to +find a specific subscription: + +- To avoid adding the same subscription again, which in some languages throws + an error. +- To update the subscription. +- To remove the subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst + .. _sdks-sync-subscriptions-add-subscription: Add a Subscription From ba66828283ca78be102c46777cfb9fb3042f2f49 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 11:58:49 -0400 Subject: [PATCH 21/25] Add info about refreshing realm for C++ and fix snooty build errors --- .../manage-sync-subscriptions-refresh-realm-description.rst | 6 ++++++ ...criptions-access-subscription-set-js-ts-description.rst} | 0 ...manage-sync-subscriptions-add-multiple-subscriptions.rst | 2 ++ .../manage-sync-subscriptions-add-named-subscription.rst | 2 ++ .../sync/manage-sync-subscriptions-add-subscription.rst | 2 ++ .../manage-sync-subscriptions-add-unnamed-subscription.rst | 2 ++ .../manage-sync-subscriptions-change-named-subscription.rst | 2 ++ ...ubscriptions-remove-all-subscriptions-to-object-type.rst | 2 ++ .../manage-sync-subscriptions-remove-all-subscriptions.rst | 2 ++ .../manage-sync-subscriptions-remove-named-subscription.rst | 2 ++ ...-sync-subscriptions-subscribe-to-all-objects-of-type.rst | 2 ++ source/sdk/sync/manage-sync-subscriptions.txt | 2 +- 12 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst rename source/includes/api-details/javascript/sync/{manage-sync-subscriptions-access-subscription-js-ts-description.rst => manage-sync-subscriptions-access-subscription-set-js-ts-description.rst} (100%) diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst new file mode 100644 index 0000000000..7328eaf1a8 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst @@ -0,0 +1,6 @@ +After you update subscriptions, call ``refresh()`` on the :cpp-sdk:`realm +`. This updates the database and outstanding objects +managed by the database to point to the most recent data. + +.. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.refresh-the-realm.cpp + :language: cpp diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst similarity index 100% rename from source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-js-ts-description.rst rename to source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst index 1868a70916..c44c1ec9f4 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst @@ -8,6 +8,8 @@ :language: cpp :copyable: false + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst index 16b8a5a7c5..2f20db692a 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-objects-matching-a-query.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst index 9e5d1d2ef3..ef46ab9d39 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst index 02a7d487b1..668a7e27e3 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst @@ -8,6 +8,8 @@ :language: cpp :copyable: false + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst index 50b96e269f..60ef5a4379 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.change-subscription-query.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst index ff795f25dc..987b3fcd22 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst index 65d7fa07e7..1dcdfb1c7a 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.clear-all-subscriptions.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst index 91a87b0761..e2dd089e55 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst index 937aa11ef7..fe9763db2e 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst @@ -7,6 +7,8 @@ .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp :language: cpp + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + - id: csharp content: | diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 4bb973981f..97cdc9f316 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -502,7 +502,7 @@ subscriptions through this property. .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-description.rst + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst .. tab:: :tabid: typescript From 646dac9ad621adb51d10f4b54fd67d9e0401f28b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 16 Jul 2024 13:48:00 -0400 Subject: [PATCH 22/25] Fix broken links --- .../manage-sync-subscriptions-find-subscription-description.rst | 2 +- .../manage-sync-subscriptions-find-subscription-description.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst index b54f892966..bfcf602047 100644 --- a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -3,6 +3,6 @@ To find a specific subscription by name, call the method with the name of a subscription. You can also find a subscription matching a specific query by calling the -:dotnet-sdk:`Find() +:dotnet-sdk:`Find() ` method with an IQueryable argument. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst index 6dc9c05997..79cbe7901a 100644 --- a/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -3,5 +3,5 @@ To find a specific subscription by name, call the method with the name of a subscription. You can also find a subscription matching a specific query by calling the -:flutter-sdk:`find() ` method with an +:flutter-sdk:`find() ` method with an RQL query. From 94d00db1e5ec3463b153e35dbeac39fb1b139f7f Mon Sep 17 00:00:00 2001 From: Dachary Date: Thu, 1 Aug 2024 11:12:15 -0400 Subject: [PATCH 23/25] Apply suggestions from review Co-authored-by: Kyle Rollins <115574589+krollins-mdb@users.noreply.github.com> --- ...ons-wait-for-subscription-changes-to-sync-description.rst | 2 +- ...ync-subscriptions-find-subscription-js-ts-description.rst | 2 +- ...anage-sync-subscriptions-add-subscription-description.rst | 2 +- ...s-remove-all-subscriptions-to-object-type-description.rst | 2 +- ...nage-sync-subscriptions-find-subscription-description.rst | 2 +- .../sync/manage-sync-subscriptions-subscribe-to-query.rst | 5 ++--- 6 files changed, 7 insertions(+), 8 deletions(-) diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst index 30ad632f86..fe50bbc2ab 100644 --- a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -1,5 +1,5 @@ Use the :dotnet-sdk:`SubscriptionSet.WaitForSynchronizationAsync() -` +` method to wait for the server to acknowledge this set of subscriptions. If the server rejects the change, the :dotnet-sdk:`SubscriptionSetState ` will be an error state, and diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst index d14b40e8e3..8492b6225e 100644 --- a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst @@ -3,6 +3,6 @@ To find a specific subscription by name, call the method with the name of a subscription. You can also find a subscription matching a specific query by calling the -:java-sdk:`findByQuery() +:js-sdk:`findByQuery() ` method with a query to match against. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst index eeb87c49aa..2a40bef164 100644 --- a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -6,5 +6,5 @@ To add a subscription: #. Call the ``add`` method to append the new subscription to the subscription set. #. Pass a query with the name of the object type. Optionally, use - :ref:`Realm Query Language query ` to query only a subset of the objects. + :ref:`Realm Query Language ` to query only a subset of the objects. You can also add an optional query name. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst index ea1d064208..ceb4bb97ce 100644 --- a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -1,4 +1,4 @@ If you want to remove all subscriptions to a specific object type, pass a class to the :kotlin-sync-sdk:`MutableSubscriptionSet.removeAll() -` +` method. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst index 7930335256..2f2a7f2391 100644 --- a/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -4,7 +4,7 @@ To find a specific subscription by name, call the method with the name of a subscription. You can also find a subscription matching a specific query by calling one of -the variants of :kotlin-sync-sdk:`subscriptions.first(ofType: where:) +the variants of :swift-sdk:`subscriptions.first(ofType: where:) ` method with the SDK object type and a query, query builder, or NSPredicate argument. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst index 6cccdfe02a..8731ea23d9 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -18,9 +18,8 @@ - id: dart content: | - .. literalinclude:: /examples/MissingPlaceholders/example.dart - :language: dart - :copyable: false + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart + :language: dart - id: java content: | From 2d42085fd052e7703f9b34772fd688b905ec5654 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 1 Aug 2024 11:18:05 -0400 Subject: [PATCH 24/25] Fix missed copy-paste and bullet formatting issue --- ...subscriptions-remove-all-subscriptions-to-object-type.rst | 5 ++--- source/sdk/sync/manage-sync-subscriptions.txt | 1 + 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst index 987b3fcd22..5f4807938a 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -4,10 +4,9 @@ - id: cpp content: | - .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp + .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp - - .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + :copyable: false - id: csharp content: | diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 97cdc9f316..cca7dc8fc9 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -1083,6 +1083,7 @@ Remove Subscriptions To remove subscriptions, you can: - Remove a specific subscription + - Remove a named subscription - Remove an unnamed subscription - Remove a subscription by reference From aded9c33f431a6c21ab1c83b9af58dff11a91096 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 1 Aug 2024 11:39:21 -0400 Subject: [PATCH 25/25] Fix cpp-sdk ID in code example include --- .../sync/manage-sync-subscriptions-access-subscription-set.rst | 2 +- .../manage-sync-subscriptions-add-multiple-subscriptions.rst | 2 +- .../sync/manage-sync-subscriptions-add-named-subscription.rst | 2 +- .../sync/manage-sync-subscriptions-add-subscription.rst | 2 +- .../sync/manage-sync-subscriptions-add-unnamed-subscription.rst | 2 +- .../manage-sync-subscriptions-change-named-subscription.rst | 2 +- .../manage-sync-subscriptions-change-unnamed-subscription.rst | 2 +- .../sync/manage-sync-subscriptions-find-subscription.rst | 2 +- ...nc-subscriptions-remove-all-subscriptions-to-object-type.rst | 2 +- .../sync/manage-sync-subscriptions-remove-all-subscriptions.rst | 2 +- ...nage-sync-subscriptions-remove-all-unnamed-subscriptions.rst | 2 +- .../manage-sync-subscriptions-remove-named-subscription.rst | 2 +- ...nage-sync-subscriptions-remove-subscription-by-reference.rst | 2 +- .../manage-sync-subscriptions-remove-unnamed-subscription.rst | 2 +- .../manage-sync-subscriptions-set-initial-subscriptions.rst | 2 +- ...nage-sync-subscriptions-subscribe-to-all-objects-of-type.rst | 2 +- .../manage-sync-subscriptions-subscribe-to-query-with-name.rst | 2 +- .../sync/manage-sync-subscriptions-subscribe-to-query.rst | 2 +- .../sync/manage-sync-subscriptions-unsubscribe-from-query.rst | 2 +- ...-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst | 2 +- ...-subscriptions-wait-for-subscription-changes-to-sync.rst.rst | 2 +- 21 files changed, 21 insertions(+), 21 deletions(-) diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst index 6d0b7298f7..e563809665 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/example.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst index c44c1ec9f4..69964babed 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/example.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst index 2f20db692a..536afacbea 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-objects-matching-a-query.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst index ef46ab9d39..86bac7a5c0 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst index 668a7e27e3..8d8b1c7a50 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/example.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst index 60ef5a4379..814b9cc802 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.change-subscription-query.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst index 16c919f0b3..2659e32773 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst index 8533d5a8c2..2a329445aa 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscription-count-and-find-subscription.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst index 5f4807938a..f32b59e2d9 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst index 1dcdfb1c7a..587776fc1c 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.clear-all-subscriptions.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst index f12e8a5758..a90082d7ec 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst index e2dd089e55..eb836e54d4 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst index c3f3aab125..cefaf4d975 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst index 67b4cc2ae1..6d32a4174c 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst index 35a32bb632..f2e8fc3daa 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst index fe9763db2e..7d351e99ee 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst index 8f537be6f5..c42bbd8aad 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst index 8731ea23d9..b67634726a 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst index 5f964999fe..a82dd6b396 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst index 7035c4c165..2237a88d00 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst index a6c833fe07..a52c990a52 100644 --- a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/MissingPlaceholders/api.cpp