From 2d454322832ff41576ac8106aff823b0d4cd3b0b Mon Sep 17 00:00:00 2001 From: MongoCaleb Date: Mon, 12 Aug 2024 10:12:07 -0700 Subject: [PATCH 1/2] Add description and new code example --- examples/dotnet/Examples/WorkWithRealm.cs | 24 ++++++++ ...rkWithRealm.snippet.field-notifications.cs | 19 +++++++ source/sdk/dotnet/react-to-changes.txt | 56 +++++++++++-------- 3 files changed, 77 insertions(+), 22 deletions(-) create mode 100644 source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs diff --git a/examples/dotnet/Examples/WorkWithRealm.cs b/examples/dotnet/Examples/WorkWithRealm.cs index 3eac893253..788d784b65 100644 --- a/examples/dotnet/Examples/WorkWithRealm.cs +++ b/examples/dotnet/Examples/WorkWithRealm.cs @@ -205,6 +205,30 @@ public void Notifications() }); //:snippet-end: + NotificationCallbackDelegate notificationCallback + = new NotificationCallbackDelegate((sender,changes) => {}); + //:snippet-start:field-notifications + var query = realm.All(); + KeyPathsCollection kpc; + + // Use one of these equivalent declarations to + // specify the fields you want to monitor for changes: + kpc = KeyPathsCollection.Of("Email", "Name"); + kpc = new List {"Email", "Name"}; + + // To get all notifications for top-level properties + // and 4 nested levels of properties, use the `Full` + // static value: + kpc = KeyPathsCollection.Full; + + // To receive notifications for changes to the + // collection only and none of the properties, + // use the `Shallow` static value: + kpc = KeyPathsCollection.Shallow; + + query.SubscribeForNotifications(notificationCallback, kpc); + //:snippet-end: + //:snippet-start:unsub-collection-notifications // Watch for collection notifications. // Call Dispose() when you are done observing the diff --git a/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs new file mode 100644 index 0000000000..db61cd08ab --- /dev/null +++ b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs @@ -0,0 +1,19 @@ +var query = realm.All(); +KeyPathsCollection kpc; + +// Use one of these equivalent declarations to +// specify the fields you want to monitor for changes: +kpc = KeyPathsCollection.Of("Email", "Name"); +kpc = new List {"Email", "Name"}; + +// To get all notifications for top-level properties +// and 4 nested levels of properties, use the `Full` +// static value: +kpc = KeyPathsCollection.Full; + +// To receive notifications for changes to the +// collection only and none of the properties, +// use the `Shallow` static value: +kpc = KeyPathsCollection.Shallow; + +query.SubscribeForNotifications(notificationCallback, kpc); diff --git a/source/sdk/dotnet/react-to-changes.txt b/source/sdk/dotnet/react-to-changes.txt index bacb979025..cb443e7b4a 100644 --- a/source/sdk/dotnet/react-to-changes.txt +++ b/source/sdk/dotnet/react-to-changes.txt @@ -90,9 +90,6 @@ notification handler on the collection or handle the `CollectionChanged `__ event. -Register a Collection Change Listener -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can register a notification handler on a specific collection within a realm. The collection can be of realm objects (like ``realm.All()``) or a collection property on a @@ -107,25 +104,6 @@ Realm emits an initial notification when a subscription is added. After the initial notification, Realm delivers notifications asynchronously whenever a write transaction adds, modifies, or removes objects in the collection. -Specifically, the notification contains a :dotnet-sdk:`ChangeSet ` -with 6 properties: - -- ``DeletedIndices`` is an ``int[]`` that contains the indices of the objects that were - deleted. -- ``InsertedIndices`` is an ``int[]`` that contains the indices of the objects that were - inserted. -- ``ModifiedIndices`` is an ``int[]`` that contains the *old* indices of the objects - that were modified. These indices indicate the position of the modified objects - in the original collection before any deletions or insertions ocurred. -- ``NewModifiedIndices`` is an ``int[]`` that represents the same entries as the - ``ModifiedIndices`` property, but the indices represent the new locations in the - collection after all changes have been accounted for. -- ``IsCleared`` is a boolean set to ``true`` when a collection has been cleared by - calling the ``Clear()`` method. -- ``Moved`` is an array of :dotnet-sdk:`ChangeSet.Move ` - structs that contain the previous and new index of an object moved within the - collection. - To subscribe to collection notifications, call the :dotnet-sdk:`SubscribeForNotifications ` method. ``SubscribeForNotifications`` returns a subscription token which can be @@ -147,6 +125,40 @@ The following code shows how to observe a collection for changes. Handling insertions before deletions may result in unexpected behavior. +Limit Notifications +~~~~~~~~~~~~~~~~~~~ + +The SDK provides also provides a +:dotnet-sdk:`KeyPathsCollection `, which +provides a way to filter the fields that will trigger a notification. You pass +the ``KeyPathsCollection`` to the ``SubscribeForNotifications`` method. +The following code shows how to observe specific fields: + +.. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs + :language: csharp + +Notification ChangeSet +~~~~~~~~~~~~~~~~~~~~~~ + +The notification contains a :dotnet-sdk:`ChangeSet ` +with 6 properties: + +- ``DeletedIndices`` is an ``int[]`` that contains the indices of the objects that were + deleted. +- ``InsertedIndices`` is an ``int[]`` that contains the indices of the objects that were + inserted. +- ``ModifiedIndices`` is an ``int[]`` that contains the *old* indices of the objects + that were modified. These indices indicate the position of the modified objects + in the original collection before any deletions or insertions ocurred. +- ``NewModifiedIndices`` is an ``int[]`` that represents the same entries as the + ``ModifiedIndices`` property, but the indices represent the new locations in the + collection after all changes have been accounted for. +- ``IsCleared`` is a boolean set to ``true`` when a collection has been cleared by + calling the ``Clear()`` method. +- ``Moved`` is an array of :dotnet-sdk:`ChangeSet.Move ` + structs that contain the previous and new index of an object moved within the + collection. + .. _dotnet-unregister-a-change-listener: Unregister a Change Listener From 472380064370f855a4352025f9fa584fba42fb9e Mon Sep 17 00:00:00 2001 From: MongoCaleb Date: Mon, 12 Aug 2024 10:26:01 -0700 Subject: [PATCH 2/2] Update PR template, small fix to netflify action path, reorganize page structure, update code comments --- .github/pull_request_template.md | 8 +++ .github/workflows/netflify-preview-links.yml | 2 +- examples/dotnet/Examples/WorkWithRealm.cs | 3 + ...rkWithRealm.snippet.field-notifications.cs | 3 + source/sdk/dotnet/react-to-changes.txt | 61 ++++++++++--------- 5 files changed, 47 insertions(+), 30 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6cf5082a3b..3519f3ccd9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,14 @@ Add links to every SDK's pages where you got the SDK-specific information: - [PAGE_NAME](https://www.mongodb.com/docs/atlas/device-sdks/LIVE-DOCS-LINK) +### Release Notes + + + ### PR Author Checklist Before requesting a review for your PR, please check these items: diff --git a/.github/workflows/netflify-preview-links.yml b/.github/workflows/netflify-preview-links.yml index 97e8985e79..a37b6b78f3 100644 --- a/.github/workflows/netflify-preview-links.yml +++ b/.github/workflows/netflify-preview-links.yml @@ -23,7 +23,7 @@ jobs: id: build_page_links run: | new_links="" - base_link='https://deploy-preview-${{ github.event.number }}--docs-realm.netlify.app' + base_link='https://deploy-preview-${{ github.event.number }}--device-sdk.netlify.app' changed_files=${{ steps.changed-files.outputs.all_changed_files }} files=$(echo $changed_files | tr "," "\n") for file in $files; do diff --git a/examples/dotnet/Examples/WorkWithRealm.cs b/examples/dotnet/Examples/WorkWithRealm.cs index 788d784b65..ec821ff164 100644 --- a/examples/dotnet/Examples/WorkWithRealm.cs +++ b/examples/dotnet/Examples/WorkWithRealm.cs @@ -213,17 +213,20 @@ NotificationCallbackDelegate notificationCallback // Use one of these equivalent declarations to // specify the fields you want to monitor for changes: + kpc = KeyPathsCollection.Of("Email", "Name"); kpc = new List {"Email", "Name"}; // To get all notifications for top-level properties // and 4 nested levels of properties, use the `Full` // static value: + kpc = KeyPathsCollection.Full; // To receive notifications for changes to the // collection only and none of the properties, // use the `Shallow` static value: + kpc = KeyPathsCollection.Shallow; query.SubscribeForNotifications(notificationCallback, kpc); diff --git a/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs index db61cd08ab..52f43827ab 100644 --- a/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs +++ b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs @@ -3,17 +3,20 @@ // Use one of these equivalent declarations to // specify the fields you want to monitor for changes: + kpc = KeyPathsCollection.Of("Email", "Name"); kpc = new List {"Email", "Name"}; // To get all notifications for top-level properties // and 4 nested levels of properties, use the `Full` // static value: + kpc = KeyPathsCollection.Full; // To receive notifications for changes to the // collection only and none of the properties, // use the `Shallow` static value: + kpc = KeyPathsCollection.Shallow; query.SubscribeForNotifications(notificationCallback, kpc); diff --git a/source/sdk/dotnet/react-to-changes.txt b/source/sdk/dotnet/react-to-changes.txt index cb443e7b4a..a5eeb113d0 100644 --- a/source/sdk/dotnet/react-to-changes.txt +++ b/source/sdk/dotnet/react-to-changes.txt @@ -104,15 +104,27 @@ Realm emits an initial notification when a subscription is added. After the initial notification, Realm delivers notifications asynchronously whenever a write transaction adds, modifies, or removes objects in the collection. -To subscribe to collection notifications, call the -:dotnet-sdk:`SubscribeForNotifications ` -method. ``SubscribeForNotifications`` returns a subscription token which can be -disposed at any time to stop receiving notifications on the collection. +Notification ChangeSets +~~~~~~~~~~~~~~~~~~~~~~~ -The following code shows how to observe a collection for changes. +The notification contains a :dotnet-sdk:`ChangeSet ` +with 6 properties: -.. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.collection-notifications.cs - :language: csharp +- ``DeletedIndices`` is an ``int[]`` that contains the indices of the objects that were + deleted. +- ``InsertedIndices`` is an ``int[]`` that contains the indices of the objects that were + inserted. +- ``ModifiedIndices`` is an ``int[]`` that contains the *old* indices of the objects + that were modified. These indices indicate the position of the modified objects + in the original collection before any deletions or insertions ocurred. +- ``NewModifiedIndices`` is an ``int[]`` that represents the same entries as the + ``ModifiedIndices`` property, but the indices represent the new locations in the + collection after all changes have been accounted for. +- ``IsCleared`` is a boolean set to ``true`` when a collection has been cleared by + calling the ``Clear()`` method. +- ``Moved`` is an array of :dotnet-sdk:`ChangeSet.Move ` + structs that contain the previous and new index of an object moved within the + collection. .. important:: Order Matters @@ -125,6 +137,19 @@ The following code shows how to observe a collection for changes. Handling insertions before deletions may result in unexpected behavior. +Get Notified of All Collection Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To subscribe to collection notifications, call the +:dotnet-sdk:`SubscribeForNotifications ` +method. ``SubscribeForNotifications`` returns a subscription token which can be +disposed at any time to stop receiving notifications on the collection. + +The following code shows how to observe a collection for changes. + +.. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.collection-notifications.cs + :language: csharp + Limit Notifications ~~~~~~~~~~~~~~~~~~~ @@ -137,28 +162,6 @@ The following code shows how to observe specific fields: .. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs :language: csharp -Notification ChangeSet -~~~~~~~~~~~~~~~~~~~~~~ - -The notification contains a :dotnet-sdk:`ChangeSet ` -with 6 properties: - -- ``DeletedIndices`` is an ``int[]`` that contains the indices of the objects that were - deleted. -- ``InsertedIndices`` is an ``int[]`` that contains the indices of the objects that were - inserted. -- ``ModifiedIndices`` is an ``int[]`` that contains the *old* indices of the objects - that were modified. These indices indicate the position of the modified objects - in the original collection before any deletions or insertions ocurred. -- ``NewModifiedIndices`` is an ``int[]`` that represents the same entries as the - ``ModifiedIndices`` property, but the indices represent the new locations in the - collection after all changes have been accounted for. -- ``IsCleared`` is a boolean set to ``true`` when a collection has been cleared by - calling the ``Clear()`` method. -- ``Moved`` is an array of :dotnet-sdk:`ChangeSet.Move ` - structs that contain the previous and new index of an object moved within the - collection. - .. _dotnet-unregister-a-change-listener: Unregister a Change Listener