DOCSP-39705: Cursors (#72)

Author: mcmorisi

source/includes/read-ops/cursors.java

@@ -0,0 +1,43 @@
+import com.mongodb.ConnectionString;
+import com.mongodb.CursorType;
+import com.mongodb.MongoClientSettings;
+import com.mongodb.client.model.Filters;
+import com.mongodb.reactivestreams.client.*;
+import org.bson.Document;
+import reactor.core.publisher.Flux;
+
+import java.util.List;
+
+public class Cursors {
+    public static void main(String[] args) {
+        String uri = "<connection string URI>";
+
+        MongoClientSettings settings = MongoClientSettings.builder()
+                .applyConnectionString(new ConnectionString(uri))
+                .build();
+
+        try (MongoClient mongoClient = MongoClients.create(settings))
+        {
+            MongoDatabase database = mongoClient.getDatabase("sample_restaurants");
+            MongoCollection<Document> collection = database.getCollection("restaurants");
+
+            // start-cursor-iterate
+            FindPublisher<Document> findPublisher = collection.find();
+            Flux.from(findPublisher)
+                    .doOnNext(x -> System.out.println(x.getString("name")))
+                    .blockLast();
+            // end-cursor-iterate
+
+            // start-cursor-list
+            FindPublisher<Document> findPublisher = collection.find(Filters.eq("name", "Dunkin' Donuts"));
+            List<Document> resultsList = Flux.from(findPublisher).collectList().block();
+            // end-cursor-list
+
+            // start-tailable-cursor
+            FindPublisher<Document> findPublisher = collection.find().cursorType(CursorType.TailableAwait);
+            Flux.from(findPublisher)
+                    .doOnNext(System.out::println)
+                    .blockLast();
+            // end-tailable-cursor
+        }
+    }

source/read-data-from-mongo.txt

@@ -28,6 +28,7 @@ Read Data From MongoDB
     /read/specify-documents-to-return
     /read/count-documents
     /read/distinct
+    /read/cursors
     /read/read-preference
     /read/text-search
     /read/geo

source/read/cursors.txt

@@ -0,0 +1,108 @@
+.. _java-rs-cursors:
+
+=========================
+Access Data From a Cursor
+=========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: read, results, oplog
+
+Overview
+--------
+
+In this guide, you can learn how to access data from a **cursor** by using the
+{+driver-short+}.
+
+A cursor is a mechanism that returns the results of a read operation in iterable
+batches. Because a cursor holds only a subset of documents at any given time,
+cursors reduce both memory consumption and network bandwidth usage.
+
+In the {+driver-short+}, some streams are backed by cursors. The size of batches used
+in these underlying cursors depends on the demand requested on the ``Subscription`` for the
+``Publisher``. The batch size of data contained by each underlying cursor can be set by
+using the ``FindPublisher.batchSize()`` method.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_restaurants.restaurants`` collection
+from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:ref:`<java-rs-getting-started>` guide.
+
+.. include:: includes/reactor-note.rst
+
+.. _java-rs-cursors-iterate:
+
+Access Cursor Contents Iteratively
+----------------------------------
+
+To iterate over the contents of a cursor, use the ``Flux.from()`` method, as shown in the
+following example:
+
+.. literalinclude:: /includes/read-ops/cursors.java
+   :start-after: start-cursor-iterate
+   :end-before: end-cursor-iterate
+   :language: java
+   :dedent:
+   :copyable:
+
+Retrieve All Documents
+----------------------
+
+.. warning::
+
+   If the number and size of documents returned by your query exceeds available
+   application memory, your program will crash. If you expect a large result
+   set, :ref:`access your cursor iteratively <java-rs-cursors-iterate>`.
+
+To retrieve all documents from a cursor, convert the cursor into a ``List``, as
+shown in the following example:
+
+.. literalinclude:: /includes/read-ops/cursors.java
+   :start-after: start-cursor-list
+   :end-before: end-cursor-list
+   :language: java
+   :dedent:
+   :copyable:
+
+Tailable Cursors
+----------------
+
+When querying on a :manual:`capped collection </core/capped-collections/>`, you
+can use a **tailable cursor** that remains open after the client exhausts the
+results in a cursor. To create a tailable cursor on a capped collection,
+pass a value of ``CursorType.TailableAwait`` to the ``cursorType()`` method of a
+``FindPublisher`` object.
+
+The following example creates a tailable cursor on a collection and prints its contents:
+
+.. literalinclude:: /includes/read-ops/cursors.java
+   :start-after: start-tailable-cursor
+   :end-before: end-tailable-cursor
+   :language: java
+   :dedent:
+   :copyable:
+
+To learn more about tailable cursors and their usage, see the :manual:`Tailable Cursors guide
+</core/tailable-cursors/>` in the {+mdb-server+} manual.
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `find() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#find()>`__
+- `FindPublisher <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/FindPublisher.html>`__
+- `CursorType <{+api+}/mongodb-driver-core/com/mongodb/CursorType.html>`__