From 6630be1c83749aae4af90927c99af92315345712 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 28 Apr 2025 15:06:55 -0400 Subject: [PATCH 1/3] DOCSP-35922: csot - gridfs --- .../specify-connection-options/csot.txt | 31 ++++++++++++ source/crud/gridfs.txt | 50 +++++++++++-------- source/includes/connect/CsotExample.java | 18 +++++++ 3 files changed, 78 insertions(+), 21 deletions(-) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index cda0ec56c..4aa8576da 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/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 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)>`__ diff --git a/source/crud/gridfs.txt b/source/crud/gridfs.txt index c1815c29a..c9ea50b91 100644 --- a/source/crud/gridfs.txt +++ b/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 `. +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 ` +reference in the 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 in the driver: -- :ref:`Create a GridFS bucket ` -- :ref:`Store Files ` -- :ref:`Retrieve File Information ` -- :ref:`Download Files ` -- :ref:`Rename Files ` -- :ref:`Delete Files ` -- :ref:`Delete a GridFS 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 a GridFS operation. + 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 `__ -- Runnable example - `GridFSTour.java `__ - from the MongoDB Java Driver repository. - +- Runnable file `GridFSTour.java + `__ + from the driver source repository diff --git a/source/includes/connect/CsotExample.java b/source/includes/connect/CsotExample.java index f8c775fcc..40deca853 100644 --- a/source/includes/connect/CsotExample.java +++ b/source/includes/connect/CsotExample.java @@ -133,4 +133,22 @@ private void cursorTimeout(){ } } + + private void gridFSTimeout(){ + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .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 + } + + } + } From 79db4a9e1b094d03214c4d65701b33df645ae5d2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 28 Apr 2025 15:27:16 -0400 Subject: [PATCH 2/3] cross links --- .../connection/specify-connection-options/csot.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index 4aa8576da..e6e7719b8 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -308,12 +308,12 @@ and prints the ``name`` field value for each document: GridFS ------ -You can set a timeout option for 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. +You can set a timeout option for :ref:`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``: From 6e0ed6ac6d8eca99464eea7003057a24746aa7df Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 29 Apr 2025 10:08:18 -0400 Subject: [PATCH 3/3] JS small fix --- source/crud/gridfs.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/crud/gridfs.txt b/source/crud/gridfs.txt index c9ea50b91..93839ce96 100644 --- a/source/crud/gridfs.txt +++ b/source/crud/gridfs.txt @@ -31,10 +31,10 @@ the file storage in your Java application. 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 ` -reference in the Server manual. +reference in the {+mdb-server+} manual. The following sections describe GridFS operations and demonstrate how to -perform these actions in the driver: +perform these actions with the driver: - :ref:`gridfs-create-bucket` - :ref:`gridfs-store-files` @@ -47,7 +47,7 @@ perform these actions in the driver: .. 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 a GridFS operation. + 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.