mongo 0.20.1 → 1.0

data/README.rdoc

@@ -35,7 +35,6 @@ The driver also requires the BSON gem:
   $ gem install bson
 
 And for a significant performance boost, you'll want to install the C extensions:
-extensions:
 
   $ gem install bson_ext
 

data/examples/admin.rb

@@ -9,13 +9,14 @@ host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
 port = ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
 
 puts "Connecting to #{host}:#{port}"
-db = Mongo::Connection.new(host, port).db('ruby-mongo-examples')
+con  = Mongo::Connection.new(host, port)
+db   = con.db('ruby-mongo-examples')
 coll = db.create_collection('test')
 
 # Erase all records from collection, if any
 coll.remove
 
-admin = db.admin
+admin = con['admin']
 
 # Profiling level set/get
 puts "Profiling level: #{admin.profiling_level}"
@@ -34,7 +35,7 @@ pp admin.profiling_info
 
 # Validate returns a hash if all is well and
 # raises an exception if there is a problem.
-info = admin.validate_collection(coll.name)
+info = db.validate_collection(coll.name)
 puts "valid = #{info['ok']}"
 puts info['result']
 

data/examples/info.rb

@@ -24,7 +24,7 @@ p db.collection_names
 p db.collections_info
 
 # Index information
-db.create_index('test', 'a')
+coll.create_index('a')
 p db.index_information('test')
 
 # Destroy the collection

data/lib/mongo.rb

@@ -1,7 +1,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  VERSION = "0.20.1"
+  VERSION = "1.0"
 end
 
 module Mongo
@@ -19,8 +19,11 @@ module Mongo
     OP_DELETE       = 2006
     OP_KILL_CURSORS = 2007
 
+    OP_QUERY_TAILABLE          = 2
     OP_QUERY_SLAVE_OK          = 4
     OP_QUERY_NO_CURSOR_TIMEOUT = 16
+
+    DEFAULT_BATCH_SIZE = 100
   end
 
 end

data/lib/mongo/collection.rb

@@ -120,6 +120,8 @@ module Mongo
     # @option opts [Boolean] :snapshot ('false') if true, snapshot mode will be used for this query.
     #   Snapshot mode assures no duplicates are returned, or objects missed, which were preset at both the start and
     #   end of the query's execution. For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
+    # @option opts [Boolean] :batch_size (100) the number of documents to returned by the database per GETMORE operation. A value of 0
+    #   will let the database server decide how many results to returns. This option can be ignored for most use cases.
     # @option opts [Boolean] :timeout ('true') when +true+, the returned cursor will be subject to
     #   the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
     #   that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
@@ -140,6 +142,7 @@ module Mongo
       sort   = opts.delete(:sort)
       hint   = opts.delete(:hint)
       snapshot = opts.delete(:snapshot)
+      batch_size = opts.delete(:batch_size)
       if opts[:timeout] == false && !block_given?
         raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block."
       end
@@ -152,7 +155,7 @@ module Mongo
       raise RuntimeError, "Unknown options [#{opts.inspect}]" unless opts.empty?
 
       cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit,
-                          :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout)
+                          :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout, :batch_size => batch_size)
       if block_given?
         yield cursor
         cursor.close()
@@ -330,9 +333,6 @@ module Mongo
     #   Also note that it is permissible to create compound indexes that include a geospatial index as
     #   long as the geospatial index comes first.
     #
-    # @param [Boolean] unique if true, this index will enforce a uniqueness constraint. DEPRECATED. Future
-    #   versions of this driver will specify the uniqueness constraint using a hash param.
-    #
     # @option opts [Boolean] :unique (false) if true, this index will enforce a uniqueness constraint.
     # @option opts [Boolean] :background (false) indicate that the index should be built in the background. This
     #   feature is only available in MongoDB >= 1.3.2.
@@ -359,32 +359,36 @@ module Mongo
     #
     # @core indexes create_index-instance_method
     def create_index(spec, opts={})
-      opts.assert_valid_keys(:min, :max, :background, :unique, :dropDups) if opts.is_a?(Hash)
+      opts.assert_valid_keys(:min, :max, :background, :unique, :dropDups)
       field_spec = OrderedHash.new
       if spec.is_a?(String) || spec.is_a?(Symbol)
         field_spec[spec.to_s] = 1
       elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
-        spec.each { |f| field_spec[f[0].to_s] = f[1] }
+        spec.each do |f|
+          if [Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D].include?(f[1])
+            field_spec[f[0].to_s] = f[1]
+          else
+            raise MongoArgumentError, "Invalid index field #{f[1].inspect}; " + 
+              "should be one of Mongo::ASCENDING (1), Mongo::DESCENDING (-1) or Mongo::GEO2D ('2d')."
+          end
+        end
       else
         raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " + 
           "should be either a string, symbol, or an array of arrays."
       end
 
       name = generate_index_name(field_spec)
-      if opts == true || opts == false
-        warn "For Collection#create_index, the method for specifying a unique index has changed." +
-          "Please pass :unique => true to the method instead."
-      end
-      sel  = {
+
+      selector = {
         :name   => name,
         :ns     => "#{@db.name}.#{@name}",
-        :key    => field_spec,
-        :unique => (opts == true ? true : false) }
-      sel.merge!(opts) if opts.is_a?(Hash)
+        :key    => field_spec
+      }
+      selector.merge!(opts)
       begin
-        response = insert_documents([sel], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
+        response = insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
       rescue Mongo::OperationFailure
-        raise Mongo::OperationFailure, "Failed to create index #{sel.inspect} with the following errors: #{response}"
+        raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following errors: #{response}"
       end
       name
     end

data/lib/mongo/connection.rb

@@ -118,11 +118,11 @@ module Mongo
     # @param opts Takes the same options as Connection.new
     #
     # @example
-    #   Connection.new([["db1.example.com", 27017],
+    #   Connection.paired([["db1.example.com", 27017],
     #                   ["db2.example.com", 27017]])
     #
     # @example
-    #   Connection.new([["db1.example.com", 27017],
+    #   Connection.paired([["db1.example.com", 27017],
     #                   ["db2.example.com", 27017]],
     #                   :pool_size => 20, :timeout => 5)
     #

data/lib/mongo/cursor.rb

@@ -47,6 +47,8 @@ module Mongo
       @timeout    = options[:timeout]  || false
       @explain    = options[:explain]
       @socket     = options[:socket]
+      @tailable   = options[:tailable] || false
+      @batch_size = options[:batch_size] || Mongo::Constants::DEFAULT_BATCH_SIZE
 
       @full_collection_name = "#{@collection.db.name}.#{@collection.name}"
       @cache = []
@@ -250,7 +252,8 @@ module Mongo
     def query_opts
       timeout  = @timeout ? 0 : Mongo::Constants::OP_QUERY_NO_CURSOR_TIMEOUT
       slave_ok = @connection.slave_ok? ? Mongo::Constants::OP_QUERY_SLAVE_OK : 0
-      slave_ok + timeout
+      tailable = @tailable ? Mongo::Constants::OP_QUERY_TAILABLE : 0
+      slave_ok + timeout + tailable
     end
 
     # Get the query options for this Cursor.
@@ -317,8 +320,8 @@ module Mongo
       db_name = @admin ? 'admin' : @db.name
       BSON::BSON_RUBY.serialize_cstr(message, "#{db_name}.#{@collection.name}")
 
-      # Number of results to return; db decides for now.
-      message.put_int(100)
+      # Number of results to return.
+      message.put_int(@batch_size)
 
       # Cursor id.
       message.put_long(@cursor_id)

data/lib/mongo/db.rb

@@ -404,8 +404,11 @@ module Mongo
     # @param [Boolean] unique if +true+, the created index will enforce a uniqueness constraint.
     #
     # @return [String] the name of the index created.
+    #
+    # @deprecated
     def create_index(collection_name, field_or_spec, unique=false)
-      self.collection(collection_name).create_index(field_or_spec, unique)
+      warn "DB#create_index is now deprecated. Please use Collection#create_index instead."
+      self.collection(collection_name).create_index(field_or_spec, :unique => unique)
     end
 
     # Return +true+ if the supplied +doc+ contains an 'ok' field with the value 1.

data/lib/mongo/gridfs/grid.rb

@@ -39,6 +39,9 @@ module Mongo
 
     # Store a file in the file store.
     #
+    # Note that arbitary metadata attributes can be saved to the file by passing
+    # them is as options.
+    #
     # @param [String, #read] data a string or io-like object to store.
     #
     # @options opts [String] :filename (nil) a name for the file.
@@ -53,14 +56,8 @@ module Mongo
     #   will be validated using an md5 hash. If validation fails, an exception will be raised.
     #
     # @return [Mongo::ObjectID] the file's id.
-    def put(data, opts={}, old_opts={})
-      if opts.is_a?(String)
-        warn "The filename is now optional. Please pass the filename as a hash option: Grid#put(data, :filename => 'file.jpg')."
-        filename = opts
-        opts     = old_opts
-      else
-        filename = opts[:filename]
-      end
+    def put(data, opts={})
+      filename = opts[:filename]
       opts.merge!(default_grid_io_opts)
       file = GridIO.new(@files, @chunks, filename, 'w', opts=opts)
       file.write(data)

data/lib/mongo/gridfs/grid_ext.rb

@@ -0,0 +1,30 @@
+# --
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+# ++
+
+module Mongo
+  module ClassMethods
+
+    def exists?(criteria)
+      BSON::ObjectID:
+      @files.find_one(query)
+    end
+
+    def list(query={})
+      @files.find(query)
+    end
+
+  end
+end

data/lib/mongo/gridfs/grid_file_system.rb

@@ -43,6 +43,9 @@ module Mongo
     # Open a file for reading or writing. Note that the options for this method only apply
     # when opening in 'w' mode.
     #
+    # Note that arbitary metadata attributes can be saved to the file by passing
+    # them is as options.
+    #
     # @param [String] filename the name of the file.
     # @param [String] mode either 'r' or 'w' for reading from
     #   or writing to the file.
@@ -105,7 +108,7 @@ module Mongo
     # Delete the file with the given filename. Note that this will delete
     # all versions of the file.
     #
-    # Note that deleting a GridFS file can result in read errors if another process
+    # Be careful with this. Deleting a GridFS file can result in read errors if another process
     # is attempting to read a file while it's being deleted. While the odds for this
     # kind of race condition are small, it's important to be aware of.
     #

data/test/collection_test.rb

@@ -165,7 +165,7 @@ class TestCollection < Test::Unit::TestCase
     end
   else
     def test_safe_update
-      @@test.create_index("x", true)
+      @@test.create_index("x", :unique => true)
       @@test.insert("x" => 5)
       @@test.insert("x" => 10)
 
@@ -182,7 +182,7 @@ class TestCollection < Test::Unit::TestCase
   end
 
   def test_safe_save
-    @@test.create_index("hello", true)
+    @@test.create_index("hello", :unique => true)
 
     @@test.save("hello" => "world")
     @@test.save("hello" => "world")
@@ -558,7 +558,7 @@ class TestCollection < Test::Unit::TestCase
     end
 
     should "create a unique index" do
-      @collection.create_index([['a', Mongo::ASCENDING]], true)
+      @collection.create_index([['a', Mongo::ASCENDING]], :unique => true)
       assert @collection.index_information['a_1']['unique'] == true
     end
 
@@ -577,6 +577,12 @@ class TestCollection < Test::Unit::TestCase
       end
     end
 
+    should "enforce proper index types" do
+      assert_raise MongoArgumentError do
+        @collection.create_index([['c', 'blah']])
+      end
+    end
+
     should "generate indexes in the proper order" do
       @collection.expects(:insert_documents) do |sel, coll, safe|
         assert_equal 'b_1_a_1', sel[:name]
@@ -594,4 +600,42 @@ class TestCollection < Test::Unit::TestCase
       end
     end
   end
+
+  context "Capped collections" do
+    setup do
+      @@db.drop_collection('log')
+      @capped = @@db.create_collection('log', :capped => true, :size => 1024)
+
+      10.times { |n| @capped.insert({:n => n}) }
+    end
+
+    should "find using a standard cursor" do
+      cursor = @capped.find
+      10.times do
+        assert cursor.next_document
+      end
+      assert_nil cursor.next_document
+      @capped.insert({:n => 100})
+      assert_nil cursor.next_document
+    end
+
+    should "" do
+      col = @@db['regular-collection']
+      col.insert({:a => 1000})
+      tail = Cursor.new(col, :tailable => true, :order => [['$natural', 1]])
+      assert_raise OperationFailure do
+        tail.next_document
+      end
+    end
+
+    should "find using a tailable cursor" do
+      tail = Cursor.new(@capped, :tailable => true, :order => [['$natural', 1]])
+      10.times do
+        assert tail.next_document
+      end
+      assert_nil tail.next_document
+      @capped.insert({:n => 100})
+      assert tail.next_document
+    end
+  end
 end

data/test/db_api_test.rb

@@ -275,7 +275,7 @@ class DBAPITest < Test::Unit::TestCase
   def test_index_information
     assert_equal @@coll.index_information.length, 1
 
-    name = @@db.create_index(@@coll.name, 'a')
+    name = @@coll.create_index('a')
     info = @@db.index_information(@@coll.name)
     assert_equal name, "a_1"
     assert_equal @@coll.index_information, info
@@ -303,7 +303,7 @@ class DBAPITest < Test::Unit::TestCase
   end
 
   def test_multiple_index_cols
-    name = @@db.create_index(@@coll.name, [['a', DESCENDING], ['b', ASCENDING], ['c', DESCENDING]])
+    name = @@coll.create_index([['a', DESCENDING], ['b', ASCENDING], ['c', DESCENDING]])
     info = @@db.index_information(@@coll.name)
     assert_equal 2, info.length
 
@@ -315,7 +315,7 @@ class DBAPITest < Test::Unit::TestCase
   end
 
   def test_multiple_index_cols_with_symbols
-    name = @@db.create_index(@@coll.name, [[:a, DESCENDING], [:b, ASCENDING], [:c, DESCENDING]])
+    name = @@coll.create_index([[:a, DESCENDING], [:b, ASCENDING], [:c, DESCENDING]])
     info = @@db.index_information(@@coll.name)
     assert_equal 2, info.length
 
@@ -338,7 +338,7 @@ class DBAPITest < Test::Unit::TestCase
 
     @@db.drop_collection("blah")
     test = @@db.collection("blah")
-    test.create_index("hello", unique=true)
+    test.create_index("hello", :unique => true)
 
     test.insert("hello" => "world")
     test.insert("hello" => "mike")
@@ -357,7 +357,7 @@ class DBAPITest < Test::Unit::TestCase
 
     @@db.drop_collection("blah")
     test = @@db.collection("blah")
-    test.create_index("hello.a", unique=true)
+    test.create_index("hello.a", :unique => true)
 
     test.insert("hello" => {"a" => 4, "b" => 5})
     test.insert("hello" => {"a" => 7, "b" => 2})

data/test/grid_test.rb

@@ -19,7 +19,7 @@ class GridTest < Test::Unit::TestCase
       setup do
         @data = "GRIDDATA" * 50000
         @grid = Grid.new(@db, 'test-fs')
-        @id   = @grid.put(@data, 'sample', :metadata => {'app' => 'photos'})
+        @id   = @grid.put(@data, :filename => 'sample', :metadata => {'app' => 'photos'})
       end
 
       should "retrieve the stored data" do
@@ -58,7 +58,7 @@ class GridTest < Test::Unit::TestCase
       end
 
       should "store the file with the old filename api" do
-        id = @grid.put(@data, 'sample', :metadata => @metadata)
+        id = @grid.put(@data, :filename => 'sample', :metadata => @metadata)
         file = @grid.get(id)
         assert_equal 'sample', file.filename
         assert_equal @metadata, file.metadata
@@ -106,7 +106,7 @@ class GridTest < Test::Unit::TestCase
     context "Storing data with a length of zero" do
       setup do
         @grid = Grid.new(@db, 'test-fs')
-        @id   = @grid.put('', 'sample', :metadata => {'app' => 'photos'})
+        @id   = @grid.put('', :filename => 'sample', :metadata => {'app' => 'photos'})
       end
 
       should "return the zero length" do
@@ -119,7 +119,7 @@ class GridTest < Test::Unit::TestCase
       setup do
         def read_and_write_stream(filename, read_length, opts={})
           io   = File.open(File.join(File.dirname(__FILE__), 'data', filename), 'r')
-          id   = @grid.put(io, filename + read_length.to_s, opts)
+          id   = @grid.put(io, opts.merge!(:filename => filename + read_length.to_s))
           file = @grid.get(id)
           io.rewind
           data = io.read

data/test/threading/test_threading_large_pool.rb

@@ -19,7 +19,7 @@ class TestThreadingLargePool < Test::Unit::TestCase
     @duplicate.insert("test" => "update")
     @unique.insert("test" => "insert")
     @unique.insert("test" => "update")
-    @unique.create_index("test", true)
+    @unique.create_index("test", :unique => true)
   end
 
   def test_safe_update

data/test/threading_test.rb

@@ -17,7 +17,7 @@ class TestThreading < Test::Unit::TestCase
     @duplicate.insert("test" => "update")
     @unique.insert("test" => "insert")
     @unique.insert("test" => "update")
-    @unique.create_index("test", true)
+    @unique.create_index("test", :unique => true)
   end
 
   def test_safe_update

metadata

@@ -3,10 +3,9 @@ name: mongo
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 0
-  - 20
   - 1
-  version: 0.20.1
+  - 0
+  version: "1.0"
 platform: ruby
 authors: 
 - Jim Menard
@@ -16,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-07 00:00:00 -04:00
+date: 2010-04-29 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,10 +26,9 @@ dependencies:
     - - "="
       - !ruby/object:Gem::Version 
         segments: 
-        - 0
-        - 20
         - 1
-        version: 0.20.1
+        - 0
+        version: "1.0"
   type: :runtime
   version_requirements: *id001
 description: A Ruby driver for MongoDB. For more information about Mongo, see http://www.mongodb.org.
@@ -53,6 +51,7 @@ files:
 - lib/mongo/db.rb
 - lib/mongo/exceptions.rb
 - lib/mongo/gridfs/grid.rb
+- lib/mongo/gridfs/grid_ext.rb
 - lib/mongo/gridfs/grid_file_system.rb
 - lib/mongo/gridfs/grid_io.rb
 - lib/mongo/util/conversions.rb