diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index cda0ec56c..e6e7719b8 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 :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``: + +.. 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..93839ce96 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 {+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 ` -- :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 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 `__ -- 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 + } + + } + }