GridFS docs

This commit is contained in:
Kyle Banker 2010-02-23 17:40:02 -05:00
parent d40767bdd4
commit e4f8a61cac
4 changed files with 72 additions and 4 deletions

View File

@ -16,10 +16,15 @@
module Mongo module Mongo
# WARNING: This class is part of a new, experimental GridFS API. Subject to change. # Implements the basic MongoDB GridFS specification.
class Grid class Grid
DEFAULT_FS_NAME = 'fs' DEFAULT_FS_NAME = 'fs'
# Initialize a new Grid instance, consisting of a MongoDB database
# and a filesystem prefix if not using the default.
#
# @core gridfs
# @see GridFileSystem
def initialize(db, fs_name=DEFAULT_FS_NAME) def initialize(db, fs_name=DEFAULT_FS_NAME)
raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB) raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB)
@ -31,6 +36,12 @@ module Mongo
@chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]]) @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]])
end end
# Store a file in the file store.
#
# @param [String, #read] data a string or io-like object to store.
# @param [String] filename a name for the file.
#
# @return [Mongo::ObjectID] the file's id.
def put(data, filename, opts={}) def put(data, filename, opts={})
opts.merge!(default_grid_io_opts) opts.merge!(default_grid_io_opts)
file = GridIO.new(@files, @chunks, filename, 'w', opts=opts) file = GridIO.new(@files, @chunks, filename, 'w', opts=opts)
@ -39,11 +50,21 @@ module Mongo
file.files_id file.files_id
end end
# Read a file from the file store.
#
# @param [] id the file's unique id.
#
# @return [Mongo::GridIO]
def get(id) def get(id)
opts = {:query => {'_id' => id}}.merge!(default_grid_io_opts) opts = {:query => {'_id' => id}}.merge!(default_grid_io_opts)
GridIO.new(@files, @chunks, nil, 'r', opts) GridIO.new(@files, @chunks, nil, 'r', opts)
end end
# Delete a file from the store.
#
# @param [] id
#
# @return [Boolean]
def delete(id) def delete(id)
@files.remove({"_id" => id}) @files.remove({"_id" => id})
@chunks.remove({"_id" => id}) @chunks.remove({"_id" => id})

View File

@ -16,9 +16,16 @@
module Mongo module Mongo
# WARNING: This class is part of a new, experimental GridFS API. Subject to change. # A file store built on the GridFS specification featuring
# an API and behavior similar to that of a traditional file system.
class GridFileSystem < Grid class GridFileSystem < Grid
# Initialize a new Grid instance, consisting of a MongoDB database
# and a filesystem prefix if not using the default.
#
# @param [Mongo::DB] db a MongoDB database.
# @param [String] fs_name A name for the file system. The default name, based on
# the specification, is 'fs'.
def initialize(db, fs_name=Grid::DEFAULT_FS_NAME) def initialize(db, fs_name=Grid::DEFAULT_FS_NAME)
raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB) raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB)
@ -31,6 +38,32 @@ module Mongo
@default_query_opts = {:sort => [['filename', 1], ['uploadDate', -1]], :limit => 1} @default_query_opts = {:sort => [['filename', 1], ['uploadDate', -1]], :limit => 1}
end end
# Open a file for reading or writing.
#
# @param [String] filename the name of the file.
# @param [String] mode either 'r' or 'w' for reading from
# or writing to the file.
#
# @example
#
# # Store the text "Hello, world!" in the grid file system.
# @grid = GridFileSystem.new(@db)
# @grid.open('filename', 'w') do |f|
# f.write "Hello, world!"
# end
#
# # Output "Hello, world!"
# @grid = GridFileSystem.new(@db)
# @grid.open('filename', 'r') do |f|
# puts f.read
# end
#
# # Write a file on disk to the GridFileSystem
# @file = File.open('image.jpg')
# @grid = GridFileSystem.new(@db)
# @grid.open('image.jpg, 'w') do |f|
# f.write @file
# end
def open(filename, mode, opts={}) def open(filename, mode, opts={})
opts.merge!(default_grid_io_opts(filename)) opts.merge!(default_grid_io_opts(filename))
file = GridIO.new(@files, @chunks, filename, mode, opts) file = GridIO.new(@files, @chunks, filename, mode, opts)
@ -44,6 +77,12 @@ module Mongo
result result
end end
# Delete the file with the given filename. Note that this will delete
# all versions of the file.
#
# @param [String] filename
#
# @return [Boolean]
def delete(filename) def delete(filename)
files = @files.find({'filename' => filename}, :fields => ['_id']) files = @files.find({'filename' => filename}, :fields => ['_id'])
files.each do |file| files.each do |file|

View File

@ -37,7 +37,16 @@ module Mongo
# #
# @option opts [Hash] :query a query selector used when opening the file in 'r' mode. # @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 [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. Defaults to 'fs' # @option opts [String] :fs_name the file system prefix.
# @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
# @options opts [Hash] :metadata ({}) any additional data to store with the file.
# @options opts [ObjectID] :_id (ObjectID) a unique id for
# the file to be use in lieu of an automatically generated one.
# @options opts [String] :content_type ('binary/octet-stream') If no content type is specified,
# the content type will be inferred from the filename extension. If that can't be done, the default
# content type of 'binary/octet-stream' will be used.
# @options opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
# will be validated using an md5 hash. If validation fails, an exception will be raised.
def initialize(files, chunks, filename, mode, opts={}) def initialize(files, chunks, filename, mode, opts={})
@files = files @files = files
@chunks = chunks @chunks = chunks

View File

@ -47,7 +47,6 @@ module GridFS
# puts f.read # puts f.read
# end # end
# #
# @core gridfs
# @deprecated # @deprecated
class GridStore class GridStore
include Enumerable include Enumerable