DOCSP-22185 BACKPORT v5.0 (#1113)

* DOCSP-22185 BACKPORT

* Staging fixes

* Staging fixes

Author: Dave

source/includes/fact-multiple-cursor-monitors.rst

@@ -0,0 +1,28 @@
+MongoDB provides multiple ways to iterate on a cursor. 
+
+The :method:`cursor.hasNext()` method blocks and waits for the next
+event. To monitor the ``watchCursor`` cursor and iterate over the
+events, use ``hasNext()`` like this:
+
+.. code-block:: javascript
+
+   while (!watchCursor.isClosed()) {
+      if (watchCursor.hasNext()) {
+        firstChange = watchCursor.next();
+        break;
+      }
+   }
+
+The :method:`cursor.tryNext()` method is non-blocking. To monitor
+the ``watchCursor`` cursor and iterate over the events, use
+``tryNext()`` like this:
+
+.. code-block:: javascript
+
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
+   }

source/reference/method/Mongo.watch.txt

@@ -251,6 +251,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Example
 -------
 
@@ -264,16 +269,18 @@ except for the ``admin``, ``local``, and the ``config`` databases.
    watchCursor = db.getMongo().watch()
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see

source/reference/method/cursor.tryNext.txt

@@ -0,0 +1,29 @@
+=============
+cursor.next()
+=============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. method:: cursor.tryNext()
+
+
+   .. include:: /includes/fact-mongosh-shell-method.rst
+
+
+   :returns: The next document in the cursor returned by the
+             :method:`db.collection.find()` method or ``null``.
+             
+
+Behavior
+--------
+
+``cursor.tryNext()`` is a special case of the :method:`cursor.next()`
+method that returns the next element in the iteration if available or
+else ``null``.
+

source/reference/method/db.collection.watch.txt

@@ -246,6 +246,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Examples
 --------
 
@@ -260,16 +265,18 @@ The following operation opens a change stream cursor against the
    watchCursor = db.getSiblingDB("data").sensors.watch()
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see
@@ -294,16 +301,18 @@ the ``data.sensors`` collection using the
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For any update operation, the change event returns the result of the
@@ -335,13 +344,13 @@ filter only ``insert`` events:
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.hasNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
+   while (!watchCursor.isClosed()){
       if (watchCursor.hasNext()){
          printjson(watchCursor.next());
       }
@@ -370,7 +379,7 @@ rolled off the cluster's oplog.
    let watchCursor = db.getSiblingDB("data").sensors.watch();
    let firstChange;
 
-   while (!watchCursor.isExhausted()) {
+   while (!watchCursor.isClosed()) {
       if (watchCursor.hasNext()) {
         firstChange = watchCursor.next();
         break;
@@ -387,13 +396,14 @@ rolled off the cluster's oplog.
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.hasNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
+
 
 .. code-block:: javascript
 
-   while (!resumedWatchCursor.isExhausted()){
+   while (!resumedWatchCursor.isClosed()){
       if (resumedWatchCursor.hasNext()){
          printjson(watchCursor.next());
       }

source/reference/method/db.watch.txt

@@ -250,6 +250,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Example
 -------
 
@@ -262,17 +267,20 @@ database.
 
    watchCursor = db.getSiblingDB("hr").watch()
 
+
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see

source/reference/method/js-cursor.txt

@@ -157,9 +157,12 @@ These methods modify the way that the underlying query is executed.
      - Marks the cursor as tailable. Only valid for cursors over capped collections.
 
    * - :method:`cursor.toArray()`
+     - Returns an array that contains all documents returned by the
+       cursor.
 
-     - Returns an array that contains all documents returned by the cursor.
-
+   * - :method:`cursor.tryNext()`
+     - Returns the next element in the iteration if available or else
+       null.
 
 .. toctree::
    :titlesonly: 
@@ -198,3 +201,4 @@ These methods modify the way that the underlying query is executed.
    /reference/method/cursor.sort
    /reference/method/cursor.tailable
    /reference/method/cursor.toArray
+   /reference/method/cursor.tryNext