Package com.mongodb.gridfs

Class GridFS

java.lang.Object

com.mongodb.gridfs.GridFS

public class GridFS
extends Object

Implementation of GridFS - a specification for storing and retrieving files that exceed the BSON-document size limit of 16MB.

Instead of storing a file in a single document, GridFS divides a file into parts, or chunks, and stores each of those chunks as a separate document. By default GridFS limits chunk size to 255k. GridFS uses two collections to store files. One collection stores the file chunks, and the other stores file metadata.

When you query a GridFS store for a file, the driver or client will reassemble the chunks as needed. You can perform range queries on files stored through GridFS. You also can access information from arbitrary sections of files, which allows you to "skip" into the middle of a video or audio file.

GridFS is useful not only for storing files that exceed 16MB but also for storing any files for which you want access without having to load the entire file into memory. For more information on the indications of GridFS, see MongoDB official documentation.

MongoDB documentation

GridFS

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_BUCKET	Bucket to use for the collection namespaces
static int	DEFAULT_CHUNKSIZE	File's chunk size
static long	MAX_CHUNKSIZE	Deprecated. You can calculate max chunkSize with a similar formula Mongo.getMaxBsonObjectSize() - 500*1000. Please ensure that you left enough space for metadata (500kb is enough).

Constructor Summary

Constructors

Constructor	Description
GridFS(DB db)	Creates a GridFS instance for the default bucket "fs" in the given database.
GridFS(DB db, String bucket)	Creates a GridFS instance for the specified bucket in the given database.

Method Summary

Modifier and Type	Method	Description
GridFSInputFile	createFile()	This method creates an empty GridFSInputFile instance.
GridFSInputFile	createFile(byte[] data)	Creates a file entry.
GridFSInputFile	createFile(File file)	Creates a file entry.
GridFSInputFile	createFile(InputStream in)	Creates a file entry.
GridFSInputFile	createFile(InputStream in, boolean closeStreamOnPersist)	Creates a file entry.
GridFSInputFile	createFile(InputStream in, String filename)	Creates a file entry.
GridFSInputFile	createFile(InputStream in, String filename, boolean closeStreamOnPersist)	Creates a file entry.
GridFSInputFile	createFile(String filename)	Creates a file entry.
List<GridFSDBFile>	find(DBObject query)	Finds a list of files matching the given query.
List<GridFSDBFile>	find(DBObject query, DBObject sort)	Finds a list of files matching the given query.
List<GridFSDBFile>	find(String filename)	Finds a list of files matching the given filename.
List<GridFSDBFile>	find(String filename, DBObject sort)	Finds a list of files matching the given filename.
GridFSDBFile	find(ObjectId objectId)	Finds one file matching the given objectId.
GridFSDBFile	findOne(DBObject query)	Finds one file matching the given query.
GridFSDBFile	findOne(String filename)	Finds one file matching the given filename.
GridFSDBFile	findOne(ObjectId objectId)	Finds one file matching the given objectId.
String	getBucketName()	Gets the bucket name used in the collection's namespace.
protected DBCollection	getChunksCollection()	Gets the DBCollection in which the binary chunks are stored.
DB	getDB()	Gets the database used.
DBCursor	getFileList()	Gets the list of files stored in this gridfs, sorted by filename.
DBCursor	getFileList(DBObject query)	Gets a filtered list of files stored in this gridfs, sorted by filename.
DBCursor	getFileList(DBObject query, DBObject sort)	Gets a sorted, filtered list of files stored in this gridfs.
protected DBCollection	getFilesCollection()	Gets the DBCollection in which the file's metadata is stored.
void	remove(DBObject query)	Removes all files matching the given query.
void	remove(String filename)	Removes all files matching the given filename.
void	remove(ObjectId id)	Removes the file matching the given id.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CHUNKSIZE

public static final int DEFAULT_CHUNKSIZE

File's chunk size

See Also:

Constant Field Values

MAX_CHUNKSIZE

@Deprecated
public static final long MAX_CHUNKSIZE

Deprecated. You can calculate max chunkSize with a similar formula Mongo.getMaxBsonObjectSize() - 500*1000. Please ensure that you left enough space for metadata (500kb is enough).

File's max chunk size

See Also:

Constant Field Values

DEFAULT_BUCKET

public static final String DEFAULT_BUCKET

Bucket to use for the collection namespaces

See Also:

Constant Field Values

Constructor Detail

GridFS

public GridFS(DB db)

Creates a GridFS instance for the default bucket "fs" in the given database. Set the preferred WriteConcern on the give DB with DB.setWriteConcern

Parameters:

db - database to work with

Throws:

MongoException - if there's a failure

See Also:

WriteConcern

GridFS

public GridFS(DB db,
              String bucket)

Creates a GridFS instance for the specified bucket in the given database. Set the preferred WriteConcern on the give DB with DB.setWriteConcern

Parameters:

db - database to work with

bucket - bucket to use in the given database

Throws:

MongoException - if there's a failure

See Also:

WriteConcern

Method Detail

getFileList

public DBCursor getFileList()

Gets the list of files stored in this gridfs, sorted by filename.

Returns:

cursor of file objects

getFileList

public DBCursor getFileList(DBObject query)

Gets a filtered list of files stored in this gridfs, sorted by filename.

Parameters:

query - filter to apply

Returns:

cursor of file objects

getFileList

public DBCursor getFileList(DBObject query,
                            DBObject sort)

Gets a sorted, filtered list of files stored in this gridfs.

Parameters:

query - filter to apply

sort - sorting to apply

Returns:

cursor of file objects

find

public GridFSDBFile find(ObjectId objectId)

Finds one file matching the given objectId. Equivalent to findOne(objectId).

Parameters:

objectId - the objectId of the file stored on a server

Returns:

a gridfs file

Throws:

MongoException - if the operation fails

findOne

public GridFSDBFile findOne(ObjectId objectId)

Finds one file matching the given objectId.

Parameters:

objectId - the objectId of the file stored on a server

Returns:

a gridfs file

Throws:

MongoException - if the operation fails

findOne

public GridFSDBFile findOne(String filename)

Finds one file matching the given filename.

Parameters:

filename - the name of the file stored on a server

Returns:

the gridfs db file

Throws:

MongoException - if the operation fails

findOne

public GridFSDBFile findOne(DBObject query)

Finds one file matching the given query.

Parameters:

query - filter to apply

Returns:

a gridfs file

Throws:

MongoException - if the operation fails

find

public List<GridFSDBFile> find(String filename)

Finds a list of files matching the given filename.

Parameters:

filename - the filename to look for

Returns:

list of gridfs files

Throws:

MongoException - if the operation fails

find

public List<GridFSDBFile> find(String filename,
                               DBObject sort)

Finds a list of files matching the given filename.

Parameters:

filename - the filename to look for

sort - the fields to sort with

Returns:

list of gridfs files

Throws:

MongoException - if the operation fails

find

public List<GridFSDBFile> find(DBObject query)

Finds a list of files matching the given query.

Parameters:

query - the filter to apply

Returns:

list of gridfs files

Throws:

MongoException - if the operation fails

find

public List<GridFSDBFile> find(DBObject query,
                               DBObject sort)

Finds a list of files matching the given query.

Parameters:

query - the filter to apply

sort - the fields to sort with

Returns:

list of gridfs files

Throws:

MongoException - if the operation fails

remove

public void remove(ObjectId id)

Removes the file matching the given id.

Parameters:

id - the id of the file to be removed

Throws:

MongoException - if the operation fails

remove

public void remove(String filename)

Removes all files matching the given filename.

Parameters:

filename - the name of the file to be removed

Throws:

MongoException - if the operation fails

remove

public void remove(DBObject query)

Removes all files matching the given query.

Parameters:

query - filter to apply

Throws:

MongoException - if the operation fails

createFile

public GridFSInputFile createFile(byte[] data)

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

data - the file's data

Returns:

a gridfs input file

createFile

public GridFSInputFile createFile(File file)
                           throws IOException

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

file - the file object

Returns:

a GridFS input file

Throws:

IOException - if there are problems reading file

createFile

public GridFSInputFile createFile(InputStream in)

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

in - an inputstream containing the file's data

Returns:

a gridfs input file

createFile

public GridFSInputFile createFile(InputStream in,
                                  boolean closeStreamOnPersist)

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

in - an inputstream containing the file's data

closeStreamOnPersist - indicate the passed in input stream should be closed once the data chunk persisted

Returns:

a gridfs input file

createFile

public GridFSInputFile createFile(InputStream in,
                                  String filename)

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

in - an inputstream containing the file's data

filename - the file name as stored in the db

Returns:

a gridfs input file

createFile

public GridFSInputFile createFile(InputStream in,
                                  String filename,
                                  boolean closeStreamOnPersist)

Creates a file entry. After calling this method, you have to call GridFSInputFile.save().

Parameters:

in - an inputstream containing the file's data

filename - the file name as stored in the db

closeStreamOnPersist - indicate the passed in input stream should be closed once the data chunk persisted

Returns:

a gridfs input file

createFile

public GridFSInputFile createFile(String filename)

Creates a file entry.

Parameters:

filename - the file name as stored in the db

Returns:

a gridfs input file

See Also:

createFile()

createFile

public GridFSInputFile createFile()

This method creates an empty GridFSInputFile instance. On this instance an OutputStream can be obtained using the GridFSInputFile.getOutputStream() method. You can still call GridFSInputFile.setContentType(String) and GridFSInputFile.setFilename(String). The file will be completely written and closed after calling the OutputStream.close() method on the output stream.

Returns:

GridFS file handle instance.

getBucketName

public String getBucketName()

Gets the bucket name used in the collection's namespace. Default value is 'fs'.

Returns:

the name of the file bucket

getDB

public DB getDB()

Gets the database used.

Returns:

the database

getFilesCollection

protected DBCollection getFilesCollection()

Gets the DBCollection in which the file's metadata is stored.

Returns:

the collection

getChunksCollection

protected DBCollection getChunksCollection()

Gets the DBCollection in which the binary chunks are stored.

Returns:

the collection