From 0ceb649fa8c1bcad432701367e1eff600cfa4478 Mon Sep 17 00:00:00 2001 From: cbullinger Date: Tue, 7 May 2024 17:16:08 -0400 Subject: [PATCH] Update progress notification documentation --- .../dart/test/manage_sync_session_test.dart | 23 ++-- ...session_test.snippet.monitor-progress.dart | 15 ++- .../sdk/flutter/sync/manage-sync-session.txt | 58 +++++---- source/sdk/flutter/upgrade-to-v2.txt | 120 +++++++++--------- 4 files changed, 114 insertions(+), 102 deletions(-) diff --git a/examples/dart/test/manage_sync_session_test.dart b/examples/dart/test/manage_sync_session_test.dart index d806c22d9c..1d42d4c739 100644 --- a/examples/dart/test/manage_sync_session_test.dart +++ b/examples/dart/test/manage_sync_session_test.dart @@ -55,8 +55,8 @@ main() { dynamic streamListener; streamListener = syncProgress.listen((syncProgressEvent) { if (called == false) { - expect(syncProgressEvent.transferableBytes > 0, isTrue); - expect(syncProgressEvent.transferredBytes > 0, isTrue); + expect(syncProgressEvent.progressEstimate > 0.0, isTrue); + expect(syncProgressEvent.progressEstimate > 0.0, isTrue); called = true; streamListener.cancel(); } @@ -98,6 +98,7 @@ main() { // :snippet-end: expect(realm.syncSession.state, SessionState.active); }); + test("Monitor sync progress", () async { var isCalled = false; realm.write(() { @@ -113,19 +114,23 @@ main() { late StreamSubscription streamListener; streamListener = stream.listen((syncProgressEvent) { - if (syncProgressEvent.transferableBytes == - syncProgressEvent.transferredBytes) { - isCalled = true; // :remove: - // Upload complete - print('Upload complete'); - // Stop listening to the Stream - streamListener.cancel(); + final progressEstimate = syncProgressEvent.progressEstimate; + + if (progressEstimate < 1.0) { + print('Upload progress: ${progressEstimate * 100}%'); } + }, onDone: () { + print("Upload complete"); + isCalled = true; // :remove: + }, onError: (error) { + print("An error occurred: $error"); + streamListener.cancel(); }); // :snippet-end: await Future.delayed(Duration(seconds: 1)); expect(isCalled, isTrue); }); + test("Monitor network connection", () async { var isConnected = false; // :snippet-start: get-network-connection diff --git a/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart b/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart index 1ac93389f6..392fb58861 100644 --- a/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart +++ b/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart @@ -3,11 +3,14 @@ final stream = realm.syncSession.getProgressStream( late StreamSubscription streamListener; streamListener = stream.listen((syncProgressEvent) { - if (syncProgressEvent.transferableBytes == - syncProgressEvent.transferredBytes) { - // Upload complete - print('Upload complete'); - // Stop listening to the Stream - streamListener.cancel(); + final progressEstimate = syncProgressEvent.progressEstimate; + + if (progressEstimate < 1.0) { + print('Upload progress: ${progressEstimate * 100}%'); } +}, onDone: () { + print("Upload complete"); +}, onError: (error) { + print("An error occurred: $error"); + streamListener.cancel(); }); diff --git a/source/sdk/flutter/sync/manage-sync-session.txt b/source/sdk/flutter/sync/manage-sync-session.txt index 73209d2f92..8377bcc854 100644 --- a/source/sdk/flutter/sync/manage-sync-session.txt +++ b/source/sdk/flutter/sync/manage-sync-session.txt @@ -9,8 +9,7 @@ Manage a Sync Session - Flutter SDK :values: tutorial .. meta:: - :description: Pause and resume sync sessions and monitor sync upload progress - with the Atlas Device SDK for Flutter. + :description: Access the syncSession to check network connection, pause and resume sync sessions, and monitor Sync progress with the Atlas Device SDK for Flutter. .. contents:: On this page :local: @@ -18,13 +17,13 @@ Manage a Sync Session - Flutter SDK :depth: 2 :class: singlecol -When you use Atlas Device Sync, the Realm Flutter SDK syncs data with Atlas +When you use Atlas Device Sync, the Flutter SDK syncs data with Atlas in the background using a sync session. The sync session starts whenever you open a synced realm. The sync session manages the following: -- Uploading and downloading changes to the realm +- Uploading and downloading changes to the synced database - Pausing and resuming sync - Monitoring sync progress - Monitoring network connectivity @@ -54,7 +53,7 @@ to download to your synced realm, call :flutter-sdk:`Session.waitForDownload() .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.wait-upload-download.dart :language: dart -You can add an optional :flutter-sdk:`CancellationToken +You can add an optional :flutter-sdk:`CancellationToken ` to ``waitForUpload()`` and ``waitForDownload()``. @@ -87,36 +86,41 @@ When to Pause a Sync Session .. _flutter-monitor-sync-progress: -Monitor Sync Upload Progress ----------------------------- +Monitor Sync Upload and Download Progress +----------------------------------------- -To monitor Sync upload progress progress, call :flutter-sdk:`SyncSession.getProgressStream() +.. versionchanged:: 2.0.0 + ``transferredBytes`` and ``transferrableBytes`` deprecated in favor of ``progressEstimate`` + +To monitor Sync progress, call :flutter-sdk:`SyncSession.getProgressStream() `. This method returns a Stream of -:flutter-sdk:`SyncProgress ` objects. -``SyncProgress`` provides the total number of transferrable bytes and the remaining -bytes to be transferred. +:flutter-sdk:`SyncProgress ` objects that provide +a ``progressEstimate`` for the current upload or download. + +The provided ``progressEstimate`` is a double whose value +ranges from ``0.0`` to ``1.0``. At ``1.0``, the progress stream is complete. ``SyncSession.getProgressStream()`` takes two arguments: - A :flutter-sdk:`ProgressDirection ` - enum that must be set to ``upload``. - This specifies that the progress stream tracks uploads. + enum that can be set to ``upload`` or ``download``. Specifies whether the + progress stream monitors upload or download progress. - A :flutter-sdk:`ProgressMode ` enum - that can be set to ``reportIndefinitely`` or ``forCurrentlyOutstandingWork``. - ``reportIndefinitely`` sets notifications to continue until the callback is unregistered. - ``forCurrentlyOutstandingWork`` sets notifications to continue until only - the currently-transferable bytes are synced. + that can be set to one of the following: + + - ``reportIndefinitely``: Sets notifications to continue until the callback is + unregistered. + - ``forCurrentlyOutstandingWork``: Sets notifications to continue until the + ``progressEstimate`` reaches ``1.0``. .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart :language: dart -.. warning:: Do Not Track Downloads +.. tip:: - The ``ProgressDirection`` enum also has a ``download`` option to track down downloads. - The ``download`` case provides planned future support for download progress notifications. - However, these notifications do not currently provide an accurate indicator of download progress. - Do not rely on ``ProgressDirection.download`` for download progress notifications. + Use the ``progressEstimate`` to display a progress indicator or estimated + data transfer percentage. .. _flutter-monitor-network-connection: @@ -146,7 +150,7 @@ Manually Reconnect All Sync Sessions The Flutter SDK automatically detects when a device regains connectivity after being offline and attempts to reconnect using an incremental backoff strategy. -You can choose to manually trigger a reconnect attempt with the +You can choose to manually trigger a reconnect attempt with the :flutter-sdk:`App.reconnect() ` instead of waiting for the duration of the incremental backoff. This is useful if you have a more accurate understanding of the network conditions and don't want to rely on @@ -155,12 +159,12 @@ automatic reconnect detection. .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.session-reconnect.dart :language: dart -When you call this method, the SDK forces all sync sessions to attempt to +When you call this method, the SDK forces all sync sessions to attempt to reconnect immediately and resets any timers used for incremental backoff. .. important:: Cannot Reconnect Within Socket Read Timeout Duration - + The Flutter SDK has an internal default socket read timeout of 2 minutes, - where the SDK will time out if a read operation does not receive any data - within a 2-minute window. If you call ``App.Sync.reconnect()`` + where the SDK will time out if a read operation does not receive any data + within a 2-minute window. If you call ``App.Sync.reconnect()`` within that window, the Flutter SDK does *not* attempt to reconnect. diff --git a/source/sdk/flutter/upgrade-to-v2.txt b/source/sdk/flutter/upgrade-to-v2.txt index f09227aed7..1a3da6b8dc 100644 --- a/source/sdk/flutter/upgrade-to-v2.txt +++ b/source/sdk/flutter/upgrade-to-v2.txt @@ -19,17 +19,17 @@ Upgrade to Flutter SDK v2.0.0 :class: singlecol Atlas Device SDK for Flutter version 2.0.0 introduces several breaking changes -that impact existing apps upgrading from an earlier version. +that impact existing apps upgrading from an earlier version. -Notably, this version of the SDK: +Notably, this version of the SDK: -- Changes the part builder and how the SDK generates files for - your data model classes. This change impacts all apps upgrading from an - earlier version of the SDK. Refer to the :ref:`flutter-v2-builder-breaking-changes` +- Changes the part builder and how the SDK generates files for + your data model classes. This change impacts all apps upgrading from an + earlier version of the SDK. Refer to the :ref:`flutter-v2-builder-breaking-changes` section on this page for information and instructions. -- Removes or replaces several classes and members. These changes may or may not impact your - app. Refer to the :ref:`flutter-v2-removed-classes` section +- Removes or replaces several classes and members. These changes may or may not impact your + app. Refer to the :ref:`flutter-v2-removed-classes` section on this page for information and instructions for impacted apps. .. _flutter-v2-builder-breaking-changes: @@ -41,9 +41,9 @@ Builder Changes This change impacts all apps upgrading from an earlier version of the SDK. -Flutter SDK version 2.0.0 updates the SDK's ``realm_generator`` to use a -``PartBuilder`` instead of a ``SharedPartBuilder``. -This updated builder generates ``RealmModel`` data model files with a new +Flutter SDK version 2.0.0 updates the SDK's ``realm_generator`` to use a +``PartBuilder`` instead of a ``SharedPartBuilder``. +This updated builder generates ``RealmModel`` data model files with a new ``.realm.dart`` file extension: .. list-table:: @@ -53,22 +53,22 @@ This updated builder generates ``RealmModel`` data model files with a new * - Version - File Extension - Example Part Directive - - * - SDK v2.0.0 and later + + * - SDK v2.0.0 and later - ``.realm.dart`` - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-new.dart :language: dart - * - SDK v1.9.0 and earlier - - ``.g.dart`` + * - SDK v1.9.0 and earlier + - ``.g.dart`` - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-old.dart :language: dart -.. tip:: +.. tip:: - The update from ``SharedPartBuilder`` to ``PartBuilder`` makes it easier - to use multiple builders in your app. For example, combining ``realm_dart`` - with a serialization package builder such as ``dart_mappable`` or + The update from ``SharedPartBuilder`` to ``PartBuilder`` makes it easier + to use multiple builders in your app. For example, combining ``realm_dart`` + with a serialization package builder such as ``dart_mappable`` or ``json_serializable``. .. _flutter-v2-what-do-i-need-to-do: @@ -76,29 +76,29 @@ This updated builder generates ``RealmModel`` data model files with a new What Do I Need to Do? ~~~~~~~~~~~~~~~~~~~~~ -When you upgrade an existing app from an earlier version of the Flutter SDK to -version 2.0.0 or later, you *must* update any existing part declarations, then -regenerate the object models with the new ``.realm.dart`` file extension: +When you upgrade an existing app from an earlier version of the Flutter SDK to +version 2.0.0 or later, you *must* update any existing part declarations, then +regenerate the object models with the new ``.realm.dart`` file extension: .. procedure:: .. step:: Update Your Existing Part Declarations - Update all of the ``RealmObject`` part declarations in your app to + Update all of the ``RealmObject`` part declarations in your app to use the new naming convention: .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart :language: dart :emphasize-lines: 3-5 - + .. step:: Regenerate Your Object Models .. tabs:: .. tab:: Flutter - :tabid: flutter + :tabid: flutter - After you update all of your declarations, regenerate your + After you update all of your declarations, regenerate your object models with the new ``.realm.dart`` file extension. You can safely delete any ``.g.dart`` files from your project. @@ -107,9 +107,9 @@ regenerate the object models with the new ``.realm.dart`` file extension: dart run realm generate .. tab:: Dart Standalone - :tabid: dart + :tabid: dart - After you update all of your declarations, regenerate your + After you update all of your declarations, regenerate your object models with the new ``.realm.dart`` file extension. You can safely delete any ``.g.dart`` files from your project. @@ -122,10 +122,10 @@ regenerate the object models with the new ``.realm.dart`` file extension: Removed Classes and Members --------------------------- -Flutter SDK version 2.0.0 also removed or replaced several classes, members, and properties +Flutter SDK version 2.0.0 also removed or replaced several classes, members, and properties from the SDK. These changes may or may not impact your app. -The following table outlines what was removed and why, as well as a recommended solution +The following table outlines what was removed and why, as well as a recommended solution when upgrading an app that used the removed class or member, if any: .. list-table:: @@ -135,70 +135,70 @@ when upgrading an app that used the removed class or member, if any: * - Removed Class or Member - Reason - Solution - + * - ``AppConfiguration.localAppName`` and ``AppConfiguration.localAppVersion`` - Unused in SDK. - - Remove any instances. + - Remove any instances. - * - ``ClientResetError.isFatal`` + * - ``ClientResetError.isFatal`` - Not needed. Always ``true``. - - Remove any instances. + - Remove any instances. - * - ``ClientResetError.sessionErrorCode`` - - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. - - Use ``SyncErrorCode`` enum. See also the + * - ``ClientResetError.sessionErrorCode`` + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. See also the :flutter-sdk:`SyncError ` API reference. - * - ``Realm.logger.level`` + * - ``Realm.logger.level`` - Replaced by ``Realm.logger.setLogLevel``. - - Replace any instances. See also :ref:`flutter-logging`. + - Replace any instances. See also :ref:`flutter-logging`. - * - ``RealmProperty.indexed`` + * - ``RealmProperty.indexed`` - Replaced by ``RealmProperty.indexType``. - - Replace any instances. + - Replace any instances. - * - ``RealmValue.type`` + * - ``RealmValue.type`` - Changed to an enum of ``RealmValueType``. - Replace any instances. See also :ref:`RealmValue Data Type `. - * - ``RealmValue.uint8List`` - - Renamed to ``RealmValue.binary``. + * - ``RealmValue.uint8List`` + - Renamed to ``RealmValue.binary``. - Replace any instances. See also :ref:`RealmValue Data Type `. - * - ``SchemaObject.properties`` + * - ``SchemaObject.properties`` - ``SchemaObject`` changed to an iterable collection of ``SchemaProperty``. - - Replace any instances. See also the + - Replace any instances. See also the :flutter-sdk:`SchemaObject ` API reference. * - ``SyncError`` constructor and ``SyncError.create`` factory - Sync errors should only be created internally by the SDK. - - Remove any instances. + - Remove any instances. - * - ``SyncClientError``, ``SyncConnectionError``, ``SyncSessionError``, + * - ``SyncClientError``, ``SyncConnectionError``, ``SyncSessionError``, ``SyncResolveError``, ``SyncWebSocketError``, and ``GeneralSyncError`` - - Consolidated into ``SyncError`` in SDK v1.6.0. - - Use ``SyncError`` or its subclasses. See also the + - Consolidated into ``SyncError`` in SDK v1.6.0. + - Use ``SyncError`` or its subclasses. See also the :flutter-sdk:`SyncError ` API reference. - * - ``SyncErrorCategory``, ``SyncClientErrorCode``, ``SyncConnectionErrorCode``, - ``SyncSessionErrorCode``, ``SyncResolveErrorCode``,``SyncWebsocketErrorCode``, + * - ``SyncErrorCategory``, ``SyncClientErrorCode``, ``SyncConnectionErrorCode``, + ``SyncSessionErrorCode``, ``SyncResolveErrorCode``,``SyncWebsocketErrorCode``, and ``GeneralSyncErrorCode`` - - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. - - Use ``SyncErrorCode`` enum. See also the + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. See also the :flutter-sdk:`SyncError ` API reference. * - ``SyncError.codeValue``, ``SyncError.category``, and ``SyncError.detailedMessage`` - - Consolidated into ``SyncError`` in SDK v1.6.0. Messages were unused. + - Consolidated into ``SyncError`` in SDK v1.6.0. Messages were unused. - Remove any category or message instances. Replace ``SyncError.codeValue`` - with ``SyncError.code.code``. See also the + with ``SyncError.code.code``. See also the :flutter-sdk:`SyncError ` API reference. * - ``SyncProgress.transferredBytes`` and ``SyncProgress.transferableBytes`` - Reported transferred and transferable values were incorrect. Consolidated into a new ``SyncProgress.progressEstimate`` metric. - - Use ``SyncProgress.progressEstimate``. + - Use ``SyncProgress.progressEstimate``. See also :ref:`flutter-monitor-sync-progress`. - * - ``User.provider`` - - Provider is associated with each identity, so value was incorrect - for users with more than one identity. - - Remove any instances. + * - ``User.provider`` + - Provider is associated with each identity, so value was incorrect + for users with more than one identity. + - Remove any instances.