mongo 2.1.0.beta → 2.2.0

data/lib/mongo/collection.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/bulk_write'
 require 'mongo/collection/view'
 
 module Mongo
@@ -22,6 +23,17 @@ module Mongo
   # @since 2.0.0
   class Collection
     extend Forwardable
+    include Retryable
+
+    # The capped option.
+    #
+    # @since 2.1.0
+    CAPPED = 'capped'.freeze
+
+    # The ns field constant.
+    #
+    # @since 2.1.0
+    NS = 'ns'.freeze
 
     # @return [ Mongo::Database ] The database the collection resides in.
     attr_reader :database
@@ -33,7 +45,7 @@ module Mongo
     attr_reader :options
 
     # Get client, cluster, read preference, and write concern from client.
-    def_delegators :database, :client, :cluster, :read_preference, :write_concern
+    def_delegators :database, :client, :cluster
 
     # Delegate to the cluster for the next primary.
     def_delegators :cluster, :next_primary
@@ -41,6 +53,11 @@ module Mongo
     # Convenience delegators to find.
     def_delegators :find, :parallel_scan
 
+    # Options that can be updated on a new Collection instance via the #with method.
+    #
+    # @since 2.1.0
+    CHANGEABLE_OPTIONS = [ :read, :read_concern, :write ].freeze
+
     # Check if a collection is equal to another object. Will check the name and
     # the database for equality.
     #
@@ -74,6 +91,65 @@ module Mongo
       @options = options.freeze
     end
 
+    # Get the read concern for this collection instance.
+    #
+    # @example Get the read concern.
+    #   collection.read_concern
+    #
+    # @return [ Hash ] The read concern.
+    #
+    # @since 2.2.0
+    def read_concern
+      @read_concern ||= options[:read_concern]
+    end
+
+    # Get the read preference on this collection.
+    #
+    # @example Get the read preference.
+    #   collection.read_preference
+    #
+    # @return [ Mongo::ServerSelector ] The read preference.
+    #
+    # @since 2.0.0
+    def read_preference
+      @read_preference ||= options[:read] ? ServerSelector.get(client.options.merge(options[:read])) :
+        database.read_preference
+    end
+
+    # Get the write concern on this collection.
+    #
+    # @example Get the write concern.
+    #   collection.write_concern
+    #
+    # @return [ Mongo::WriteConcern ] The write concern.
+    #
+    # @since 2.0.0
+    def write_concern
+      @write_concern ||= options[:write] ? WriteConcern.get(options[:write]) :
+        database.write_concern
+    end
+
+    # Provides a new collection with either a new read preference or new write concern
+    # merged over the existing read preference / write concern.
+    #
+    # @example Get a collection with changed read preference.
+    #   collection.with(:read => { :mode => :primary_preferred })
+    #
+    # @example Get a collection with changed write concern.
+    #   collection.with(:write => { w:  3 })
+
+    # @param [ Hash ] new_options The new options to use.
+    #
+    # @return [ Mongo::Collection ] A new collection instance.
+    #
+    # @since 2.1.0
+    def with(new_options)
+      new_options.keys.each do |k|
+        raise Error::UnchangeableCollectionOption.new(k) unless CHANGEABLE_OPTIONS.include?(k)
+      end
+      Collection.new(database, name, options.merge(new_options))
+    end
+
     # Is the collection capped?
     #
     # @example Is the collection capped?
@@ -83,7 +159,7 @@ module Mongo
     #
     # @since 2.0.0
     def capped?
-      database.command(:collstats => name).documents[0]['capped']
+      database.command(:collstats => name).documents[0][CAPPED]
     end
 
     # Force the collection to be created in the database.
@@ -171,6 +247,8 @@ module Mongo
     #   aggregation to run.
     # @option options [ true, false ] :use_cursor Indicates whether the command will request that the server
     #   provide results using a cursor.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
     #
     # @return [ Aggregation ] The aggregation object.
     #
@@ -256,13 +334,17 @@ module Mongo
     #
     # @since 2.0.0
     def insert_one(document, options = {})
-      Operation::Write::Insert.new(
-        :documents => [ document ],
-        :db_name => database.name,
-        :coll_name => name,
-        :write_concern => write_concern,
-        :options => options
-      ).execute(next_primary.context)
+      write_with_retry do
+        Operation::Write::Insert.new(
+          :documents => [ document ],
+          :db_name => database.name,
+          :coll_name => name,
+          :write_concern => write_concern,
+          :bypass_document_validation => !!options[:bypass_document_validation],
+          :options => options,
+          :id_generator => client.options[:id_generator]
+        ).execute(next_primary.context)
+      end
     end
 
     # Insert the provided documents into the collection.
@@ -286,19 +368,21 @@ module Mongo
     # @example Execute a bulk write.
     #   collection.bulk_write(operations, options)
     #
-    # @param [ Array<Hash> ] operations The operations.
+    # @param [ Array<Hash> ] requests The bulk write requests.
     # @param [ Hash ] options The options.
     #
     # @option options [ true, false ] :ordered Whether the operations
     #   should be executed in order.
     # @option options [ Hash ] :write_concern The write concern options.
     #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
     #
     # @return [ BulkWrite::Result ] The result of the operation.
     #
     # @since 2.0.0
-    def bulk_write(operations, options = {})
-      BulkWrite.get(self, operations, options).execute
+    def bulk_write(requests, options = {})
+      BulkWrite.new(self, requests, options).execute
     end
 
     # Remove a document from the collection.
@@ -329,6 +413,24 @@ module Mongo
       find(filter).delete_many
     end
 
+    # Execute a parallel scan on the collection view.
+    #
+    # Returns a list of up to cursor_count cursors that can be iterated concurrently.
+    # As long as the collection is not modified during scanning, each document appears once
+    # in one of the cursors' result sets.
+    #
+    # @example Execute a parallel collection scan.
+    #   collection.parallel_scan(2)
+    #
+    # @param [ Integer ] cursor_count The max number of cursors to return.
+    #
+    # @return [ Array<Cursor> ] An array of cursors.
+    #
+    # @since 2.1
+    def parallel_scan(cursor_count)
+      find.send(:parallel_scan, cursor_count)
+    end
+
     # Replaces a single document in the collection with the new document.
     #
     # @example Replace a single document.
@@ -340,6 +442,8 @@ module Mongo
     #
     # @option options [ true, false ] :upsert Whether to upsert if the
     #   document doesn't exist.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
     #
     # @return [ Result ] The response from the database.
     #
@@ -359,6 +463,8 @@ module Mongo
     #
     # @option options [ true, false ] :upsert Whether to upsert if the
     #   document doesn't exist.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
     #
     # @return [ Result ] The response from the database.
     #
@@ -378,6 +484,8 @@ module Mongo
     #
     # @option options [ true, false ] :upsert Whether to upsert if the
     #   document doesn't exist.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
     #
     # @return [ Result ] The response from the database.
     #
@@ -400,6 +508,8 @@ module Mongo
     # @option options [ Hash ] :projection The fields to include or exclude in the returned doc.
     # @option options [ Hash ] :sort The key and direction pairs by which the result set
     #   will be sorted.
+    # @option options [ Hash ] :write_concern The write concern options.
+    #   Defaults to the collection's write concern.
     #
     # @return [ BSON::Document, nil ] The document, if found.
     #
@@ -428,6 +538,10 @@ module Mongo
     #   will be sorted.
     # @option options [ Symbol ] :return_document Either :before or :after.
     # @option options [ true, false ] :upsert Whether to upsert if the document doesn't exist.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
+    # @option options [ Hash ] :write_concern The write concern options.
+    #   Defaults to the collection's write concern.
     #
     # @return [ BSON::Document ] The document.
     #
@@ -456,6 +570,10 @@ module Mongo
     #   will be sorted.
     # @option options [ Symbol ] :return_document Either :before or :after.
     # @option options [ true, false ] :upsert Whether to upsert if the document doesn't exist.
+    # @option options [ true, false ] :bypass_document_validation Whether or
+    #   not to skip document level validation.
+    # @option options [ Hash ] :write_concern The write concern options.
+    #   Defaults to the collection's write concern.
     #
     # @return [ BSON::Document ] The document.
     #

data/lib/mongo/cursor/builder/get_more_command.rb

@@ -0,0 +1,71 @@
+# Copyright (C) 2015 MongoDB, 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
+  class Cursor
+    module Builder
+
+      # Generates a specification for a get more command.
+      #
+      # @since 2.2.0
+      class GetMoreCommand
+        extend Forwardable
+
+        # @return [ Cursor ] cursor The cursor.
+        attr_reader :cursor
+
+        def_delegators :@cursor, :batch_size, :collection_name, :database, :view
+
+        # Create the new builder.
+        #
+        # @example Create the builder.
+        #   GetMoreCommand.new(cursor)
+        #
+        # @param [ Cursor ] cursor The cursor.
+        #
+        # @since 2.2.0
+        def initialize(cursor)
+          @cursor = cursor
+        end
+
+        # Get the specification.
+        #
+        # @example Get the specification.
+        #   get_more_command.specification
+        #
+        # @return [ Hash ] The spec.
+        #
+        # @since 2.2.0
+        def specification
+          { selector: get_more_command, db_name: database.name }
+        end
+
+        private
+
+        def get_more_command
+          command = { :getMore => cursor.id, :collection => collection_name }
+          command[:batchSize] = batch_size if batch_size
+          # If the max_await_time_ms option is set, then we set maxTimeMS on
+          # the get more command.
+          if view.respond_to?(:max_await_time_ms)
+            if view.max_await_time_ms && view.options[:await_data]
+              command[:maxTimeMS] = view.max_await_time_ms
+            end
+          end
+          command
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cursor/builder/kill_cursors_command.rb

@@ -0,0 +1,62 @@
+# Copyright (C) 2015 MongoDB, 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
+  class Cursor
+    module Builder
+
+      # Generates a specification for a kill cursors command.
+      #
+      # @since 2.2.0
+      class KillCursorsCommand
+        extend Forwardable
+
+        # @return [ Cursor ] cursor The cursor.
+        attr_reader :cursor
+
+        def_delegators :@cursor, :collection_name, :database
+
+        # Create the new builder.
+        #
+        # @example Create the builder.
+        #   KillCursorsCommand.new(cursor)
+        #
+        # @param [ Cursor ] cursor The cursor.
+        #
+        # @since 2.2.0
+        def initialize(cursor)
+          @cursor = cursor
+        end
+
+        # Get the specification.
+        #
+        # @example Get the specification.
+        #   kill_cursors_command.specification
+        #
+        # @return [ Hash ] The spec.
+        #
+        # @since 2.2.0
+        def specification
+          { selector: kill_cursors_command, db_name: database.name }
+        end
+
+        private
+
+        def kill_cursors_command
+          { :killCursors => collection_name, :cursors => [ cursor.id ] }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cursor/builder/op_get_more.rb

@@ -0,0 +1,61 @@
+# Copyright (C) 2015 MongoDB, 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
+  class Cursor
+    module Builder
+
+      # Encapsulates behaviour around generating an OP_GET_MORE specification.
+      #
+      # @since 2.2.0
+      class OpGetMore
+        extend Forwardable
+
+        # @return [ Cursor ] cursor The cursor.
+        attr_reader :cursor
+
+        def_delegators :@cursor, :collection_name, :database, :to_return
+
+        # Create the new builder.
+        #
+        # @example Create the builder.
+        #   OpGetMore.new(cursor)
+        #
+        # @param [ Cursor ] cursor The cursor.
+        #
+        # @since 2.2.0
+        def initialize(cursor)
+          @cursor = cursor
+        end
+
+        # Get the specification.
+        #
+        # @example Get the specification.
+        #   op_get_more.specification
+        #
+        # @return [ Hash ] The specification.
+        #
+        # @since 2.2.0
+        def specification
+          {
+            :to_return => to_return,
+            :cursor_id => cursor.id,
+            :db_name   => database.name,
+            :coll_name => collection_name
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cursor/builder/op_kill_cursors.rb

@@ -0,0 +1,56 @@
+# Copyright (C) 2015 MongoDB, 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
+  class Cursor
+    module Builder
+
+      # Encapsulates behaviour around generating an OP_KILL_CURSORS specification.
+      #
+      # @since 2.2.0
+      class OpKillCursors
+        extend Forwardable
+
+        # @return [ Cursor ] cursor The cursor.
+        attr_reader :cursor
+
+        def_delegators :@cursor, :collection_name, :database
+
+        # Create the new builder.
+        #
+        # @example Create the builder.
+        #   OpKillCursors.new(cursor)
+        #
+        # @param [ Cursor ] cursor The cursor.
+        #
+        # @since 2.2.0
+        def initialize(cursor)
+          @cursor = cursor
+        end
+
+        # Get the specification.
+        #
+        # @example Get the specification.
+        #   op_kill_cursors.specification
+        #
+        # @return [ Hash ] The specification.
+        #
+        # @since 2.2.0
+        def specification
+          { :coll_name => collection_name, :db_name => database.name, :cursor_ids => [ cursor.id ] }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cursor/builder.rb

@@ -0,0 +1,18 @@
+# Copyright (C) 2015 MongoDB, 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.
+
+require 'mongo/cursor/builder/op_get_more'
+require 'mongo/cursor/builder/op_kill_cursors'
+require 'mongo/cursor/builder/get_more_command'
+require 'mongo/cursor/builder/kill_cursors_command'

data/lib/mongo/cursor.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/cursor/builder'
+
 module Mongo
 
   # Client-side representation of an iterator over a query result set on
@@ -35,6 +37,9 @@ module Mongo
     def_delegators :@view, :collection, :limit
     def_delegators :collection, :client, :database
 
+    # @return [ Collection::View ] view The collection view.
+    attr_reader :view
+
     # Creates a +Cursor+ object.
     #
     # @example Instantiate the cursor.
@@ -82,12 +87,71 @@ module Mongo
       end
     end
 
-    private
-
+    # Get the batch size.
+    #
+    # @example Get the batch size.
+    #   cursor.batch_size
+    #
+    # @return [ Integer ] The batch size.
+    #
+    # @since 2.2.0
     def batch_size
       @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
     end
 
+    # Is the cursor closed?
+    #
+    # @example Is the cursor closed?
+    #   cursor.closed?
+    #
+    # @return [ true, false ] If the cursor is closed.
+    #
+    # @since 2.2.0
+    def closed?
+      !more?
+    end
+
+    # Get the parsed collection name.
+    #
+    # @example Get the parsed collection name.
+    #   cursor.coll_name
+    #
+    # @return [ String ] The collection name.
+    #
+    # @since 2.2.0
+    def collection_name
+      @coll_name || collection.name
+    end
+
+    # Get the cursor id.
+    #
+    # @example Get the cursor id.
+    #   cursor.id
+    #
+    # @note A cursor id of 0 means the cursor was closed on the server.
+    #
+    # @return [ Integer ] The cursor id.
+    #
+    # @since 2.2.0
+    def id
+      @cursor_id
+    end
+
+    # Get the number of documents to return. Used on 3.0 and lower server
+    # versions.
+    #
+    # @example Get the number to return.
+    #   cursor.to_return
+    #
+    # @return [ Integer ] The number of documents to return.
+    #
+    # @since 2.2.0
+    def to_return
+      use_limit? ? @remaining : (batch_size || 0)
+    end
+
+    private
+
     def exhausted?
       limited? ? @remaining <= 0 : false
     end
@@ -97,16 +161,11 @@ module Mongo
     end
 
     def get_more_operation
-      Operation::Read::GetMore.new(get_more_spec)
-    end
-
-    def get_more_spec
-      {
-        :to_return => to_return,
-        :cursor_id => @cursor_id,
-        :db_name   => database.name,
-        :coll_name => @coll_name || collection.name
-      }
+      if @server.features.find_command_enabled?
+        Operation::Commands::GetMore.new(Builder::GetMoreCommand.new(self).specification)
+      else
+        Operation::Read::GetMore.new(Builder::OpGetMore.new(self).specification)
+      end
     end
 
     def kill_cursors
@@ -114,11 +173,11 @@ module Mongo
     end
 
     def kill_cursors_operation
-      Operation::KillCursors.new(kill_cursors_spec)
-    end
-
-    def kill_cursors_spec
-      { :cursor_ids => [ @cursor_id ]}
+      if @server.features.find_command_enabled?
+        Operation::Commands::Command.new(Builder::KillCursorsCommand.new(self).specification)
+      else
+        Operation::KillCursors.new(Builder::OpKillCursors.new(self).specification)
+      end
     end
 
     def limited?
@@ -136,10 +195,6 @@ module Mongo
       result.documents
     end
 
-    def to_return
-      use_limit? ? @remaining : (batch_size || 0)
-    end
-
     def use_limit?
       limited? && batch_size >= @remaining
     end