doc GridFS

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.