GridFs (mongodb-async-driver 2.0.1 API)

java.lang.Object
- com.allanbank.mongodb.gridfs.GridFs

```
public class GridFs
extends Object
```
GridFs provides an interface for working with a GridFS collection.
This implementation uses a ObjectId as the id when writing and stores the name of the file in the files collection document's "filename" field. To unlink(String) or read(String, OutputStream) a file from the collection the _id field may contain any value but the filename field must be present.

API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2012-2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CHUNK_NUMBER_FIELD` The field in the `chunks` collection containing the chunk's number.
`static int`	`CHUNK_OVERHEAD` The amount of overhead in a chunk document in bytes: 62
`static String`	`CHUNK_SIZE_FIELD` The field in the `files` collection containing the file's chunk size.
`static String`	`CHUNKS_SUFFIX` The suffix for the chunks collection.
`static String`	`DATA_FIELD` The field in the `chunks` collection containing the chunk's data.
`static int`	`DEFAULT_CHUNK_SIZE` The default chunk size.
`static String`	`DEFAULT_ROOT` The suffix for the files collection.
`static String`	`FILENAME_FIELD` The field in the `files` collection containing the file's name.
`static String`	`FILES_ID_FIELD` The field in the `chunks` collection containing the chunk's related file id.
`static String`	`FILES_SUFFIX` The suffix for the files collection.
`static String`	`ID_FIELD` The `_id` field name.
`static String`	`LENGTH_FIELD` The field in the `files` collection containing the file's length.
`static String`	`MD5_FIELD` The field in the `files` collection containing the file's MD5.
`static String`	`UPLOAD_DATE_FIELD` The field in the `files` collection containing the file's upload date.

Constructor Summary

Constructors
Constructor and Description
`GridFs(MongoDatabase database)` Creates a new GridFs.
`GridFs(MongoDatabase database, String rootName)` Creates a new GridFs.
`GridFs(String mongoDbUri)` Creates a new GridFs.
`GridFs(String mongoDbUri, String rootName)` Creates a new GridFs.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`createIndexes()` Creates the following indexes: Files Collection: `{ 'filename' : 1, 'uploadDate' : 1 }` Chunks Collection: `{ 'files_id' : 1, 'n' : 1 }` If in a non-sharded environment the indexes will be unique.
`protected void`	`doAddFault(Map<Object,List<String>> faults, Element idObj, String message)` Adds a fault message to the faults map.
`protected void`	`doRead(Document fileDoc, OutputStream sink)` Reads a file from the GridFS collections and writes the contents to the `sink`
`protected void`	`doTryAndRepair(Document fileDoc, Map<Object,List<String>> faults)` Tries to repair the file.
`protected boolean`	`doUnlink(Document fileDoc)` Unlinks (deletes) the file from the GridFS collections.
`protected boolean`	`doValidate(Document fileDoc)` Validates the file from the GridFS collections using the `filemd5` command.
`protected boolean`	`doVerifyFileMd5(Map<Object,List<String>> faults, Document fileDoc, Document cmdResult)` Verifies the MD5 result for the filemd5 command.
`Map<Object,List<String>>`	`fsck(boolean repair)` Validates and optionally tries to repair the GridFS collections.
`int`	`getChunkSize()` Returns the size for a chunk written.
`void`	`read(ObjectId id, OutputStream sink)` Reads a file from the GridFS collections and writes the contents to the `sink`
`void`	`read(String name, OutputStream sink)` Reads a file from the GridFS collections and writes the contents to the `sink`
`void`	`setChunkSize(int chunkSize)` Sets the value of size for a chunk written.
`boolean`	`unlink(ObjectId id)` Unlinks (deletes) the file from the GridFS collections.
`boolean`	`unlink(String name)` Unlinks (deletes) the file from the GridFS collections.
`boolean`	`validate(ObjectId id)` Validates the file from the GridFS collections using the `filemd5` command.
`boolean`	`validate(String name)` Validates the file from the GridFS collections using the `filemd5` command.
`ObjectId`	`write(String name, InputStream source)` Attempts to write a file into the GridFS collections using the specified name for the file and deriving the chunks from the data read from the `source`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CHUNK_NUMBER_FIELD
```
public static final String CHUNK_NUMBER_FIELD
```
    The field in the chunks collection containing the chunk's number.
    
    See Also:
    Constant Field Values
  - CHUNK_OVERHEAD
```
public static final int CHUNK_OVERHEAD
```
    The amount of overhead in a chunk document in bytes: 62
    
    See Also:
    Constant Field Values
  - CHUNK_SIZE_FIELD
```
public static final String CHUNK_SIZE_FIELD
```
    The field in the files collection containing the file's chunk size.
    
    See Also:
    Constant Field Values
  - CHUNKS_SUFFIX
```
public static final String CHUNKS_SUFFIX
```
    The suffix for the chunks collection.
    
    See Also:
    Constant Field Values
  - DATA_FIELD
```
public static final String DATA_FIELD
```
    The field in the chunks collection containing the chunk's data.
    
    See Also:
    Constant Field Values
  - DEFAULT_CHUNK_SIZE
```
public static final int DEFAULT_CHUNK_SIZE
```
    The default chunk size. This is slightly less than 256K to allow for the CHUNK_OVERHEAD when using the power of two allocator.
  - DEFAULT_ROOT
```
public static final String DEFAULT_ROOT
```
    The suffix for the files collection.
    
    See Also:
    Constant Field Values
  - FILENAME_FIELD
```
public static final String FILENAME_FIELD
```
    The field in the files collection containing the file's name.
    
    See Also:
    Constant Field Values
  - FILES_ID_FIELD
```
public static final String FILES_ID_FIELD
```
    The field in the chunks collection containing the chunk's related file id.
    
    See Also:
    Constant Field Values
  - FILES_SUFFIX
```
public static final String FILES_SUFFIX
```
    The suffix for the files collection.
    
    See Also:
    Constant Field Values
  - ID_FIELD
```
public static final String ID_FIELD
```
    The _id field name.
    
    See Also:
    Constant Field Values
  - LENGTH_FIELD
```
public static final String LENGTH_FIELD
```
    The field in the files collection containing the file's length.
    
    See Also:
    Constant Field Values
  - MD5_FIELD
```
public static final String MD5_FIELD
```
    The field in the files collection containing the file's MD5.
    
    See Also:
    Constant Field Values
  - UPLOAD_DATE_FIELD
```
public static final String UPLOAD_DATE_FIELD
```
    The field in the files collection containing the file's upload date.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - GridFs
```
public GridFs(MongoDatabase database)
```
    Creates a new GridFs.
    The GridFS objects will be stored in the 'fs' collection.
    
    Parameters:
    database - The database containing the GridFS collections.
  - GridFs
```
public GridFs(MongoDatabase database,
      String rootName)
```
    Creates a new GridFs.
    
    Parameters:
    database - The database containing the GridFS collections.
    rootName - The rootName for the collections. The FILES_SUFFIX and CHUNKS_SUFFIX will be appended to create the two collection names.
  - GridFs
```
public GridFs(String mongoDbUri)
```
    Creates a new GridFs.
    
    Parameters:
    mongoDbUri - The configuration for the connection to MongoDB expressed as a MongoDB URL.
    
    Throws:
    
    IllegalArgumentException - If the mongoDbUri is not a properly formated MongoDB style URL.
    See Also:
    MongoDB Connections
  - GridFs
```
public GridFs(String mongoDbUri,
      String rootName)
```
    Creates a new GridFs.
    
    Parameters:
    mongoDbUri - The configuration for the connection to MongoDB expressed as a MongoDB URL.
    rootName - The rootName for the collections. The FILES_SUFFIX and CHUNKS_SUFFIX will be appended to create the two collection names.
    
    Throws:
    
    IllegalArgumentException - If the mongoDbUri is not a properly formated MongoDB style URL.
    See Also:
    MongoDB Connections
- Method Detail
  - createIndexes
```
public void createIndexes()
```
    Creates the following indexes:
    - Files Collection:
      
      { 'filename' : 1, 'uploadDate' : 1 }
    - Chunks Collection:
      
      { 'files_id' : 1, 'n' : 1 }
    If in a non-sharded environment the indexes will be unique.
  - fsck
```
public Map<Object,List<String>> fsck(boolean repair)
                              throws IOException
```
    Validates and optionally tries to repair the GridFS collections.
    - Ensure the following indexes exist:
      
      Files Collection:
      
      { 'filename' : 1, 'uploadDate' : 1 }
      
      Chunks Collection:
      
      { 'files_id' : 1, 'n' : 1 }
    - Ensure there are no duplicate n values for the chunks of a file. If repair is true then the n values will be updated to be sequential based on the ordering { 'n' : 1, '_id' 1 }.
    - Validates the MD5 sum for each file via the filemd5 command.
    Warning: This function iterates over every file in the GridFS collection and can take a considerable amount of time and resources on the client and the server.
    
    Note: Due to a limitation in the MongoDB server this method will return false positives when used with a sharded cluster when the shard key for the chunks collection is not one of {files_id:1} or {files_id:1, n:1}. See SERVER-9888.
    Parameters:
    repair - If set to true then the fsck will attempt to repair common errors.
    
    Returns:
    A map of the file ids to the errors found for the file and the repair status. If no errors are found an empty map is returned.
    
    Throws:
    
    IOException - On a failure to execute the fsck.
    See Also:
    SERVER-9888
  - getChunkSize
```
public int getChunkSize()
```
    Returns the size for a chunk written.
    
    Returns:
    The size for a chunk written.
  - read
```
public void read(ObjectId id,
        OutputStream sink)
          throws IOException
```
    Reads a file from the GridFS collections and writes the contents to the sink
    
    Parameters:
    id - The id of the file.
    sink - The stream to write the data to. This stream will not be closed by this method.
    
    Throws:
    
    IOException - On a failure reading the data from MongoDB or writing to the sink.
  - read
```
public void read(String name,
        OutputStream sink)
          throws IOException
```
    Reads a file from the GridFS collections and writes the contents to the sink
    
    Parameters:
    name - The name of the file.
    sink - The stream to write the data to. This stream will not be closed by this method.
    
    Throws:
    
    IOException - On a failure reading the data from MongoDB or writing to the sink.
  - setChunkSize
```
public void setChunkSize(int chunkSize)
```
    Sets the value of size for a chunk written.
    
    Parameters:
    chunkSize - The new value for the size for a chunk written.
  - unlink
```
public boolean unlink(ObjectId id)
               throws IOException
```
    Unlinks (deletes) the file from the GridFS collections.
    
    Parameters:
    id - The id of the file to be deleted.
    
    Returns:
    True if a file was deleted, false otherwise.
    
    Throws:
    
    IOException - On a failure to delete the file.
  - unlink
```
public boolean unlink(String name)
               throws IOException
```
    Unlinks (deletes) the file from the GridFS collections.
    
    Parameters:
    name - The name of the file to be deleted.
    
    Returns:
    True if a file was deleted, false otherwise.
    
    Throws:
    
    IOException - On a failure to validate the file.
  - validate
```
public boolean validate(ObjectId id)
                 throws IOException
```
    Validates the file from the GridFS collections using the filemd5 command.
    Note: Due to a limitation in the MongoDB server this method will always return false when used with a sharded cluster when the shard key for the chunks collection is not one of {files_id:1} or {files_id:1, n:1}. See SERVER-9888.
    
    Parameters:
    id - The id of the file to be validate.
    
    Returns:
    True if a file was validated (md5 hash matches), false otherwise.
    
    Throws:
    
    IOException - On a failure to validate the file.
    See Also:
    SERVER-9888
  - validate
```
public boolean validate(String name)
                 throws IOException
```
    Validates the file from the GridFS collections using the filemd5 command.
    Note: Due to a limitation in the MongoDB server this method will always return false when used with a sharded cluster when the shard key for the chunks collection is not one of {files_id:1} or {files_id:1, n:1}. See SERVER-9888.
    
    Parameters:
    name - The name of the file to be validate.
    
    Returns:
    True if a file was validated (md5 hash matches), false otherwise.
    
    Throws:
    
    IOException - On a failure to validate the file.
    See Also:
    SERVER-9888
  - write
```
public ObjectId write(String name,
             InputStream source)
               throws IOException
```
    Attempts to write a file into the GridFS collections using the specified name for the file and deriving the chunks from the data read from the source.
    
    Parameters:
    name - The name of the file being written.
    source - The source of the bits in the file. This stream will not be closed.
    
    Returns:
    The ObjectId associted with the file.
    
    Throws:
    
    IOException - On a failure writing the documents or reading the file contents. In the case of a failure an attempt is made to remove the documents written to the collections.
  - doAddFault
```
protected void doAddFault(Map<Object,List<String>> faults,
              Element idObj,
              String message)
```
    Adds a fault message to the faults map.
    
    Parameters:
    faults - The map of file ids to the error messages.
    idObj - The id for the file.
    message - The message to add.
  - doRead
```
protected void doRead(Document fileDoc,
          OutputStream sink)
               throws IOException
```
    Reads a file from the GridFS collections and writes the contents to the sink
    
    Parameters:
    fileDoc - The document for the file.
    sink - The stream to write the data to. This stream will not be closed by this method.
    
    Throws:
    
    IOException - On a failure reading the data from MongoDB or writing to the sink.
  - doTryAndRepair
```
protected void doTryAndRepair(Document fileDoc,
                  Map<Object,List<String>> faults)
```
    Tries to repair the file.
    Currently the only strategy is to reorder the chunk's into _id order. The operation verifies that the reorder fixes the file prior to modifying anything. it also verifies that the reordering worked after reordering the chunks.
    
    Parameters:
    fileDoc - The document representing the file.
    faults - The map to update with the status of the repair.
  - doUnlink
```
protected boolean doUnlink(Document fileDoc)
                    throws IOException
```
    Unlinks (deletes) the file from the GridFS collections.
    
    Parameters:
    fileDoc - The document for the file to delete.
    
    Returns:
    True if a file was deleted, false otherwise.
    
    Throws:
    
    IOException - On a failure to delete the file.
  - doValidate
```
protected boolean doValidate(Document fileDoc)
```
    Validates the file from the GridFS collections using the filemd5 command.
    Note: Due to a limitation in the MongoDB server this method will always return false when used with a sharded cluster when the shard key for the chunks collection is not one of {files_id:1} or {files_id:1, n:1}. See SERVER-9888.
    
    Parameters:
    fileDoc - The document for the file to delete.
    
    Returns:
    True if a file was deleted, false otherwise.
    See Also:
    SERVER-9888
  - doVerifyFileMd5
```
protected boolean doVerifyFileMd5(Map<Object,List<String>> faults,
                      Document fileDoc,
                      Document cmdResult)
```
    Verifies the MD5 result for the filemd5 command.
    
    Parameters:
    faults - The faults for to update if the verify fails.
    fileDoc - The document representing the file.
    cmdResult - The document returned from the 'filemd5' command.
    
    Returns:
    True if the file was successful.

Class GridFs

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CHUNK_NUMBER_FIELD

CHUNK_OVERHEAD

CHUNK_SIZE_FIELD

CHUNKS_SUFFIX

DATA_FIELD

DEFAULT_CHUNK_SIZE

DEFAULT_ROOT

FILENAME_FIELD

FILES_ID_FIELD

FILES_SUFFIX

ID_FIELD

LENGTH_FIELD

MD5_FIELD

UPLOAD_DATE_FIELD

Constructor Detail

GridFs

GridFs

GridFs

GridFs

Method Detail

createIndexes

fsck

getChunkSize

read

read

setChunkSize

unlink

unlink

validate

validate

write

doAddFault

doRead

doTryAndRepair

doUnlink

doValidate

doVerifyFileMd5