DOC-7519 -- Pending Doc Ids not documented

modules/ROOT/pages/_partials/commons/common-sgw-replication.adoc

@@ -236,7 +236,7 @@ include::{snippet}[tag=replication-reset-checkpoint,indent=0]
 == Monitoring
 
 In this section::
-<<lbl-repl-chng>>  |  <<lbl-repl-status>>  |  <<lbl-repl-evnts>>
+<<lbl-repl-chng>>  |  <<lbl-repl-status>>  |  <<lbl-repl-evnts>> | <<lbl-repl-pend>>
 
 You can monitor a replication’s status by using a combination of <<lbl-repl-chng>> and the `replication.status.activity` property -- see; {url-api-enum-replicator-activity}.
 This enables you to know, for example, when the replication is actively transferring data and when it has stopped.
@@ -319,6 +319,35 @@ include::{snippet}[tag=remove-document-replication-listener,indent=0]
 When access to a document is removed on Sync Gateway (see: Sync Gateway's xref:sync-gateway::sync-function-api.adoc[Sync Function]), the document replication listener sends a notification with the `AccessRemoved` flag set to `true` and subsequently purges the document from the database.
 --
 
+[#lbl-repl-pend]
+=== Documents Pending Push
+
+TIP: {url-api-method-replicator-isDocumentPending} is quicker and more efficient.
+Use it in preference to returning a list of pending document IDs, where possible.
+
+You can check whether documents are waiting to be pushed in any forthcoming sync by using either of the following API methods:
+
+* Use the {url-api-method-replicator-getPendingDocumentIds} method, which returns a list of document IDs that have local changes, but which have not yet been pushed to the server.
++
+This can be very useful in tracking the progress of a push sync, enabling the app to provide a visual indicator to the end user on its status, or decide when it is safe to exit.
+
+* Use the {url-api-method-replicator-isDocumentPending} method to quickly check whether an individual document is pending a push.
+
+[#ex-pending]
+.Use Pending Document ID API
+====
+
+[source, {source-language}]
+----
+include::{snippet}[tags=replication-pendingdocuments, indent=0]
+
+----
+<.> {url-api-method-replicator-getPendingDocumentIds} returns a list of the document IDs for all documents waiting to be pushed.
+This is a snapshot and may have changed by the time the response is received and processed.
+
+<.> {url-api-method-replicator-isDocumentPending} returns `true` if the document is waiting to be pushed, and `false` otherwise.
+
+====
 
 [#lbl-repl-stop]
 == Stop Sync

modules/android/examples/java-android/app/src/main/java/com/couchbase/code_snippets/Examples.java

@@ -894,10 +894,91 @@ public void testReplicationStatus() throws URISyntaxException {
             if (change.getStatus().getActivityLevel() == Replicator.ActivityLevel.STOPPED) {
                 Log.i(TAG, "Replication stopped");
             }
-        });
-        // end::replication-status[]
+          });
+          // end::replication-status[]
+        }
+
+    //  BEGIN PendingDocuments BM -- 19/Feb/21 --
+    import android.support.annotation.NonNull;
+    import android.util.Log;
+
+    import java.net.URI;
+    import java.net.URISyntaxException;
+    import java.util.Iterator;
+    import java.util.Set;
+
+    import com.couchbase.lite.CouchbaseLiteException;
+    import com.couchbase.lite.Database;
+    import com.couchbase.lite.Endpoint;
+    import com.couchbase.lite.Replicator;
+    import com.couchbase.lite.ReplicatorConfiguration;
+    import com.couchbase.lite.URLEndpoint;
+
+    class PendingDocsExample {
+        private static final String TAG = "SCRATCH";
+
+        private Database database;
+        private Replicator replicator;
+
+        //  BEGIN PendingDocuments IB -- 11/Feb/21 --
+        public void testReplicationPendingDocs() throws URISyntaxException, CouchbaseLiteException {
+            // tag::replication-pendingdocuments[]
+            // ... include other code as required
+            //
+            final Endpoint endpoint =
+              new URLEndpoint(new URI("ws://localhost:4984/db"));
+
+            final ReplicatorConfiguration config =
+              new ReplicatorConfiguration(database, endpoint)
+            .setReplicatorType(ReplicatorConfiguration.ReplicatorType.PUSH);
+            // tag::replication-push-pendingdocumentids[]
+
+            replicator = new Replicator(config);
+            final Set<String> pendingDocs =
+              replicator.getPendingDocumentIds(); // <.>
+
+            // end::replication-push-pendingdocumentids[]
+
+            replicator.addChangeListener(change -> {
+              onStatusChanged(pendingDocs, change.getStatus()); });
+
+            replicator.start();
+
+            // ... include other code as required
+            // end::replication-pendingdocuments[]
+          }
+        //
+        // tag::replication-pendingdocuments[]
+        //
+        private void onStatusChanged(
+          @NonNull final Set<String> pendingDocs,
+          @NonNull final Replicator.Status status) {
+          // ... sample onStatusChanged function
+          //
+          Log.i(TAG,
+            "Replicator activity level is " + status.getActivityLevel().toString());
+
+          // iterate and report-on previously
+          // retrieved pending docids 'list'
+          for (Iterator<String> itr = pendingDocs.iterator(); itr.hasNext(); ) {
+            final String docId = itr.next();
+            try {
+              // tag::replication-push-isdocumentpending[]
+              if (!replicator.isDocumentPending(docId)) { continue; } // <.>
+              // end::replication-push-isdocumentpending[]
+
+              itr.remove();
+              Log.i(TAG, "Doc ID " + docId + " has been pushed");
+            }
+            catch (CouchbaseLiteException e) {
+              Log.w(TAG, "isDocumentPending failed", e); }
+          }
+        }
+        // end::replication-pendingdocuments[]
+        //  END PendingDocuments BM -- 19/Feb/21 --
     }
 
+
     public void testHandlingNetworkErrors() throws URISyntaxException {
         Endpoint endpoint = new URLEndpoint(new URI("ws://localhost:4984/db"));
         ReplicatorConfiguration config = new ReplicatorConfiguration(database, endpoint);

modules/android/pages/_partials/_attributes-module.adoc

@@ -217,7 +217,7 @@
 
 :url-api-method-replicator-getPendingDocumentIds: {url-api-properties-replicator-abs}getPendingDocumentIds--[Replicator.getPendingDocumentIds()]
 
-:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator-abs}isDocumentPending--[Replicator.isDocumentPending()]
+:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator-abs}isDocumentPending-java.lang.String-[Replicator.isDocumentPending()]
 
 :url-api-method-replicator-start: {url-api-properties-replicator-abs}start-boolean-[start()]
 

modules/csharp/examples/code_snippets/Program.cs

@@ -1074,6 +1074,55 @@ private static void SetupReplicatorListener()
             // end::replication-status[]
         }
 
+
+
+
+    //  BEGIN PendingDocuments IB -- 11/Feb/21 --
+    private static void ReplicatorPendingDocuments()
+    {
+        // tag::replication-pendingdocuments[]
+        var url = new Uri("ws://localhost:4984/mydatabase");
+        var target = new URLEndpoint(url);
+        var database = new Database("myDB");
+        var config = new ReplicatorConfiguration(database, target);
+        config.ReplicatorType  = ReplicatorType.Push;
+
+        // tag::replication-push-pendingdocumentids[]
+        var replicator = new Replicator(config);
+
+        var mydocids =
+          new HashSet <string> (replicator.GetPendingDocumentIDs()); // <.>
+
+        // end::replication-push-pendingdocumentids[]
+
+        if (mydocids.Count > 0)
+        {
+            Console.WriteLine($"There are {mydocids.Count} documents pending");
+            replicator.AddChangeListener((sender, change) =>
+            {
+                Console.WriteLine($"Replicator activity level is " +
+                                  change.Status.Activity.ToString());
+                // iterate and report-on previously
+                // retrieved pending docids 'list'
+                foreach (var thisId in mydocids)
+                    // tag::replication-push-isdocumentpending[]
+                    if (!replicator.IsDocumentPending(thisId)) // <.>
+                    {
+                        Console.WriteLine($"Doc ID {thisId} now pushed");
+                    };
+                // end::replication-push-isdocumentpending[]
+            });
+
+            replicator.Start();
+        }
+    // end::replication-pendingdocuments[]
+    }
+
+
+//  END PendingDocuments IB -- 11/Feb/21 --
+
+
+
 		private static void ReplicatorDocumentEvent()
         {
             var replicator = _Replicator;
@@ -1572,4 +1621,3 @@ public Document Resolve(Conflict conflict)
         }
     }
     // end::merge-conflict-resolver[]
-}

modules/csharp/pages/_partials/_attributes-module.adoc

@@ -227,9 +227,9 @@
 
 :url-api-method-replicator-rmv-change-listener: {url-api-properties-replicator}RemoveChangeListener_Couchbase_Lite_ListenerToken_[RemoveChangeListener(ListenerToken)]
 
-:url-api-method-replicator-getPendingDocumentIds: {url-api-properties-replicator}GetPendingDocumentIDs[Replicator.GetPendingDocumentIds()]
+:url-api-method-replicator-getPendingDocumentIds: {url-api-properties-replicator}GetPendingDocumentIDs[Replicator.GetPendingDocumentIDs()]
 
-:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator}IsDocumentPending--[Replicator.IsDocumentPending()]
+:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator}IsDocumentPending_System_String_[Replicator.IsDocumentPending()]
 
 :url-api-method-replicator-start: {url-api-properties-replicator}Start[Start()]
 

modules/java/examples/code_snippets/Examples.java

@@ -1389,6 +1389,89 @@ public void testReplicationStatus() throws URISyntaxException {
         // end::replication-status[]
     }
 
+    //  BEGIN PendingDocuments BM -- 19/Feb/21 --
+    import android.support.annotation.NonNull;
+    import android.util.Log;
+
+    import java.net.URI;
+    import java.net.URISyntaxException;
+    import java.util.Iterator;
+    import java.util.Set;
+
+    import com.couchbase.lite.CouchbaseLiteException;
+    import com.couchbase.lite.Database;
+    import com.couchbase.lite.Endpoint;
+    import com.couchbase.lite.Replicator;
+    import com.couchbase.lite.ReplicatorConfiguration;
+    import com.couchbase.lite.URLEndpoint;
+
+    class PendingDocsExample {
+        private static final String TAG = "SCRATCH";
+
+        private Database database;
+        private Replicator replicator;
+
+        //  BEGIN PendingDocuments IB -- 11/Feb/21 --
+        public void testReplicationPendingDocs() throws URISyntaxException, CouchbaseLiteException {
+            // tag::replication-pendingdocuments[]
+            // ... include other code as required
+            //
+            final Endpoint endpoint =
+              new URLEndpoint(new URI("ws://localhost:4984/db"));
+
+            final ReplicatorConfiguration config =
+              new ReplicatorConfiguration(database, endpoint)
+            .setReplicatorType(ReplicatorConfiguration.ReplicatorType.PUSH);
+            // tag::replication-push-pendingdocumentids[]
+
+            replicator = new Replicator(config);
+            final Set<String> pendingDocs =
+              replicator.getPendingDocumentIds(); // <.>
+
+            // end::replication-push-pendingdocumentids[]
+
+            replicator.addChangeListener(change -> {
+              onStatusChanged(pendingDocs, change.getStatus()); });
+
+            replicator.start();
+
+            // ... include other code as required
+            // end::replication-pendingdocuments[]
+          }
+        //
+        // tag::replication-pendingdocuments[]
+        //
+        private void onStatusChanged(
+          @NonNull final Set<String> pendingDocs,
+          @NonNull final Replicator.Status status) {
+          // ... sample onStatusChanged function
+          //
+          Log.i(TAG,
+            "Replicator activity level is " + status.getActivityLevel().toString());
+
+          // iterate and report-on previously
+          // retrieved pending docids 'list'
+          for (Iterator<String> itr = pendingDocs.iterator(); itr.hasNext(); ) {
+            final String docId = itr.next();
+            try {
+              // tag::replication-push-isdocumentpending[]
+              if (!replicator.isDocumentPending(docId)) { continue; } // <.>
+              // end::replication-push-isdocumentpending[]
+
+              itr.remove();
+              Log.i(TAG, "Doc ID " + docId + " has been pushed");
+            }
+            catch (CouchbaseLiteException e) {
+              Log.w(TAG, "isDocumentPending failed", e); }
+          }
+        }
+        // end::replication-pendingdocuments[]
+        //  END PendingDocuments BM -- 19/Feb/21 --
+    }
+
+
+
+
     public void testHandlingNetworkErrors() throws URISyntaxException {
         Endpoint endpoint = new URLEndpoint(new URI("ws://localhost:4984/db"));
         ReplicatorConfiguration config = new ReplicatorConfiguration(database, endpoint);

modules/java/pages/_partials/_attributes-module.adoc

@@ -213,9 +213,9 @@
 
 :url-api-method-replicator-stop: {url-api-properties-replicator-abs}stop--[stop()]
 
-:url-api-method-replicator-getPendingDocumentIds: {url-api-properties-replicator-abs}getPendingDocumentIds--[Replicator.getPendingDocuments()]
+:url-api-method-replicator-getPendingDocumentIds: {url-api-properties-replicator-abs}getPendingDocumentIds--[Replicator.getPendingDocumentIds()]
 
-:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator-abs}isDocumentPending--[Replicator.isDocumentPending]
+:url-api-method-replicator-isDocumentPending: {url-api-properties-replicator-abs}isDocumentPending-java.lang.String-[Replicator.isDocumentPending]
 
 :url-api-property-replicator-status: {url-api-properties-replicator-abs}getStatus--[replicator.getStatus]
 

modules/objc/examples/code_snippets/SampleCodeTest.m

@@ -836,6 +836,62 @@ - (void) dontTestReplicatorStatus {
     // end::replication-status[]
 }
 
+
+//  BEGIN PendingDocuments IB -- 11/Feb/21 --
+//    public void testReplicationPendingDocs() throws URISyntaxException {
+      // tag::replication-pendingdocuments[]
+
+      CBLDatabase *database = self.db;
+      NSURL *url = [NSURL URLWithString:@"ws://localhost:4984/db"];
+      CBLURLEndpoint *target =
+        [[CBLURLEndpoint alloc] initWithURL: url];
+      CBLReplicatorConfiguration *config =
+        [[CBLReplicatorConfiguration alloc]
+          initWithDatabase:database
+          target:target];
+
+      config.replicatorType = kCBLReplicatorTypePush;
+
+      // tag::replication-push-pendingdocumentids[]
+      CBLReplicator *replicator =
+        [[CBLReplicator alloc] initWithConfig:config];
+
+      // Get list of pending doc IDs
+      NSError* err = nil;
+      NSSet *mydocids =
+        [NSSet setWithSet:[replicator pendingDocumentIDs:&err]]; // <.>
+
+      // end::replication-push-pendingdocumentids[]
+
+      if ([mydocids count] > 0) {
+
+        NSLog(@"There are %lu documents pending", (unsigned long)[mydocids count]);
+
+        [replicator addChangeListener:^(CBLReplicatorChange *change) {
+
+          NSLog(@"Replicator activity level is %u", change.status.activity);
+          // iterate and report-on the pending doc IDs  in 'mydocids'
+          for (thisid in mydocids) {
+
+            // tag::replication-push-isdocumentpending[]
+            NSError* err = nil;
+            if (![replicator isDocumentPending: thisid error: &err]) { // <.>
+              NSLog(@"Doc ID %@ now pushed", thisid);
+            }
+            // end::replication-push-isdocumentpending[]
+          }
+
+        }];
+        [replicator start];
+
+      };
+
+      // end::replication-pendingdocuments[]
+    }
+//  END PendingDocuments IB -- 11/Feb/21 --
+
+
+
 - (void) dontTestReplicatorDocumentEvent {
     CBLDatabase *database = self.db;
     NSURL *url = [NSURL URLWithString:@"ws://localhost:4984/db"];