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 256k. 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.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	_bucketName Deprecated. Please use getBucketName() for access.
protected DBCollection	_chunkCollection Deprecated. Please use getChunksCollection() for access.
protected DB	_db Deprecated. Please use getDB() for access.
protected DBCollection	_filesCollection Deprecated. Please use getFilesCollection() for access.
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 and 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 and Description
protected GridFSDBFile	_fix(Object o) Deprecated. This method is NOT a part of public API and will be dropped in 3.x versions.
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.
GridFSDBFile	find(ObjectId objectId) Finds one file matching the given objectId.
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	findOne(DBObject query) Finds one file matching the given query.
GridFSDBFile	findOne(ObjectId objectId) Finds one file matching the given objectId.
GridFSDBFile	findOne(String filename) Finds one file matching the given filename.
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(ObjectId id) Removes the file matching the given id.
void	remove(String filename) Removes all files matching the given filename.

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

_db

@Deprecated
protected final DB _db

Deprecated. Please use getDB() for access.

_bucketName

@Deprecated
protected final String _bucketName

Deprecated. Please use getBucketName() for access.

_filesCollection

@Deprecated
protected final DBCollection _filesCollection

Deprecated. Please use getFilesCollection() for access.

_chunkCollection

@Deprecated
protected final DBCollection _chunkCollection

Deprecated. Please use getChunksCollection() for access.

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

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

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

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

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

findOne

public GridFSDBFile findOne(DBObject query)

Finds one file matching the given query.

Parameters:

query - filter to apply

Returns:

a gridfs file

Throws:

MongoException

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

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

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

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

_fix

@Deprecated
protected GridFSDBFile _fix(Object o)

Deprecated. This method is NOT a part of public API and will be dropped in 3.x versions.

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

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

remove

public void remove(DBObject query)

Removes all files matching the given query.

Parameters:

query - filter to apply

Throws:

MongoException

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