Browse files

doc GridFS

  • Loading branch information...
1 parent e117f59 commit b15f42ab4f566cc2ab041b1b2d6df80fdae14a9f @gerald-lindsly committed Nov 21, 2011
Showing with 109 additions and 4 deletions.
  1. +109 −4 GridFS.pas
View
113 GridFS.pas
@@ -1,3 +1,16 @@
+{ GridFS Unit - The classes in this unit are used to store and/or
+ access a "Grid File System" (GridFS) on a MongoDB server.
+ While primarily intended to store large documents that
+ won't fit on the server as a single BSON object,
+ GridFS may also be used to store large numbers of smaller files.
+
+ See http://www.mongodb.org/display/DOCS/GridFS and
+ http://www.mongodb.org/display/DOCS/When+to+use+GridFS.
+
+ Objects of class TGridFS represent the interface to the GridFS.
+ Objects of class TGridfile are used to access gridfiles and read from them.
+ Objects of class TGridfileWriter are used to write buffered data to the GridFS.
+}
unit GridFS;
interface
@@ -9,55 +22,147 @@ TGridfile = class;
TGridfileWriter = class;
TGridFS = class(TObject)
+ private
var
+ { Pointer to externally managed data representing the GridFS }
handle : Pointer;
+ { Holds a reference to the TMongo object used in construction.
+ Prevents release until the TGridFS is destroyed. }
conn : TMongo;
+ public
+ { Create a TGridFS object for accessing the GridFS on the MongoDB server.
+ Parameter mongo is an already established connection object to the
+ server; db is the name of the database in which to construct the GridFS.
+ The prefix defaults to 'fs'.}
constructor Create(mongo : TMongo; db : string); overload;
+ { Create a TGridFS object for accessing the GridFS on the MongoDB server.
+ Parameter mongo is an already established connection object to the
+ server; db is the name of the database in which to construct the GridFS.
+ prefix is appended to the database name for the collections that represent
+ the GridFS: 'db.prefix.files' & 'db.prefix.chunks'. }
constructor Create(mongo : TMongo; db : string; prefix : string); overload;
+ { Store a file on the GridFS. filename is the path to the file.
+ Returns True if successful; otherwise, False. }
function storeFile(filename : string) : Boolean; overload;
+ { Store a file on the GridFS. filename is the path to the file.
+ remoteName is the name that the file will be known as within the GridFS.
+ Returns True if successful; otherwise, False. }
function storeFile(filename : string; remoteName : string) : Boolean; overload;
+ { Store a file on the GridFS. filename is the path to the file.
+ remoteName is the name that the file will be known as within the GridFS.
+ contentType is the MIME-type content type of the file.
+ Returns True if successful; otherwise, False. }
function storeFile(filename : string; remoteName : string; contentType : string) : Boolean; overload;
+ { Remove a file from the GridFS. }
procedure removeFile(remoteName : string);
+ { Store data as a GridFS file. Pointer is the address of the data and length
+ is its size. remoteName is the name that the file will be known as within the GridFS.
+ Returns True if successful; otherwise, False. }
function store(p : Pointer; length : Int64; remoteName : string) : Boolean; overload;
+ { Store data as a GridFS file. Pointer is the address of the data and length
+ is its size. remoteName is the name that the file will be known as within the GridFS.
+ contentType is the MIME-type content type of the file.
+ Returns True if successful; otherwise, False. }
function store(p : Pointer; length : Int64; remoteName : string; contentType : string) : Boolean; overload;
+ { Create a TGridfileWriter object for writing buffered data to a GridFS file.
+ remoteName is the name that the file will be known as within the GridFS. }
function writerCreate(remoteName : string) : TGridfileWriter; overload;
+ { Create a TGridfileWriter object for writing buffered data to a GridFS file.
+ remoteName is the name that the file will be known as within the GridFS.
+ contentType is the MIME-type content type of the file. }
function writerCreate(remoteName : string; contentType : string) : TGridfileWriter; overload;
+ { Locate a GridFS file by its remoteName and return a TGridfile object for
+ accessing it. }
function find(remoteName : string) : TGridfile; overload;
+ { Locate a GridFS file by an TBson query document on the GridFS file descriptors.
+ Returns a TGridfile object for accessing it. }
function find(query : TBson) : TGridfile; overload;
+ { Destroy this GridFS object. Releases external resources. }
destructor Destroy(); override;
end;
+ { Objects of class TGridfile are used to access gridfiles and read from them. }
TGridfile = class(TObject)
+ private
var
+ { Pointer to externally managed data representing the gridfile }
handle : Pointer;
+ { Hold a reference to the TGridFS object used in construction of this
+ TGridfile. Prevents release until this TGridfile is destroyed. }
gfs : TGridFS;
- private
+ { Create a TGridfile object. Internal use only by TGridFS.find(). }
constructor Create(gridfs : TGridFS);
public
+ { Get the filename (remoteName) of this gridfile. }
function getFilename() : string;
+ { Get the size of the chunks into which the file is divided. }
function getChunkSize() : Integer;
+ { Get the length of this gridfile. }
function getLength() : Int64;
+ { Get the content type of this gridfile. }
function getContentType() : string;
+ { Get the upload date of this gridfile. }
function getUploadDate() : TDateTime;
+ { Get the MD5 hash of this gridfile. This is a 16-digit hex string. }
function getMD5() : string;
+ { Get any metadata associated with this gridfile as a TBson document.
+ Returns nil if there is none. }
function getMetadata() : TBson;
+ { Get the number of chunks into which the file is divided. }
function getChunkCount() : Integer;
+ { Get the descriptor of this gridfile as a TBson document. }
function getDescriptor() : TBson;
+ { Get the Ith chunk of this gridfile. The content of the chunk is
+ in the 'data' field of the returned TBson document. Returns nil
+ if i is not in the range 0 to getChunkCount() - 1. }
function getChunk(i : Integer) : TBson;
+ { Get a cursor for stepping through a range of chunks of this gridfile.
+ i is the index of the first chunk to be returned. count is the number
+ of chunks to return. Returns nil if there are no chunks in the
+ specified range. }
function getChunks(i : Integer; count : Integer) : TMongoCursor;
+ { Read data from this gridfile. The gridfile maintains a current position
+ so that successive reads will return consecutive data. The data is
+ read to the address indicated by p and length bytes are read. The size
+ of the data read is returned and can be less than length if there was
+ not enough data remaining to be read. }
function read(p : Pointer; length : Int64) : Int64;
+ { Seek to a specified offset within the gridfile. read() will then
+ return data starting at that location. Returns the position that
+ was set. This can be at the end of the gridfile if offset is greater
+ the length of this gridfile. }
function seek(offset : Int64) : Int64;
+ { Destroy this TGridfile object. Releases external resources. }
destructor Destroy(); override;
end;
+ { Objects of class TGridfileWriter are used to write buffered data to the GridFS. }
TGridfileWriter = class(TObject)
+ private
var
+ { Holds a pointer to externally managed data representing the TGridfileWriter. }
handle : Pointer;
+ { Holds a reference to the TGridFS object used in construction.
+ Prevents release of the TGridFS until this TGridfileWriter is destroyed. }
gfs : TGridFS;
+ public
+ { Create a TGridfile writer on the given TGridFS that will write data to
+ the given remoteName. }
constructor Create(gridfs : TGridFS; remoteName : string); overload;
+ { Create a TGridfile writer on the given TGridFS that will write data to
+ the given remoteName. contentType is the MIME-type content type of the gridfile
+ to be written. }
constructor Create(gridfs : TGridFS; remoteName : string; contentType : string); overload;
+ { Write data to this TGridfileWriter. p is the address of the data and length
+ is its size. Multiple calls to write() may be made to append successive
+ data. }
procedure write(p : Pointer; length : Int64);
+ { Finish with this TGridfileWriter. Flushes any data remaining to be written
+ to a chunk and posts the 'directory' information of the gridfile to the
+ GridFS. Returns True if successful; otherwise, False. }
function finish() : Boolean;
+ { Destroy this TGridfileWriter. Calls finish() if necessary and releases
+ external resources. }
destructor Destroy(); override;
end;
@@ -263,7 +368,7 @@ implementation
begin
Result := Int64ToDouble(gridfile_get_uploaddate(handle)) / (1000 * 24 * 60 * 60) + 25569;
end;
-
+
function TGridfile.getMD5() : string;
begin
Result := string(gridfile_get_md5(handle));
@@ -290,7 +395,7 @@ implementation
begin
Result := gridfile_get_numchunks(handle);
end;
-
+
function TGridfile.getDescriptor() : TBson;
var
b : Pointer;
@@ -338,5 +443,5 @@ implementation
Result := gridfile_seek(handle, offset);
end;
-
+
end.

0 comments on commit b15f42a

Please sign in to comment.