mongo 1.12.5 → 2.0.0.beta

data/lib/mongo/operation/read_preferrable.rb

@@ -0,0 +1,34 @@
+# Copyright (C) 2014-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
+  module Operation
+
+    # Adds behaviour for queries that need to take read preference into account.
+    #
+    # @since 2.0.0
+    module ReadPreferrable
+
+      private
+
+      def message(context)
+        sel = (context.mongos? && read_pref = read.to_mongos) ?
+                selector.merge(:$readPreference => read_pref) : selector
+        opts = context.standalone? || read.slave_ok? ?
+                 options.merge(flags: [:slave_ok]) : options
+        Protocol::Query.new(db_name, query_coll, sel, opts)
+      end
+    end
+  end
+end

data/lib/mongo/operation/result.rb

@@ -0,0 +1,259 @@
+# Copyright (C) 2014-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
+  module Operation
+
+    # Result wrapper for operations.
+    #
+    # @since 2.0.0
+    class Result
+      extend Forwardable
+      include Enumerable
+
+      # The number of documents updated in the write.
+      #
+      # @since 2.0.0
+      N = 'n'.freeze
+
+      # The ok status field in the result.
+      #
+      # @since 2.0.0
+      OK = 'ok'.freeze
+
+      # @return [ Array<Protocol::Reply> ] replies The wrapped wire protocol replies.
+      attr_reader :replies
+
+      # Is the result acknowledged?
+      #
+      # @note On MongoDB 2.6 and higher all writes are acknowledged since the
+      #   driver uses write commands for all write operations. On 2.4 and
+      #   lower, the result is acknowledged if the GLE has been executed after
+      #   the command. If not, no replies will be specified. Reads will always
+      #   return true here since a replies is always provided.
+      #
+      # @return [ true, false ] If the result is acknowledged.
+      #
+      # @since 2.0.0
+      def acknowledged?
+        !!@replies
+      end
+
+      # Determine if this result is a collection of multiple replies from the
+      # server.
+      #
+      # @example Is the result for multiple replies?
+      #   result.multiple?
+      #
+      # @return [ true, false ] If the result is for multiple replies.
+      #
+      # @since 2.0.0
+      def multiple?
+        replies.size > 1
+      end
+
+      # Get the cursor id if the response is acknowledged.
+      #
+      # @note Cursor ids of 0 indicate there is no cursor on the server.
+      #
+      # @example Get the cursor id.
+      #   result.cursor_id
+      #
+      # @return [ Integer ] The cursor id.
+      #
+      # @since 2.0.0
+      def cursor_id
+        acknowledged? ? replies.last.cursor_id : 0
+      end
+
+      # Get the namespace of the cursor. The method should be defined in
+      # result classes where 'ns' is in the server response.
+      #
+      # @return [ Nil ]
+      #
+      # @since 2.0.0
+      def namespace
+        nil
+      end
+
+      # Get the documents in the result.
+      #
+      # @example Get the documents.
+      #   result.documents
+      #
+      # @return [ Array<BSON::Document> ] The documents.
+      #
+      # @since 2.0.0
+      def documents
+        if acknowledged?
+          replies.flat_map{ |reply| reply.documents }
+        else
+          []
+        end
+      end
+
+      # Iterate over the documents in the replies.
+      #
+      # @example Iterate over the documents.
+      #   result.each do |doc|
+      #     p doc
+      #   end
+      #
+      # @return [ Enumerator ] The enumerator.
+      #
+      # @since 2.0.0
+      #
+      # @yieldparam [ BSON::Document ] Each document in the result.
+      def each(&block)
+        documents.each(&block)
+      end
+
+      # Initialize a new result result.
+      #
+      # @example Instantiate the result.
+      #   Result.new(replies)
+      #
+      # @param [ Protocol::Reply ] replies The wire protocol replies.
+      #
+      # @since 2.0.0
+      def initialize(replies)
+        @replies = replies.is_a?(Protocol::Reply) ? [ replies ] : replies
+      end
+
+      # Get the pretty formatted inspection of the result.
+      #
+      # @example Inspect the result.
+      #   result.inspect
+      #
+      # @return [ String ] The inspection.
+      #
+      # @since 2.0.0
+      def inspect
+        "#<Mongo::Operation::Result:#{object_id} documents=#{documents}>"
+      end
+
+      # Get the first reply from the result.
+      #
+      # @example Get the first reply.
+      #   result.reply
+      #
+      # @return [ Protocol::Reply ] The first reply.
+      #
+      # @since 2.0.0
+      def reply
+        if acknowledged?
+          replies.first
+        else
+          nil
+        end
+      end
+
+      # Get the count of documents returned by the server.
+      #
+      # @example Get the number returned.
+      #   result.returned_count
+      #
+      # @return [ Integer ] The number of documents returned.
+      #
+      # @since 2.0.0
+      def returned_count
+        if acknowledged?
+          multiple? ? aggregate_returned_count : reply.number_returned
+        else
+          0
+        end
+      end
+
+      # If the result was a command then determine if it was considered a
+      # success.
+      #
+      # @note If the write was unacknowledged, then this will always return
+      #   true.
+      #
+      # @example Was the command successful?
+      #   result.successful?
+      #
+      # @return [ true, false ] If the command was successful.
+      #
+      # @since 2.0.0
+      def successful?
+        return true if !acknowledged?
+        if first_document.has_key?(OK)
+          first_document[OK] == 1 && parser.message.empty?
+        else
+          parser.message.empty?
+        end
+      end
+
+      # Validate the result by checking for any errors.
+      #
+      # @note This only checks for errors with writes since authentication is
+      #   handled at the connection level and any authentication errors would
+      #   be raised there, before a Result is ever created.
+      #
+      # @example Validate the result.
+      #   result.validate!
+      #
+      # @raise [ Error::OperationFailure ] If an error is in the result.
+      #
+      # @return [ Result ] The result if verification passed.
+      #
+      # @since 2.0.0
+      def validate!
+        !successful? ? raise(Error::OperationFailure.new(parser.message)) : self
+      end
+
+      # Get the number of documents written by the server.
+      #
+      # @example Get the number of documents written.
+      #   result.written_count
+      #
+      # @return [ Integer ] The number of documents written.
+      #
+      # @since 2.0.0
+      def written_count
+        if acknowledged?
+          multiple? ? aggregate_written_count : (first_document[N] || 0)
+        else
+          0
+        end
+      end
+      alias :n :written_count
+
+      private
+
+      def aggregate_returned_count
+        replies.reduce(0) do |n, reply|
+          n += reply.number_returned
+          n
+        end
+      end
+
+      def aggregate_written_count
+        documents.reduce(0) do |n, document|
+          n += (document[N] || 0)
+          n
+        end
+      end
+
+      def parser
+        @parser ||= Error::Parser.new(first_document)
+      end
+
+      def first_document
+        @first_document ||= first || BSON::Document.new
+      end
+    end
+  end
+end

data/lib/mongo/operation/specifiable.rb

@@ -0,0 +1,380 @@
+# Copyright (C) 2014-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
+  module Operation
+
+    # This module contains common functionality for convenience methods getting
+    # various values from the spec.
+    #
+    # @since 2.0.0
+    module Specifiable
+
+      # The field for database name.
+      #
+      # @since 2.0.0
+      DB_NAME = :db_name.freeze
+
+      # The field for deletes.
+      #
+      # @since 2.0.0
+      DELETES = :deletes.freeze
+
+      # The field for delete.
+      #
+      # @since 2.0.0
+      DELETE = :delete.freeze
+
+      # The field for documents.
+      #
+      # @since 2.0.0
+      DOCUMENTS = :documents.freeze
+
+      # The field for collection name.
+      #
+      # @since 2.0.0
+      COLL_NAME = :coll_name.freeze
+
+      # The field for cursor count.
+      #
+      # @since 2.0.0
+      CURSOR_COUNT = :cursor_count.freeze
+
+      # The field for cursor id.
+      #
+      # @since 2.0.0
+      CURSOR_ID = :cursor_id.freeze
+
+      # The field for cursor ids.
+      #
+      # @since 2.0.0
+      CURSOR_IDS = :cursor_ids.freeze
+
+      # The field for indexes.
+      #
+      # @since 2.0.0
+      INDEX = :index.freeze
+
+      # The field for index names.
+      #
+      # @since 2.0.0
+      INDEX_NAME = :index_name.freeze
+
+      # The field for options.
+      #
+      # @since 2.0.0
+      OPTIONS = :options.freeze
+
+      # The field for a selector.
+      #
+      # @since 2.0.0
+      SELECTOR = :selector.freeze
+
+      # The field for number to return.
+      #
+      # @since 2.0.0
+      TO_RETURN = :to_return.freeze
+
+      # The field for updates.
+      #
+      # @since 2.0.0
+      UPDATES = :updates.freeze
+
+      # The field for update.
+      #
+      # @since 2.0.0
+      UPDATE = :update.freeze
+
+      # The field name for a user.
+      #
+      # @since 2.0.0
+      USER = :user.freeze
+
+      # The field name for user name.
+      #
+      # @since 2.0.0
+      USER_NAME = :user_name.freeze
+
+      # The field name for a write concern.
+      #
+      # @since 2.0.0
+      WRITE_CONCERN = :write_concern.freeze
+
+      # The field name for the read preference.
+      #
+      # @since 2.0.0
+      READ = :read.freeze
+
+      # @return [ Hash ] spec The specification for the operation.
+      attr_reader :spec
+
+      # Check equality of two specifiable operations.
+      #
+      # @example Are the operations equal?
+      #   operation == other
+      #
+      # @param [ Object ] other The other operation.
+      #
+      # @return [ true, false ] Whether the objects are equal.
+      #
+      # @since 2.0.0
+      def ==(other)
+        return false unless other.is_a?(Specifiable)
+        spec == other.spec
+      end
+      alias_method :eql?, :==
+
+      # Get the cursor count from the spec.
+      #
+      # @example Get the cursor count.
+      #   specifiable.cursor_count
+      #
+      # @return [ Integer ] The cursor count.
+      #
+      # @since 2.0.0
+      def cursor_count
+        spec[CURSOR_COUNT]
+      end
+
+      # The name of the database to which the operation should be sent.
+      #
+      # @example Get the database name.
+      #   specifiable.db_name
+      #
+      # @return [ String ] Database name.
+      #
+      # @since 2.0.0
+      def db_name
+        spec[DB_NAME]
+      end
+
+      # Get the deletes from the specification.
+      #
+      # @example Get the deletes.
+      #   specifiable.deletes
+      #
+      # @return [ Array<BSON::Document> ] The deletes.
+      #
+      # @since 2.0.0
+      def deletes
+        spec[DELETES]
+      end
+
+      # Get the delete document from the specification.
+      #
+      # @example Get the delete document.
+      #   specifiable.delete
+      #
+      # @return [ Hash ] The delete document.
+      #
+      # @since 2.0.0
+      def delete
+        spec[DELETE]
+      end
+
+      # The documents to in the specification.
+      #
+      # @example Get the documents.
+      #   specifiable.documents
+      #
+      # @return [ Array<BSON::Document> ] The documents.
+      #
+      # @since 2.0.0
+      def documents
+        spec[DOCUMENTS]
+      end
+
+      # The name of the collection to which the operation should be sent.
+      #
+      # @example Get the collection name.
+      #   specifiable.coll_name
+      #
+      # @return [ String ] Collection name.
+      #
+      # @since 2.0.0
+      def coll_name
+        spec[COLL_NAME]
+      end
+
+      # The id of the cursor created on the server.
+      #
+      # @example Get the cursor id.
+      #   specifiable.cursor_id
+      #
+      # @return [ Integer ] The cursor id.
+      #
+      # @since 2.0.0
+      def cursor_id
+        spec[CURSOR_ID]
+      end
+
+      # The ids of the cursors to kill from the spec.
+      #
+      # @example Get the cursor ids from the spec.
+      #   specifiable.cursor_ids
+      #
+      # @return [ Array<Integer> ] The cursor ids.
+      #
+      # @since 2.0.0
+      def cursor_ids
+        spec[CURSOR_IDS]
+      end
+
+      # Get the index from the specification.
+      #
+      # @example Get the index specification.
+      #   specifiable.index
+      #
+      # @return [ Hash ] The index specification.
+      #
+      # @since 2.0.0
+      def index
+        spec[INDEX]
+      end
+
+      # Get the index name from the spec.
+      #
+      # @example Get the index name.
+      #   specifiable.index_name
+      #
+      # @return [ String ] The index name.
+      #
+      # @since 2.0.0
+      def index_name
+        spec[INDEX_NAME]
+      end
+
+      # Create the new specifiable operation.
+      #
+      # @example Create the new specifiable operation.
+      #   Specifiable.new(spec)
+      #
+      # @param [ Hash ] spec The operation specification.
+      #
+      # @see The individual operations for the values they require in their
+      #   specs.
+      #
+      # @since 2.0.0
+      def initialize(spec)
+        @spec = spec
+      end
+
+      # Get the options for the operation.
+      #
+      # @example Get the options.
+      #   specifiable.options
+      #
+      # @return [ Hash ] The options.
+      #
+      # @since 2.0.0
+      def options
+        spec[OPTIONS] || {}
+      end
+
+      # The selector for from the specification.
+      #
+      # @example Get a selector specification.
+      #   specifiable.selector.
+      #
+      # @return [ Hash ] The selector spec.
+      #
+      # @since 2.0.0
+      def selector
+        spec[SELECTOR]
+      end
+
+      # The number of documents to request from the server.
+      #
+      # @example Get the to return value from the spec.
+      #   specifiable.to_return
+      #
+      # @return [ Integer ] The number of documents to return.
+      #
+      # @since 2.0.0
+      def to_return
+        spec[TO_RETURN]
+      end
+
+      # The update documents from the spec.
+      #
+      # @example Get the update documents.
+      #
+      # @return [ Array<BSON::Document> ] The update documents.
+      #
+      # @since 2.0.0
+      def updates
+        spec[UPDATES]
+      end
+
+      # The update document from the spec.
+      #
+      # @example Get the update document.
+      #
+      # @return [ Hash ] The update document.
+      #
+      # @since 2.0.0
+      def update
+        spec[UPDATE]
+      end
+
+      # The user for user related operations.
+      #
+      # @example Get the user.
+      #   specifiable.user
+      #
+      # @return [ Auth::User ] The user.
+      #
+      # @since 2.0.0
+      def user
+        spec[USER]
+      end
+
+      # The user name from the specification.
+      #
+      # @example Get the user name.
+      #   specifiable.user_name
+      #
+      # @return [ String ] The user name.
+      #
+      # @since 2.0.
+      def user_name
+        spec[USER_NAME]
+      end
+
+      # The write concern to use for this operation.
+      #
+      # @example Get the write concern.
+      #   specifiable.write_concern
+      #
+      # @return [ Mongo::WriteConcern ] The write concern.
+      #
+      # @since 2.0.0
+      def write_concern
+        @spec[WRITE_CONCERN] || WriteConcern.get(WriteConcern::DEFAULT)
+      end
+
+      # The read preference for this operation.
+      #
+      # @example Get the read preference.
+      #   specifiable.read
+      #
+      # @return [ Mongo::ServerSelector ] The read preference.
+      #
+      # @since 2.0.0
+      def read
+        @spec[READ] || ServerSelector.get
+      end
+    end
+  end
+end