From e4f8a61cac098caf5a2ff0a87510708d72030674 Mon Sep 17 00:00:00 2001 From: Kyle Banker Date: Tue, 23 Feb 2010 17:40:02 -0500 Subject: [PATCH] GridFS docs --- lib/mongo/gridfs/grid.rb | 23 +++++++++++++++- lib/mongo/gridfs/grid_file_system.rb | 41 +++++++++++++++++++++++++++- lib/mongo/gridfs/grid_io.rb | 11 +++++++- lib/mongo/gridfs/grid_store.rb | 1 - 4 files changed, 72 insertions(+), 4 deletions(-) diff --git a/lib/mongo/gridfs/grid.rb b/lib/mongo/gridfs/grid.rb index b3636b9..bc49acf 100644 --- a/lib/mongo/gridfs/grid.rb +++ b/lib/mongo/gridfs/grid.rb @@ -16,10 +16,15 @@ module Mongo - # WARNING: This class is part of a new, experimental GridFS API. Subject to change. + # Implements the basic MongoDB GridFS specification. class Grid 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) 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]]) 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={}) opts.merge!(default_grid_io_opts) file = GridIO.new(@files, @chunks, filename, 'w', opts=opts) @@ -39,11 +50,21 @@ module Mongo file.files_id end + # Read a file from the file store. + # + # @param [] id the file's unique id. + # + # @return [Mongo::GridIO] def get(id) opts = {:query => {'_id' => id}}.merge!(default_grid_io_opts) GridIO.new(@files, @chunks, nil, 'r', opts) end + # Delete a file from the store. + # + # @param [] id + # + # @return [Boolean] def delete(id) @files.remove({"_id" => id}) @chunks.remove({"_id" => id}) diff --git a/lib/mongo/gridfs/grid_file_system.rb b/lib/mongo/gridfs/grid_file_system.rb index ede3d74..dfdca8c 100644 --- a/lib/mongo/gridfs/grid_file_system.rb +++ b/lib/mongo/gridfs/grid_file_system.rb @@ -16,9 +16,16 @@ 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 + # 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) 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} 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={}) opts.merge!(default_grid_io_opts(filename)) file = GridIO.new(@files, @chunks, filename, mode, opts) @@ -44,6 +77,12 @@ module Mongo result 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) files = @files.find({'filename' => filename}, :fields => ['_id']) files.each do |file| diff --git a/lib/mongo/gridfs/grid_io.rb b/lib/mongo/gridfs/grid_io.rb index ce3146b..ea25ace 100644 --- a/lib/mongo/gridfs/grid_io.rb +++ b/lib/mongo/gridfs/grid_io.rb @@ -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_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={}) @files = files @chunks = chunks diff --git a/lib/mongo/gridfs/grid_store.rb b/lib/mongo/gridfs/grid_store.rb index dbe3af7..fa9730f 100644 --- a/lib/mongo/gridfs/grid_store.rb +++ b/lib/mongo/gridfs/grid_store.rb @@ -47,7 +47,6 @@ module GridFS # puts f.read # end # - # @core gridfs # @deprecated class GridStore include Enumerable