mongo 0.18.3 → 0.19

data/README.rdoc

@@ -9,15 +9,15 @@ Here's a quick code sample. See the MongoDB Ruby Tutorial
   require 'mongo'
   include Mongo
 
-  @db   = Connection.new.db('sample-db')
-  @coll = db.collection('test')
+  db   = Connection.new.db('sample-db')
+  coll = db.collection('test')
 
-  @coll.remove
+  coll.remove
   3.times do |i|
-    @coll.insert({'a' => i+1})
+    coll.insert({'a' => i+1})
   end
-  puts "There are #{@coll.count()} records. Here they are:"
-  @coll.find().each { |doc| puts doc.inspect }
+  puts "There are #{coll.count()} records. Here they are:"
+  coll.find().each { |doc| puts doc.inspect }
 
 = Installation
 
@@ -25,7 +25,6 @@ The driver's gems are hosted on Gemcutter[http://gemcutter.org]. If you haven't
 installed a gem from Gemcutter before, you'll need to set up Gemcutter first:
 
   $ gem install gemcutter
-  $ gem tumble
 
 Once you've installed Gemcutter, install the mongo gem as follows:
 
@@ -70,40 +69,51 @@ Here's how to start MongoDB and run the "simple.rb" example:
 
 See also the test code, especially test/test_db_api.rb.
 
-= GridStore
+= GridFS
 
-The GridStore class is a Ruby implementation of MongoDB's GridFS file storage
-system. An instance of GridStore is like an IO object. See the RDocs for
-details, and see examples/gridfs.rb for code that uses many of the GridStore
-features (metadata, content type, rewind/seek/tell, etc).
+Note: The GridStore class has been deprecated. Use either the Grid or GridFileSystem
+classes to take advantage of GridFS.
 
-Note that the GridStore class is not automatically required when you require
-'mongo'. You also need to require 'mongo/gridfs'
+The Ruby driver include two abstractions for storing large files: Grid and GridFileSystem.
+The Grid class is a Ruby implementation of MongoDB's GridFS file storage
+specification. GridFileSystem is essentailly the same, but provides a more filesystem-like API
+and assumes that filenames are unique.
 
-Example code:
+An instance of both classes represents an individual file store. See the API reference
+for details, and see examples/gridfs.rb for code that uses many of the Grid
+features (metadata, content type, seek, tell, etc).
 
-  include GridFS
+Examples:
+  include Mongo
+
+  # Get a database
+  db = Mongo::Connection.new.db('app-db')
 
-  # Store the text "Hello, world!" in the grid store.
-  GridStore.open(database, 'filename', 'w') do |f|
-    f.puts "Hello, world!"
+  # GridFileSystem. Store the text "Hello, world!" in the fs.
+  fs = GridFileSystem.new(db)
+  fs.open('filename', 'w') do |f|
+    f.write "Hello, world!"
   end
 
-  # Output "Hello, world!"
-  GridStore.open(database, 'filename', 'r') do |f|
+  # GridFileSystem. Output "Hello, world!"
+  fs = GridFileSystem.new(db)
+  fs.open('filename', 'r') do |f|
     puts f.read
   end
 
-  # Add text to the grid store.
-  GridStore.open(database, 'filename', 'w+') do |f|
-    f.puts "But wait, there's more!"
-  end
+  # Write a file on disk to the Grid
+  file = File.open('image.jpg')
+  grid = Grid.new(db)
+  id   = grid.put(file)
 
-  # Retrieve everything, outputting  "Hello, world!\nBut wait, there's more!\n"
-  GridStore.open(database, 'filename', 'r') do |f|
-    puts f.read
-  end
+  # Retrieve the file
+  file = grid.get(id)
+  file.read
 
+  # Get all the file's metata
+  file.filename
+  file.content_type
+  file.metadata
 
 = Notes
 
@@ -294,8 +304,7 @@ It's also possible to test replica pairs with connection pooling:
 
 ===Shoulda and Mocha
 
-All tests now require shoulda and mocha.  You can install these gems as
-follows:
+Running the test suite requires shoulda and mocha.  You can install them as follows:
 
   $ gem install shoulda
   $ gem install mocha
@@ -305,23 +314,6 @@ can override the default host (localhost) and port (Connection::DEFAULT_PORT) by
 using the environment variables MONGO_RUBY_DRIVER_HOST and
 MONGO_RUBY_DRIVER_PORT.
 
-The project mongo-qa (http://github.com/mongodb/mongo-qa) contains many more
-Mongo driver tests that are language independent. To run thoses tests as part
-of the "rake test" task, download the code "next to" this directory. So, after
-installing the mongo-qa code you would have these two directories next to each
-other:
-
-  $ ls
-  mongo-qa
-  mongo-ruby-driver
-  $ rake test
-
-The tests run just fine if the mongo-qa directory is not there.
-
-Additionally, the script bin/validate is used by the mongo-qa project's
-validator script.
-
-
 = Documentation
 
 This documentation is available online at http://api.mongodb.org/ruby. You can
@@ -342,7 +334,7 @@ See CREDITS.
 
 = License
 
- Copyright 2008-2009 10gen Inc.
+ Copyright 2008-2010 10gen Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -355,4 +347,3 @@ See CREDITS.
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-

data/Rakefile

@@ -47,7 +47,7 @@ namespace :test do
   end
 
   Rake::TestTask.new(:functional) do |t|
-    t.test_files = FileList['test/test*.rb']
+    t.test_files = FileList['test/*_test.rb']
     t.verbose    = true
   end
 
@@ -76,6 +76,16 @@ namespace :test do
     t.verbose    = true
   end
 
+  Rake::TestTask.new(:auto_reconnect) do |t|
+    t.test_files = FileList['test/auxillary/autoreconnect_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::TestTask.new(:authentication) do |t|
+    t.test_files = FileList['test/auxillary/authentication_test.rb']
+    t.verbose    = true
+  end
+
   task :drop_databases do |t|
     puts "Dropping test database..."
     require File.join(File.dirname(__FILE__), 'lib', 'mongo')
@@ -96,10 +106,10 @@ end
 
 desc "Generate YARD documentation"
 task :ydoc do
-  version = eval(File.read("mongo-ruby-driver.gemspec")).version
-  out = File.join('ydoc', version.to_s)
+  require File.join(File.dirname(__FILE__), 'lib', 'mongo')
+  out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
-  system "yardoc lib/**/*.rb lib/mongo/**/*.rb -o #{out} --title MongoRuby-#{version}"
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb -e docs/yard_ext.rb -p docs/templates -o #{out} --title MongoRuby-#{Mongo::VERSION}"
 end
 
 desc "Publish documentation to mongo.rubyforge.org"

data/examples/gridfs.rb

@@ -1,10 +1,10 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+def assert
+  raise "Failed!" unless yield
+end
 
 require 'mongo'
-require 'mongo/gridfs'
-
 include Mongo
-include GridFS
 
 host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
 port = ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
@@ -12,77 +12,32 @@ port = ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
 puts "Connecting to #{host}:#{port}"
 db = Connection.new(host, port).db('ruby-mongo-examples')
 
-def dump(db, fname)
-  GridStore.open(db, fname, 'r') { |f| puts f.read }
-end
-
-# Write a new file
-GridStore.open(db, 'foobar', 'w') { |f| f.write("hello, world!") }
-
-# Read it and print out the contents
-dump(db, 'foobar')
-
-# Append more data
-GridStore.open(db, 'foobar', 'w+') { |f| f.write("\n"); f.puts "line two" }
-dump(db, 'foobar')
+data = "hello, world!"
 
-# Overwrite
-GridStore.open(db, 'foobar', 'w') { |f| f.puts "hello, sailor!" }
-dump(db, 'foobar')
+grid = Grid.new(db)
 
-# File existence tests
-puts "File 'foobar' exists: #{GridStore.exist?(db, 'foobar')}"
-puts "File 'does-not-exist' exists: #{GridStore.exist?(db, 'does-not-exist')}"
+# Write a new file. data can be a string or an io object responding to #read.
+id = grid.put(data, 'hello.txt')
 
-# Read with offset (uses seek)
-puts GridStore.read(db, 'foobar', 6, 7)
+# Read it and print out the contents
+file = grid.get(id)
+puts file.read
 
-# Rewind/seek/tell
-GridStore.open(db, 'foobar', 'w') { |f|
-  f.write "hello, world!"
-  f.rewind
-  f.write "xyzzz"
-  puts f.tell                   # => 5
-  f.seek(4)
-  f.write('y')
-}
-dump(db, 'foobar')              # => 'xyzzy'
+# Delete the file
+grid.delete(id)
 
-# Unlink (delete)
-GridStore.unlink(db, 'foobar')
-puts "File 'foobar' exists after delete: #{GridStore.exist?(db, 'foobar')}"
+begin
+grid.get(id)
+rescue => e
+  assert {e.class == Mongo::GridError}
+end
 
 # Metadata
-GridStore.open(db, 'foobar', 'w') { |f| f.write("hello, world!") }
-GridStore.open(db, 'foobar', 'r') { |f|
-  puts f.content_type
-  puts f.upload_date
-  puts f.chunk_size
-  puts f.metadata.inspect
-}
-
-# Add some metadata; change content type
-GridStore.open(db, 'foobar', 'w+') { |f|
-  f.content_type = 'text/xml'
-  f.metadata = {'a' => 1}
-}
-# Print it
-GridStore.open(db, 'foobar', 'r') { |f|
-  puts f.content_type
-  puts f.upload_date
-  puts f.chunk_size
-  puts f.metadata.inspect
-}
-
-# You can also set metadata when initially writing the file. Setting :root
-# means that the file and its chunks are stored in a different root
-# collection: instead of gridfs.files and gridfs.chunks, here we use
-# my_files.files and my_files.chunks.
-GridStore.open(db, 'foobar', 'w',
-               :content_type => 'text/plain',
-               :metadata => {'a' => 1},
-               :chunk_size => 1024 * 4,
-               :root => 'my_files') { |f|
-  f.puts 'hello, world'
-}
-
+id = grid.put(data, 'hello.txt', :content_type => 'text/plain', :metadata => {'name' => 'hello'})
+file = grid.get(id)
+
+p file.content_type
+p file.metadata.inspect
+p file.chunk_size
+p file.file_length
+p file.data

data/lib/mongo.rb

@@ -1,7 +1,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  VERSION = "0.18.3"
+  VERSION = "0.19"
 end
 
 begin
@@ -52,10 +52,12 @@ require 'mongo/util/conversions'
 require 'mongo/util/server_version'
 require 'mongo/util/bson_ruby'
 
-require 'mongo/admin'
 require 'mongo/collection'
 require 'mongo/connection'
 require 'mongo/cursor'
 require 'mongo/db'
 require 'mongo/exceptions'
 require 'mongo/gridfs'
+require 'mongo/gridfs/grid'
+require 'mongo/gridfs/grid_io'
+require 'mongo/gridfs/grid_file_system'

data/lib/mongo/collection.rb

@@ -1,5 +1,5 @@
 # --
-# Copyright (C) 2008-2009 10gen Inc.
+# Copyright (C) 2008-2010 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -33,6 +33,8 @@ module Mongo
     #   if collection name is not a string or symbol
     #
     # @return [Collection]
+    #
+    # @core collections constructor_details
     def initialize(db, name, pk_factory=nil)
       case name
       when Symbol, String
@@ -126,6 +128,8 @@ module Mongo
     #
     # @raise [RuntimeError]
     #   if given unknown options
+    #
+    # @core find find-instance_method
     def find(selector={}, opts={})
       fields = opts.delete(:fields)
       fields = ["_id"] if fields && fields.empty?
@@ -221,6 +225,8 @@ module Mongo
     #   If true, check that the save succeeded. OperationFailure
     #   will be raised on an error. Note that a safe check requires an extra
     #   round-trip to the database.
+    #
+    # @core insert insert-instance_method
     def insert(doc_or_docs, options={})
       doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array)
       doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
@@ -248,15 +254,17 @@ module Mongo
     #
     # @raise [Mongo::OperationFailure] an exception will be raised iff safe mode is enabled
     #   and the operation fails.
+    #
+    # @core remove remove-instance_method
     def remove(selector={}, opts={})
       # Initial byte is 0.
       message = ByteBuffer.new([0, 0, 0, 0])
       BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       message.put_int(0)
-      message.put_array(BSON.serialize(selector, false).to_a)
+      message.put_array(BSON.serialize(selector, false, true).to_a)
 
       if opts[:safe]
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message,
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name,
           "db.#{@db.name}.remove(#{selector.inspect})")
         # the return value of send_message_with_safe_check isn't actually meaningful --
         # only the fact that it didn't raise an error is -- so just return true
@@ -285,6 +293,8 @@ module Mongo
     #   If true, check that the save succeeded. OperationFailure
     #   will be raised on an error. Note that a safe check requires an extra
     #   round-trip to the database.
+    #
+    # @core update update-instance_method
     def update(selector, document, options={})
       # Initial byte is 0.
       message = ByteBuffer.new([0, 0, 0, 0])
@@ -293,8 +303,8 @@ module Mongo
       update_options += 1 if options[:upsert]
       update_options += 2 if options[:multi]
       message.put_int(update_options)
-      message.put_array(BSON.serialize(selector, false).to_a)
-      message.put_array(BSON.serialize(document, false).to_a)
+      message.put_array(BSON.serialize(selector, false, true).to_a)
+      message.put_array(BSON.serialize(document, false, true).to_a)
       if options[:safe]
         @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name,
           "db.#{@name}.update(#{selector.inspect}, #{document.inspect})")
@@ -313,6 +323,8 @@ module Mongo
     # @param [Boolean] unique if true, this index will enforce a uniqueness constraint.
     #
     # @return [String] the name of the index created.
+    #
+    # @core indexes create_index-instance_method
     def create_index(field_or_spec, unique=false)
       field_h = OrderedHash.new
       if field_or_spec.is_a?(String) || field_or_spec.is_a?(Symbol)
@@ -326,18 +338,26 @@ module Mongo
         :ns     => "#{@db.name}.#{@name}",
         :key    => field_h,
         :unique => unique }
-      insert_documents([sel], Mongo::DB::SYSTEM_INDEX_COLLECTION, false)
+      begin
+        insert_documents([sel], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
+      rescue Mongo::OperationFailure
+        raise Mongo::OperationFailure, "Failed to create index #{sel.inspect}."
+      end
       name
     end
 
     # Drop a specified index.
     #
     # @param [String] name
+    #
+    # @core indexes
     def drop_index(name)
       @db.drop_index(@name, name)
     end
 
     # Drop all indexes.
+    #
+    # @core indexes
     def drop_indexes
 
       # Note: calling drop_indexes with no args will drop them all.
@@ -369,6 +389,8 @@ module Mongo
     # @return [Collection] a collection containing the results of the operation.
     #
     # @see http://www.mongodb.org/display/DOCS/MapReduce Offical MongoDB map/reduce documentation.
+    #
+    # @core mapreduce map_reduce-instance_method
     def map_reduce(map, reduce, opts={})
       map    = Code.new(map) unless map.is_a?(Code)
       reduce = Code.new(reduce) unless reduce.is_a?(Code)
@@ -397,100 +419,57 @@ module Mongo
     # @param [String, Code] finalize :: optional. a JavaScript function that receives and modifies
     #              each of the resultant grouped objects. Available only when group is run
     #              with command set to true.
-    # @param [Boolean] command if true, run the group as a command instead of in an
-    #   eval. Note: Running group as eval has been DEPRECATED.
+    # @param [Nil] deprecated this param in a placeholder for a deprecated param. It will be removed
+    #   in the next release.
     #
     # @return [Array] the grouped items.
-    def group(key, condition, initial, reduce, command=false, finalize=nil)
+    def group(key, condition, initial, reduce, finalize=nil, deprecated=nil)
 
-      if command
+      # Warn of changed API post eval deprecation.
+      if finalize == true || finalize == false || deprecated
+        warn "The API for Collection#group has changed. 'Finalize' is now the fifth parameter, " +
+          "since it's no longer necessary to specify whether #group is run as a command. " +
+          "See http://api.mongodb.org/ruby/current/Mongo/Collection.html#group-instance_method for details."
+      end
 
-        reduce = Code.new(reduce) unless reduce.is_a?(Code)
+      reduce = Code.new(reduce) unless reduce.is_a?(Code)
 
-        group_command = {
-          "group" => {
-            "ns"      => @name,
-            "$reduce" => reduce,
-            "cond"    => condition,
-            "initial" => initial
-          }
+      group_command = {
+        "group" => {
+          "ns"      => @name,
+          "$reduce" => reduce,
+          "cond"    => condition,
+          "initial" => initial
         }
+      }
 
-        unless key.nil?
-          if key.is_a? Array
-            key_type = "key"
-            key_value = {}
-            key.each { |k| key_value[k] = 1 }
-          else
-            key_type  = "$keyf"
-            key_value = key.is_a?(Code) ? key : Code.new(key)
-          end
-
-          group_command["group"][key_type] = key_value
-        end
-
-        # only add finalize if specified
-        if finalize
-          finalize = Code.new(finalize) unless finalize.is_a?(Code)
-          group_command['group']['finalize'] = finalize
-        end
-
-        result = @db.command group_command
-
-        if result["ok"] == 1
-          return result["retval"]
+      unless key.nil?
+        if key.is_a? Array
+          key_type = "key"
+          key_value = {}
+          key.each { |k| key_value[k] = 1 }
         else
-          raise OperationFailure, "group command failed: #{result['errmsg']}"
+          key_type  = "$keyf"
+          key_value = key.is_a?(Code) ? key : Code.new(key)
         end
 
-      else
-
-        warn "Collection#group must now be run as a command; you can do this by passing 'true' as the command argument."
-
-        raise OperationFailure, ":finalize can be specified only when " +
-          "group is run as a command (set command param to true)" if finalize
+        group_command["group"][key_type] = key_value
+      end
 
-        raise OperationFailure, "key must be an array of fields to group by. If you want to pass a key function, 
-          run group as a command by passing 'true' as the command argument." unless key.is_a? Array || key.nil?
+      # only add finalize if specified
+      # check to see if users have sent the finalizer as the last argument.
+      finalize = deprecated if deprecated.is_a?(String) || deprecated.is_a?(Code)
+      finalize = Code.new(finalize) if finalize.is_a?(String)
+      if finalize.is_a?(Code)
+        group_command['group']['finalize'] = finalize
+      end
 
-        case reduce
-        when Code
-          scope = reduce.scope
-        else
-          scope = {}
-        end
-        scope.merge!({
-                       "ns" => @name,
-                       "keys" => key,
-                       "condition" => condition,
-                       "initial" => initial })
-
-      group_function = <<EOS
-function () {
-    var c = db[ns].find(condition);
-    var map = new Map();
-    var reduce_function = #{reduce};
-    while (c.hasNext()) {
-        var obj = c.next();
-
-        var key = {};
-        for (var i = 0; i < keys.length; i++) {
-            var k = keys[i];
-            key[k] = obj[k];
-        }
+      result = @db.command group_command
 
-        var aggObj = map.get(key);
-        if (aggObj == null) {
-            var newObj = Object.extend({}, key);
-            aggObj = Object.extend(newObj, initial);
-            map.put(key, aggObj);
-        }
-        reduce_function(obj, aggObj);
-    }
-    return {"result": map.values()};
-}
-EOS
-        @db.eval(Code.new(group_function, scope))["result"]
+      if result["ok"] == 1
+        result["retval"]
+      else
+        raise OperationFailure, "group command failed: #{result['errmsg']}"
       end
     end
 
@@ -534,7 +513,7 @@ EOS
     # Note: If operating in auth mode, the client must be authorized as an admin to
     # perform this operation. 
     #
-    # @param [String ] new_name the new name for this collection
+    # @param [String] new_name the new name for this collection
     #
     # @raise [InvalidName] if +new_name+ is an invalid collection name.
     def rename(new_name)
@@ -562,6 +541,8 @@ EOS
     # Get information on the indexes for this collection.
     #
     # @return [Hash] a hash where the keys are index names.
+    #
+    # @core indexes
     def index_information
       @db.index_information(@name)
     end
@@ -609,7 +590,7 @@ EOS
       # Initial byte is 0.
       message = ByteBuffer.new([0, 0, 0, 0])
       BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{collection_name}")
-      documents.each { |doc| message.put_array(BSON.serialize(doc, check_keys).to_a) }
+      documents.each { |doc| message.put_array(BSON.serialize(doc, check_keys, true).to_a) }
       if safe
         @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name,
           "db.#{collection_name}.insert(#{documents.inspect})")