JarCastingMongoDB GridFS
Provides MongoDB GridFS support via the Vert.x event bus keeping file chunks in a binary format. See the MongoDB site for more information on GridFS: http://docs.mongodb.org/manual/reference/gridfs/
Dependencies
This module requires a MongoDB server to be available on the network.
Configuration
The MongoDB GridFS module takes the following configuration:
{
"address": <address>,
"host": <host>,
"port": <port>,
"db_name": <db_name>,
"pool_size": <pool_size>
}
Or for replica sets:
{
"address": <address>,
"seeds": [{"host":<address1>, "port":<port1>},{"host":<address2>, "port":<port2>}]
"db_name": <db_name>,
"pool_size": <pool_size>
}
For example:
{
"address": "test.my_persistor",
"host": "192.168.1.100",
"port": 27000,
"pool_size": 20,
"db_name": "my_db"
}
Or for replica sets:
{
"address": "test.my_persistor",
"seeds": [{"host":"192.168.1.100", "port":27000},{"host":"192.168.1.101", "port":27000}]
"pool_size": 20,
"db_name": "my_db"
}
Let's take a look at each field in turn:
addressThe main address for the module. Every module has a main address. Defaults toet.mongo.gridfs.hostHost name or ip address of the MongoDB instance. Defaults tolocalhost.portPort at which the MongoDB instance is listening. Defaults to27017.db_nameName of the database in the MongoDB instance to use. Defaults todefault_db.pool_sizeThe number of socket connections the module instance should maintain to the MongoDB server. Default is 10.seedsUse instead of host and port when connecting to a replica set.
Operations
The module supports the following operations
Get File
Returns GridFS file information for a given id.
Send a JSON message to the module main address:
{
"action": "getFile",
"id": <id>,
"bucket": <bucket>
}
Where:
idis the ObjectId of the GridFS file. This field is mandatory.bucketis GridFS bucket the file was saved under. The default value is "fs".
An example would be:
{
"action": "getFile",
"id": "51d864754728011036adc575",
"bucket": "my_bucket"
}
When the getFile completes successfully, a reply message is sent back to the sender with the following data:
{
"status": "ok",
"filename": <filename>,
"contentType": <contentType>,
"length": <length>,
"chunkSize": <chunkSize>,
"uploadDate": <uploadDate>,
"metadata": <metadata>
}
Where:
filenameis the filename provided when savingcontentTypeis the content type (ex. image/jpeg)lengthis the total file length in byteschunkSizeis the size in bytes of each chunkuploadDateis the long time of the upload in milliseconds since 1 Jan 1970metadatais an optional json object with additional metadata
If an error occurs in saving the document a reply is returned:
{
"status": "error",
"message": <message>
}
Where message is an error message.
Get Chunk
Returns a GridFS file chunk
Send a JSON message to the module main address:
{
"action": "getChunk",
"files_id": <files_id>,
"n": <n>,
"bucket": <bucket>,
"reply": <reply>
}
Where:
files_idis the ObjectId of the filenis the chunk number (first chunk is 0).bucketis GridFS bucket the file was saved under. The default value is "fs".replyis a boolean flag indicating a reply message handler should be added to send the next chunk
An example would be:
{
"action": "getChunk",
"files_id": "51d864754728011036adc575",
"n": 0,
"bucket": "my_bucket",
"reply": true
}
When the get chunk completes successfully, a reply message with the chunk data byte[] in the message body is returned.
If an error occurs when getting the chunk, a json message is returned:
{
"status": "error",
"message": <message>
}
Where message is an error message.
Save File
Saves the file information.
Send a JSON message to the module main address:
{
"action": "saveFile",
"id": <id>,
"length": <length>,
"chunkSize": <chunkSize>,
"uploadDate": <uploadDate>,
"filename": <filename>,
"contentType": <contentType>,
"bucket": <bucket>
}
Where:
idis the ObjectId of the file.lengthis the total file length in byteschunkSizeis the size in bytes of each chunkuploadDateis the long time of the upload in milliseconds since 1 Jan 1970. The field is optional.filenameis the filename provided when saving. This field is optional.contentTypeis the content type (ex. image/jpeg). This field is optional (but recommended).bucketis GridFS bucket the file was saved under. The default value is "fs".
An example would be:
{
"action": "saveFile",
"id": "51d864754728011036adc575",
"length": 161966,
"chunkSize": 102400,
"contentType": "image/jpeg"
}
When the save completes successfully, a reply message is sent back to the sender with the following data:
{
"status": "ok"
}
If an error occurs when saving the file information a reply is returned:
{
"status": "error",
"message": <message>
}
Where message is an error message.
Save Chunk
Saves a chunk of binary data in the GridFS format.
Send a Buffer message to the module main address + "/saveChunk".
The Buffer is made up of 3 parts:
- The first four bytes are an int defining the length of a UTF-8 encoded json string.
- The json bytes are next
- The remaining bytes are the chunk to be saved
The json contains the following fields:
{
"files_id": <files_id>,
"n": <n>,
"bucket": <bucket>
}
Where:
files_idis the ObjectId of the filenis the chunk number (first chunk is 0).bucketis GridFS bucket the file was saved under. The default value is "fs".
An example would be:
{
"files_id": "51d864754728011036adc575",
"n": 0,
"bucket": "my_bucket",
}
An example of generating the message would be:
public Buffer getMessage(String files_id, int chunkNumber, byte[] data) {
JsonObject jsonObject = new JsonObject()
.putString("files_id", files_id)
.putNumber("n", chunkNumber);
byte[] json = jsonObject.encode().getBytes("UTF-8");
byte[] data = getData(chunkNumber);
Buffer buffer = new Buffer();
buffer.appendInt(json.length);
buffer.appendBytes(json);
buffer.appendBytes(data);
return buffer;
}
When the save completes successfully, a reply message is sent back to the sender with the following data:
{
"status": "ok"
}
