DOCSP-35922: csot - gridfs (#683)

* DOCSP-35922: csot - gridfs

* cross links

* JS small fix

(cherry picked from commit 5c9b19a)

Author: rustagir

source/connection/specify-connection-options/csot.txt

@@ -303,6 +303,36 @@ and prints the ``name`` field value for each document:
    :dedent:
    :emphasize-lines: 3
 
+.. _java-csot-gridfs:
+
+GridFS
+------
+
+You can set a timeout option for :ref:`GridFS <java-crud-gridfs>`
+operations when instantiating a ``GridFSBucket`` by using the
+``withTimeout()`` method. This timeout applies to all operations
+performed on the bucket, such as uploading and downloading data. If you
+do not set a timeout, the ``GridFSBucket`` instance inherits the timeout
+setting from the ``MongoDatabase`` it is created with.
+
+The following code demonstrates how to set a timeout when instantiating
+a ``GridFSBucket``:
+
+.. literalinclude:: /includes/connect/CsotExample.java
+   :language: java
+   :start-after: start-gridfsbucket-timeout
+   :end-before: end-gridfsbucket-timeout
+   :dedent:
+   :emphasize-lines: 3
+
+.. important:: InputStream Timeout Support
+
+   When you call the ``uploadFromStream()`` method on a ``GridFSBucket``
+   that has an operation timeout, timeout breaches might occur because
+   the ``InputStream`` class lacks inherent read timeout support. This might
+   extend the operation beyond the specified timeout limit, causing a
+   timeout exception.
+
 API Documentation
 -----------------
 
@@ -317,3 +347,4 @@ API documentation:
 - `ClientEncryptionSettings.Builder.timeout() <{+core-api+}/ClientEncryptionSettings.Builder.html#timeout(long,java.util.concurrent.TimeUnit)>`__
 - `FindIterable.timeoutMode() <{+driver-api+}/FindIterable.html#timeoutMode(com.mongodb.client.cursor.TimeoutMode)>`__
 - `TimeoutMode <{+core-api+}/client/cursor/TimeoutMode.html>`__
+- `GridFSBucket.withTimeout() <{+driver-api+}/gridfs/GridFSBucket.html#withTimeout(long,java.util.concurrent.TimeUnit)>`__

source/crud/gridfs.txt

@@ -22,26 +22,35 @@ Overview
 --------
 
 In this guide, you can learn how to store and retrieve large files in
-MongoDB using **GridFS**. GridFS is a specification implemented by the
-driver that describes how to split files into chunks when storing them
+MongoDB by using **GridFS**. GridFS is a specification implemented by the
+{+driver-short+} that describes how to split files into chunks when storing them
 and reassemble them when retrieving them. The driver implementation of
 GridFS is an abstraction that manages the operations and organization of
-the file storage. 
+the file storage in your Java application.
 
-You should use GridFS if the size of your files exceed the BSON document
-size limit of 16MB. For more detailed information on whether GridFS is
-suitable for your use case, see the :manual:`GridFS server manual page </core/gridfs>`.
+Use GridFS if the size of your files exceed the BSON document
+size limit of 16MB. To learn more about whether GridFS is
+suitable for your use case, see the :manual:`GridFS </core/gridfs>`
+reference in the {+mdb-server+} manual.
 
-See the following sections that describe GridFS operations and how to
-perform them:
+The following sections describe GridFS operations and demonstrate how to
+perform these actions with the driver:
 
-- :ref:`Create a GridFS bucket <gridfs-create-bucket>`
-- :ref:`Store Files <gridfs-store-files>`
-- :ref:`Retrieve File Information <gridfs-retrieve-file-info>`
-- :ref:`Download Files <gridfs-download-files>`
-- :ref:`Rename Files <gridfs-rename-files>`
-- :ref:`Delete Files <gridfs-delete-files>`
-- :ref:`Delete a GridFS bucket <gridfs-delete-bucket>`
+- :ref:`gridfs-create-bucket`
+- :ref:`gridfs-store-files`
+- :ref:`gridfs-retrieve-file-info`
+- :ref:`gridfs-download-files`
+- :ref:`gridfs-rename-files`
+- :ref:`gridfs-delete-files`
+- :ref:`gridfs-delete-bucket`
+
+.. tip:: Timeout Setting
+
+   You can use the client-side operation timeout (CSOT) setting to limit
+   the amount of time in which the server can finish GridFS operations.
+   To learn more about using this setting with GridFS, see the
+   :ref:`java-csot-gridfs` section of the Limit Server Execution Time
+   guide.
 
 How GridFS Works
 ----------------
@@ -419,11 +428,10 @@ For more information about this method, see the
 `drop() <{+driver-api+}/gridfs/GridFSBucket.html#drop()>`__
 API Documentation.
 
-Additional Resources
---------------------
+Additional Information
+----------------------
 
 - `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`__
-- Runnable example
-  `GridFSTour.java <https://github.com/mongodb/mongo-java-driver/blob/master/driver-sync/src/examples/gridfs/GridFSTour.java>`__
-  from the MongoDB Java Driver repository.
-
+- Runnable file `GridFSTour.java
+  <https://github.com/mongodb/mongo-java-driver/blob/master/driver-sync/src/examples/gridfs/GridFSTour.java>`__
+  from the driver source repository

source/includes/connect/CsotExample.java

@@ -133,4 +133,22 @@ private void cursorTimeout(){
         }
 
     }
+
+    private void gridFSTimeout(){
+        MongoClientSettings settings = MongoClientSettings.builder()
+                .applyConnectionString(new ConnectionString("<connection string>"))
+                .build();
+
+        try (MongoClient mongoClient = MongoClients.create(settings)) {
+            MongoDatabase database = mongoClient.getDatabase("db");
+
+            // start-gridfsbucket-timeout
+            GridFSBucket gridFSBucket = GridFSBuckets
+                    .create(database)
+                    .withTimeout(200L, MILLISECONDS);
+            // end-gridfsbucket-timeout
+        }
+
+    }
+
 }