Deprecating Collection#modify, Collection#replace and Collection#repsert in favor of Collection#update

lib/mongo.rb

@@ -4,6 +4,7 @@ require 'mongo/types/objectid'
 require 'mongo/types/regexp_of_holding'
 require 'mongo/types/undefined'
 
+require 'mongo/errors'
 require 'mongo/mongo'
 require 'mongo/message'
 require 'mongo/db'

lib/mongo/collection.rb

@@ -128,23 +128,60 @@ module XGen
           remove({})
         end
 
+        # DEPRECATED - use update(... :upsert => true) instead
+        #
         # Update records that match +selector+ by applying +obj+ as an update.
         # If no match, inserts (???).
         def repsert(selector, obj)
-          @db.repsert_in_db(@name, selector, obj)
+          warn "Collection#repsert is deprecated and will be removed. Please use Collection#update instead."
+          update(selector, obj, :upsert => true)
         end
 
+        # DEPRECATED - use update(... :upsert => false) instead
+        #
         # Update records that match +selector+ by applying +obj+ as an update.
         def replace(selector, obj)
-          @db.replace_in_db(@name, selector, obj)
+          warn "Collection#replace is deprecated and will be removed. Please use Collection#update instead."
+          update(selector, obj)
         end
 
+        # DEPRECATED - use update(... :upsert => false) instead
+        #
         # Update records that match +selector+ by applying +obj+ as an update.
         # Both +selector+ and +modifier_obj+ are required.
         def modify(selector, modifier_obj)
-          raise "no object" unless modifier_obj
-          raise "no selector" unless selector
-          @db.modify_in_db(@name, selector, modifier_obj)
+          warn "Collection#modify is deprecated and will be removed. Please use Collection#update instead."
+          update(selector, modifier_obj)
+        end
+
+        # Update a document(s) in this collection.
+        #
+        # :spec :: a hash specifying elements which must be present for
+        #   a document to be updated
+        # :document :: a hash specifying the fields to be changed in the
+        #   selected document(s), or (in the case of an upsert) the document to
+        #   be inserted
+        #
+        # Options:
+        # :upsert :: if true, perform an upsert operation
+        # :safe :: if true, check that the update succeeded. OperationFailure
+        #   will be raised on an error. Checking for safety requires an extra
+        #   round-trip to the database
+        def update(spec, document, options={})
+          upsert = options.delete(:upsert)
+          safe = options.delete(:safe)
+
+          if upsert
+            @db.repsert_in_db(@name, spec, document)
+          else
+            @db.replace_in_db(@name, spec, document)
+          end
+          if safe
+            error = @db.error
+            if error
+              raise OperationFailure, error
+            end
+          end
         end
 
         # Create a new index. +field_or_spec+

lib/mongo/errors.rb

@@ -0,0 +1,24 @@
+# Copyright 2009 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.
+
+# Exceptions raised by the MongoDB driver.
+
+module XGen
+  module Mongo
+    module Driver
+      # Raised when a database operation fails.
+      class OperationFailure < RuntimeError; end
+    end
+  end
+end

mongo-ruby-driver.gemspec

@@ -24,6 +24,7 @@ PACKAGE_FILES = ['README.rdoc', 'Rakefile', 'mongo-ruby-driver.gemspec',
                  'lib/mongo/gridfs/chunk.rb',
                  'lib/mongo/gridfs/grid_store.rb',
                  'lib/mongo/gridfs.rb',
+                 'lib/mongo/errors.rb',
                  'lib/mongo/message/get_more_message.rb',
                  'lib/mongo/message/insert_message.rb',
                  'lib/mongo/message/kill_cursors_message.rb',
@@ -66,6 +67,7 @@ TEST_FILES = ['tests/mongo-qa/_common.rb',
               'tests/test_bson.rb',
               'tests/test_byte_buffer.rb',
               'tests/test_chunk.rb',
+              'tests/test_collection.rb',
               'tests/test_cursor.rb',
               'tests/test_db.rb',
               'tests/test_db_api.rb',

tests/test_collection.rb

@@ -0,0 +1,66 @@
+# --
+# Copyright (C) 2008-2009 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.
+# ++
+
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'test/unit'
+
+# NOTE: assumes Mongo is running
+class TestCollection < Test::Unit::TestCase
+  include XGen::Mongo
+  include XGen::Mongo::Driver
+
+  @@db = Mongo.new(ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost',
+                   ENV['MONGO_RUBY_DRIVER_PORT'] || Mongo::DEFAULT_PORT).db('ruby-mongo-test')
+  @@test = @@db.collection("test")
+
+  def setup
+    @@test.drop()
+  end
+
+  def test_update
+    id1 = @@test.save("x" => 5)
+    @@test.update({}, {"$inc" => {"x" => 1}})
+    assert_equal 1, @@test.count()
+    assert_equal 6, @@test.find_first(:_id => id1)["x"]
+
+    id2 = @@test.save("x" => 1)
+    @@test.update({"x" => 6}, {"$inc" => {"x" => 1}})
+    assert_equal 7, @@test.find_first(:_id => id1)["x"]
+    assert_equal 1, @@test.find_first(:_id => id2)["x"]
+  end
+
+  def test_upsert
+    @@test.update({"page" => "/"}, {"$inc" => {"count" => 1}}, :upsert => true)
+    @@test.update({"page" => "/"}, {"$inc" => {"count" => 1}}, :upsert => true)
+
+    assert_equal 1, @@test.count()
+    assert_equal 2, @@test.find_first()["count"]
+  end
+
+  def test_safe_update
+    @@test.create_index("x")
+    @@test.insert("x" => 5)
+
+    @@test.update({}, {"$inc" => {"x" => 1}})
+    assert @@db.error?
+
+    assert_raise OperationFailure do
+      @@test.update({}, {"$inc" => {"x" => 1}}, :safe => true)
+    end
+  end
+end
+