Object
GridIO objects represent files in the GridFS specification. This class manages the reading and writing of file chunks and metadata.
Create a new GridIO object. Note that most users will not need to use this class directly; the Grid and GridFileSystem classes will instantiate this class
@param [Mongo::Collection] files a collection for storing file metadata. @param [Mongo::Collection] chunks a collection for storing file chunks. @param [String] filename the name of the file to open or write. @param [String] mode 'r' or 'w' or reading or creating a file.
@option opts [Hash] :query a query selector used when opening the file in 'r' mode. @option opts [Hash] :query_opts any query options to be used when opening the file in 'r' mode. @option opts [String] :fs_name the file system prefix. @option opts [Integer] (262144) :chunk_size size of file chunks in bytes. @option opts [Hash] :metadata ({}) any additional data to store with the file. @option opts [ObjectId] :_id (ObjectId) a unique id for
the file to be use in lieu of an automatically generated one.
@option opts [String] :content_type ('binary/octet-stream') If no content type is specified,
the content type will may be inferred from the filename extension if the mime-types gem can be loaded. Otherwise, the content type 'binary/octet-stream' will be used.
@option opts [String, Integer, Symbol] :w (1) Set the write concern
Notes on write concern: When :w > 0, the chunks sent to the server will be validated using an md5 hash. If validation fails, an exception will be raised.
# File lib/mongo/gridfs/grid_io.rb, line 57 def initialize(files, chunks, filename, mode, opts={}) @files = files @chunks = chunks @filename = filename @mode = mode opts = opts.dup @query = opts.delete(:query) || {} @query_opts = opts.delete(:query_opts) || {} @fs_name = opts.delete(:fs_name) || Grid::DEFAULT_FS_NAME @write_concern = get_write_concern(opts) @local_md5 = Digest::MD5.new if Mongo::WriteConcern.gle?(@write_concern) @custom_attrs = {} case @mode when 'r' then init_read when 'w' then init_write(opts) else raise GridError, "Invalid file mode #{@mode}. Mode should be 'r' or 'w'." end end
# File lib/mongo/gridfs/grid_io.rb, line 78 def [](key) @custom_attrs[key] || instance_variable_get("@#{key.to_s}") end
# File lib/mongo/gridfs/grid_io.rb, line 82 def []=(key, value) if PROTECTED_ATTRS.include?(key.to_sym) warn "Attempting to overwrite protected value." return nil else @custom_attrs[key] = value end end
Creates or updates the document from the files collection that stores the chunks' metadata. The file becomes available only after this method has been called.
This method will be invoked automatically when on GridIO#open is passed a block. Otherwise, it must be called manually.
@return [BSON::ObjectId]
# File lib/mongo/gridfs/grid_io.rb, line 236 def close if @mode[0] == ww if @current_chunk['n'].zero? && @chunk_position.zero? warn "Warning: Storing a file with zero length." end @upload_date = Time.now.utc id = @files.insert(to_mongo_object) end id end
Read a chunk of the data from the file and yield it to the given block.
Note that this method reads from the current file position.
@yield Yields on chunk per iteration as defined by this file's
chunk size.
@return [Mongo::GridIO] self
# File lib/mongo/gridfs/grid_io.rb, line 256 def each return read_all unless block_given? while chunk = read(chunk_size) yield chunk break if chunk.empty? end self end
Return a boolean indicating whether the position pointer is at the end of the file.
@return [Boolean]
# File lib/mongo/gridfs/grid_io.rb, line 190 def eof raise GridError, "file not opened for read #{@mode}" unless @mode[0] == rr @file_position >= @file_length end
Return the next byte from the GridFS file.
@return [String]
# File lib/mongo/gridfs/grid_io.rb, line 224 def getc read_length(1) end
Return the next line from a GridFS file. This probably makes sense only if you're storing plain text. This method has a somewhat tricky API, which it inherits from Ruby's StringIO#gets.
@param [String, Integer] separator or length. If a separator,
read up to the separator. If a length, read the +length+ number of bytes. If nil, read the entire file.
@param [Integer] length If a separator is provided, then
read until either finding the separator or passing over the +length+ number of bytes.
@return [String]
# File lib/mongo/gridfs/grid_io.rb, line 209 def gets(separator="\n", length=nil) if separator.nil? read_all elsif separator.is_a?(Integer) read_length(separator) elsif separator.length > 1 read_to_string(separator, length) else read_to_character(separator, length) end end
# File lib/mongo/gridfs/grid_io.rb, line 265 def inspect "#<GridIO _id: #{@files_id}>" end
Read the data from the file. If a length if specified, will read from the current file position.
@param [Integer] length
@return [String]
the data in the file
# File lib/mongo/gridfs/grid_io.rb, line 98 def read(length=nil) return '' if @file_length.zero? if length == 0 return '' elsif length.nil? && @file_position.zero? read_all else read_length(length) end end
Rewind the file. This is equivalent to seeking to the zeroth position.
@return [Integer] the position of the file after rewinding (always zero).
# File lib/mongo/gridfs/grid_io.rb, line 181 def rewind raise GridError, "file not opened for read" unless @mode[0] == rr seek(0) end
Position the file pointer at the provided location.
@param [Integer] pos
the number of bytes to advance the file pointer. this can be a negative number.
@param [Integer] whence
one of IO::SEEK_CUR, IO::SEEK_END, or IO::SEEK_SET
@return [Integer] the new file position
# File lib/mongo/gridfs/grid_io.rb, line 149 def seek(pos, whence=IO::SEEK_SET) raise GridError, "Seek is only allowed in read mode." unless @mode == 'r' target_pos = case whence when IO::SEEK_CUR @file_position + pos when IO::SEEK_END @file_length + pos when IO::SEEK_SET pos end new_chunk_number = (target_pos / @chunk_size).to_i if new_chunk_number != @current_chunk['n'] save_chunk(@current_chunk) if @mode[0] == ww @current_chunk = get_chunk(new_chunk_number) end @file_position = target_pos @chunk_position = @file_position % @chunk_size @file_position end
The current position of the file.
@return [Integer]
# File lib/mongo/gridfs/grid_io.rb, line 173 def tell @file_position end
Write the given string (binary) data to the file.
@param [String] string
the data to write
@return [Integer]
the number of bytes written.
# File lib/mongo/gridfs/grid_io.rb, line 117 def write(io) raise GridError, "file not opened for write" unless @mode[0] == ww if io.is_a? String if Mongo::WriteConcern.gle?(@write_concern) @local_md5.update(io) end write_string(io) else length = 0 if Mongo::WriteConcern.gle?(@write_concern) while(string = io.read(@chunk_size)) @local_md5.update(string) length += write_string(string) end else while(string = io.read(@chunk_size)) length += write_string(string) end end length end end
Generated with the Darkfish Rdoc Generator 2.