Package com.mongodb.client.gridfs

Interface GridFSBucket

@ThreadSafe public interface GridFSBucket
Represents a GridFS Bucket
Since:
3.1

  • Method Details

    • getBucketName

      String getBucketName()
      The bucket name.
      Returns:
      the bucket name

    • getChunkSizeBytes

      int getChunkSizeBytes()
      Sets the chunk size in bytes. Defaults to 255.
      Returns:
      the chunk size in bytes.

    • getWriteConcern

      WriteConcern getWriteConcern()
      Get the write concern for the GridFSBucket.
      Returns:
      the WriteConcern

    • getReadPreference

      ReadPreference getReadPreference()
      Get the read preference for the GridFSBucket.
      Returns:
      the ReadPreference

    • getReadConcern

      ReadConcern getReadConcern()
      Get the read concern for the GridFSBucket.
      Returns:
      the ReadConcern
      Since:
      3.2
      MongoDB documentation
      Read Concern
      Since server release
      3.2

    • getTimeout

      @Alpha(CLIENT) @Nullable Long getTimeout(TimeUnit timeUnit)
      The time limit for the full execution of an operation.

      If not null the following deprecated options will be ignored: waitQueueTimeoutMS, socketTimeoutMS, wTimeoutMS, maxTimeMS and maxCommitTimeMS

      • null means that the timeout mechanism for operations will defer to using:
        • waitQueueTimeoutMS: The maximum wait time in milliseconds that a thread may wait for a connection to become available
        • socketTimeoutMS: How long a send or receive on a socket can take before timing out.
        • wTimeoutMS: How long the server will wait for the write concern to be fulfilled before timing out.
        • maxTimeMS: The cumulative time limit for processing operations on a cursor. See: cursor.maxTimeMS.
        • maxCommitTimeMS: The maximum amount of time to allow a single commitTransaction command to execute. See: TransactionOptions.getMaxCommitTime(java.util.concurrent.TimeUnit).
      • 0 means infinite timeout.
      • > 0 The time limit to use for the full execution of an operation.
      Parameters:
      timeUnit - the time unit
      Returns:
      the timeout in the given time unit
      Since:
      4.x

    • withChunkSizeBytes

      GridFSBucket withChunkSizeBytes(int chunkSizeBytes)
      Create a new GridFSBucket instance with a new chunk size in bytes.
      Parameters:
      chunkSizeBytes - the new chunk size in bytes.
      Returns:
      a new GridFSBucket instance with the different chunk size in bytes

    • withReadPreference

      GridFSBucket withReadPreference(ReadPreference readPreference)
      Create a new GridFSBucket instance with a different read preference.
      Parameters:
      readPreference - the new ReadPreference for the GridFSBucket
      Returns:
      a new GridFSBucket instance with the different readPreference

    • withWriteConcern

      GridFSBucket withWriteConcern(WriteConcern writeConcern)
      Create a new GridFSBucket instance with a different write concern.
      Parameters:
      writeConcern - the new WriteConcern for the GridFSBucket
      Returns:
      a new GridFSBucket instance with the different writeConcern

    • withReadConcern

      GridFSBucket withReadConcern(ReadConcern readConcern)
      Create a new GridFSBucket instance with a different read concern.
      Parameters:
      readConcern - the new ReadConcern for the GridFSBucket
      Returns:
      a new GridFSBucket instance with the different ReadConcern
      Since:
      3.2
      MongoDB documentation
      Read Concern
      Since server release
      3.2

    • withTimeout

      @Alpha(CLIENT) GridFSBucket withTimeout(long timeout, TimeUnit timeUnit)
      Create a new GridFSBucket instance with the set time limit for the full execution of an operation.
      • 0 means infinite timeout.
      • > 0 The time limit to use for the full execution of an operation.
      Parameters:
      timeout - the timeout, which must be greater than or equal to 0
      timeUnit - the time unit
      Returns:
      a new GridFSBucket instance with the set time limit for the full execution of an operation
      Since:
      4.x
      See Also:

    • openUploadStream

      GridFSUploadStream openUploadStream(String filename)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      filename - the filename for the stream
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.

    • openUploadStream

      GridFSUploadStream openUploadStream(String filename, GridFSUploadOptions options)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      filename - the filename for the stream
      options - the GridFSUploadOptions
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.

    • openUploadStream

      GridFSUploadStream openUploadStream(BsonValue id, String filename)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      id - the custom id value of the file
      filename - the filename for the stream
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.3

    • openUploadStream

      GridFSUploadStream openUploadStream(BsonValue id, String filename, GridFSUploadOptions options)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      id - the custom id value of the file
      filename - the filename for the stream
      options - the GridFSUploadOptions
      Returns:
      the GridFSUploadStream that includes the _id for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.3

    • openUploadStream

      GridFSUploadStream openUploadStream(ClientSession clientSession, String filename)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the filename for the stream
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.6
      Since server release
      3.6

    • openUploadStream

      GridFSUploadStream openUploadStream(ClientSession clientSession, String filename, GridFSUploadOptions options)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the filename for the stream
      options - the GridFSUploadOptions
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.6
      Since server release
      3.6

    • openUploadStream

      GridFSUploadStream openUploadStream(ClientSession clientSession, BsonValue id, String filename)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file
      filename - the filename for the stream
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.6
      Since server release
      3.6

    • openUploadStream

      GridFSUploadStream openUploadStream(ClientSession clientSession, ObjectId id, String filename)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file
      filename - the filename for the stream
      Returns:
      the GridFSUploadStream that provides the ObjectId for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.6
      Since server release
      3.6

    • openUploadStream

      GridFSUploadStream openUploadStream(ClientSession clientSession, BsonValue id, String filename, GridFSUploadOptions options)
      Opens a Stream that the application can write the contents of the file to.

      As the application writes the contents to the returned Stream, the contents are uploaded as chunks in the chunks collection. When the application signals it is done writing the contents of the file by calling close on the returned Stream, a files collection document is created in the files collection.

      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file
      filename - the filename for the stream
      options - the GridFSUploadOptions
      Returns:
      the GridFSUploadStream that includes the _id for the file to be uploaded and the Stream to which the application will write the contents.
      Since:
      3.6
      Since server release
      3.6

    • uploadFromStream

      ObjectId uploadFromStream(String filename, InputStream source)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Parameters:
      filename - the filename for the stream
      source - the Stream providing the file data
      Returns:
      the ObjectId of the uploaded file.

    • uploadFromStream

      ObjectId uploadFromStream(String filename, InputStream source, GridFSUploadOptions options)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Parameters:
      filename - the filename for the stream
      source - the Stream providing the file data
      options - the GridFSUploadOptions
      Returns:
      the ObjectId of the uploaded file.

    • uploadFromStream

      void uploadFromStream(BsonValue id, String filename, InputStream source)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      id - the custom id value of the file
      filename - the filename for the stream
      source - the Stream providing the file data
      Since:
      3.3

    • uploadFromStream

      void uploadFromStream(BsonValue id, String filename, InputStream source, GridFSUploadOptions options)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      id - the custom id value of the file
      filename - the filename for the stream
      source - the Stream providing the file data
      options - the GridFSUploadOptions
      Since:
      3.3

    • uploadFromStream

      ObjectId uploadFromStream(ClientSession clientSession, String filename, InputStream source)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the filename for the stream
      source - the Stream providing the file data
      Returns:
      the ObjectId of the uploaded file.
      Since:
      3.6
      Since server release
      3.6

    • uploadFromStream

      ObjectId uploadFromStream(ClientSession clientSession, String filename, InputStream source, GridFSUploadOptions options)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the filename for the stream
      source - the Stream providing the file data
      options - the GridFSUploadOptions
      Returns:
      the ObjectId of the uploaded file.
      Since:
      3.6
      Since server release
      3.6

    • uploadFromStream

      void uploadFromStream(ClientSession clientSession, BsonValue id, String filename, InputStream source)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file
      filename - the filename for the stream
      source - the Stream providing the file data
      Since:
      3.6
      Since server release
      3.6

    • uploadFromStream

      void uploadFromStream(ClientSession clientSession, BsonValue id, String filename, InputStream source, GridFSUploadOptions options)
      Uploads the contents of the given InputStream to a GridFS bucket.

      Reads the contents of the user file from the Stream and uploads it as chunks in the chunks collection. After all the chunks have been uploaded, it creates a files collection document for filename in the files collection.

      Note: When this GridFSBucket is set with a operation timeout (via timeout inherited from MongoDatabase settings or withTimeout(long, TimeUnit)), timeout breaches may occur due to the InputStream lacking inherent read timeout support, which might extend the operation beyond the specified timeout limit.

      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file
      filename - the filename for the stream
      source - the Stream providing the file data
      options - the GridFSUploadOptions
      Since:
      3.6
      Since server release
      3.6

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(ObjectId id)
      Opens a Stream from which the application can read the contents of the stored file specified by id.
      Parameters:
      id - the ObjectId of the file to be put into a stream.
      Returns:
      the stream

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(BsonValue id)
      Opens a Stream from which the application can read the contents of the stored file specified by id.
      Parameters:
      id - the custom id value of the file, to be put into a stream.
      Returns:
      the stream

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(String filename)
      Opens a Stream from which the application can read the contents of the latest version of the stored file specified by the filename.
      Parameters:
      filename - the name of the file to be downloaded
      Returns:
      the stream
      Since:
      3.3

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(String filename, GridFSDownloadOptions options)
      Opens a Stream from which the application can read the contents of the stored file specified by filename and the revision in options.
      Parameters:
      filename - the name of the file to be downloaded
      options - the download options
      Returns:
      the stream
      Since:
      3.3

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(ClientSession clientSession, ObjectId id)
      Opens a Stream from which the application can read the contents of the stored file specified by id.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the ObjectId of the file to be put into a stream.
      Returns:
      the stream
      Since:
      3.6
      Since server release
      3.6

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(ClientSession clientSession, BsonValue id)
      Opens a Stream from which the application can read the contents of the stored file specified by id.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id value of the file, to be put into a stream.
      Returns:
      the stream
      Since:
      3.6
      Since server release
      3.6

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(ClientSession clientSession, String filename)
      Opens a Stream from which the application can read the contents of the latest version of the stored file specified by the filename.
      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the name of the file to be downloaded
      Returns:
      the stream
      Since:
      3.6
      Since server release
      3.6

    • openDownloadStream

      GridFSDownloadStream openDownloadStream(ClientSession clientSession, String filename, GridFSDownloadOptions options)
      Opens a Stream from which the application can read the contents of the stored file specified by filename and the revision in options.
      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the name of the file to be downloaded
      options - the download options
      Returns:
      the stream
      Since:
      3.6
      Since server release
      3.6

    • downloadToStream

      void downloadToStream(ObjectId id, OutputStream destination)
      Downloads the contents of the stored file specified by id and writes the contents to the destination Stream.
      Parameters:
      id - the ObjectId of the file to be written to the destination stream
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.

    • downloadToStream

      void downloadToStream(BsonValue id, OutputStream destination)
      Downloads the contents of the stored file specified by id and writes the contents to the destination Stream.
      Parameters:
      id - the custom id of the file, to be written to the destination stream
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.

    • downloadToStream

      void downloadToStream(String filename, OutputStream destination)
      Downloads the contents of the latest version of the stored file specified by filename and writes the contents to the destination Stream.
      Parameters:
      filename - the name of the file to be downloaded
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.
      Since:
      3.3

    • downloadToStream

      void downloadToStream(String filename, OutputStream destination, GridFSDownloadOptions options)
      Downloads the contents of the stored file specified by filename and by the revision in options and writes the contents to the destination Stream.
      Parameters:
      filename - the name of the file to be downloaded
      destination - the destination stream
      options - the download options. Its OutputStream.flush() is not guaranteed to be called by this method.
      Since:
      3.3

    • downloadToStream

      void downloadToStream(ClientSession clientSession, ObjectId id, OutputStream destination)
      Downloads the contents of the stored file specified by id and writes the contents to the destination Stream.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the ObjectId of the file to be written to the destination stream
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.
      Since:
      3.6
      Since server release
      3.6

    • downloadToStream

      void downloadToStream(ClientSession clientSession, BsonValue id, OutputStream destination)
      Downloads the contents of the stored file specified by id and writes the contents to the destination Stream.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the custom id of the file, to be written to the destination stream
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.
      Since:
      3.6
      Since server release
      3.6

    • downloadToStream

      void downloadToStream(ClientSession clientSession, String filename, OutputStream destination)
      Downloads the contents of the latest version of the stored file specified by filename and writes the contents to the destination Stream.
      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the name of the file to be downloaded
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.
      Since:
      3.6
      Since server release
      3.6

    • downloadToStream

      void downloadToStream(ClientSession clientSession, String filename, OutputStream destination, GridFSDownloadOptions options)
      Downloads the contents of the stored file specified by filename and by the revision in options and writes the contents to the destination Stream.
      Parameters:
      clientSession - the client session with which to associate this operation
      filename - the name of the file to be downloaded
      destination - the destination stream. Its OutputStream.flush() is not guaranteed to be called by this method.
      options - the download options
      Since:
      3.6
      Since server release
      3.6

    • find

      GridFSFindIterable find()
      Finds all documents in the files collection.
      Returns:
      the GridFS find iterable interface
      MongoDB documentation
      Find

    • find

      GridFSFindIterable find(Bson filter)
      Finds all documents in the collection that match the filter.

      Below is an example of filtering against the filename and some nested metadata that can also be stored along with the file data: 

        
      Filters.and(Filters.eq("filename", "mongodb.png"), Filters.eq("metadata.contentType", "image/png"));
      Parameters:
      filter - the query filter
      Returns:
      the GridFS find iterable interface
      See Also:

    • find

      GridFSFindIterable find(ClientSession clientSession)
      Finds all documents in the files collection.
      Parameters:
      clientSession - the client session with which to associate this operation
      Returns:
      the GridFS find iterable interface
      Since:
      3.6
      MongoDB documentation
      Find
      Since server release
      3.6

    • find

      GridFSFindIterable find(ClientSession clientSession, Bson filter)
      Finds all documents in the collection that match the filter.

      Below is an example of filtering against the filename and some nested metadata that can also be stored along with the file data: 

        
      Filters.and(Filters.eq("filename", "mongodb.png"), Filters.eq("metadata.contentType", "image/png"));
      Parameters:
      clientSession - the client session with which to associate this operation
      filter - the query filter
      Returns:
      the GridFS find iterable interface
      Since:
      3.6
      See Also:
      Since server release
      3.6

    • delete

      void delete(ObjectId id)
      Given a id, delete this stored file's files collection document and associated chunks from a GridFS bucket.
      Parameters:
      id - the ObjectId of the file to be deleted

    • delete

      void delete(BsonValue id)
      Given a id, delete this stored file's files collection document and associated chunks from a GridFS bucket.
      Parameters:
      id - the id of the file to be deleted
      Since:
      3.3

    • delete

      void delete(ClientSession clientSession, ObjectId id)
      Given a id, delete this stored file's files collection document and associated chunks from a GridFS bucket.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the ObjectId of the file to be deleted
      Since:
      3.6
      Since server release
      3.6

    • delete

      void delete(ClientSession clientSession, BsonValue id)
      Given a id, delete this stored file's files collection document and associated chunks from a GridFS bucket.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the id of the file to be deleted
      Since:
      3.6
      Since server release
      3.6

    • rename

      void rename(ObjectId id, String newFilename)
      Renames the stored file with the specified id.
      Parameters:
      id - the id of the file in the files collection to rename
      newFilename - the new filename for the file

    • rename

      void rename(BsonValue id, String newFilename)
      Renames the stored file with the specified id.
      Parameters:
      id - the id of the file in the files collection to rename
      newFilename - the new filename for the file
      Since:
      3.3

    • rename

      void rename(ClientSession clientSession, ObjectId id, String newFilename)
      Renames the stored file with the specified id.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the id of the file in the files collection to rename
      newFilename - the new filename for the file
      Since:
      3.6
      Since server release
      3.6

    • rename

      void rename(ClientSession clientSession, BsonValue id, String newFilename)
      Renames the stored file with the specified id.
      Parameters:
      clientSession - the client session with which to associate this operation
      id - the id of the file in the files collection to rename
      newFilename - the new filename for the file
      Since:
      3.6
      Since server release
      3.6

    • drop

      void drop()
      Drops the data associated with this bucket from the database.

    • drop

      void drop(ClientSession clientSession)
      Drops the data associated with this bucket from the database.
      Parameters:
      clientSession - the client session with which to associate this operation
      Since:
      3.6
      Since server release
      3.6