moped 1.5.3 → 2.0.0.beta

data/lib/moped/protocol/message.rb

@@ -35,6 +35,43 @@ module Moped
     #
     module Message
 
+      # Default implementation for a message is to do nothing when receiving
+      # replies.
+      #
+      # @example Receive replies.
+      #   message.receive_replies(connection)
+      #
+      # @param [ Connection ] connection The connection.
+      #
+      # @return [ nil ] nil.
+      #
+      # @since 1.0.0
+      def receive_replies(connection); end
+
+      # Serializes the message and all of its fields to a new buffer or to the
+      # provided buffer.
+      #
+      # @example Serliaze the message.
+      #   message.serialize
+      #
+      # @param [ String ] buffer A buffer to serialize to.
+      #
+      # @return [ String ] The result of serliazing this message
+      #
+      # @since 1.0.0
+      def serialize(buffer = "")
+        raise NotImplementedError, "This method is generated after calling #finalize on a message class"
+      end
+      alias :to_s :serialize
+
+      # @return [String] the nicely formatted version of the message
+      def inspect
+        fields = self.class.fields.map do |field|
+          "@#{field}=" + __send__(field).inspect
+        end
+        "#<#{self.class.name}\n" <<
+        "  #{fields * "\n  "}>"
+      end
       class << self
 
         # Extends the including class with +ClassMethods+.
@@ -42,10 +79,8 @@ module Moped
         # @param [Class] subclass the inheriting class
         def included(base)
           super
-
-          base.extend ClassMethods
+          base.extend(ClassMethods)
         end
-
         private :included
       end
 
@@ -119,21 +154,21 @@ module Moped
           if options[:optional]
             class_eval <<-RUBY, __FILE__, __LINE__ + 1
               def serialize_#{name}(buffer)
-                BSON::Document.serialize(#{name}, buffer) if #{name}
+                buffer << #{name}.to_bson if #{name}
               end
             RUBY
           elsif options[:type] == :array
             class_eval <<-RUBY, __FILE__, __LINE__ + 1
               def serialize_#{name}(buffer)
                 #{name}.each do |document|
-                  BSON::Document.serialize(document, buffer)
+                  buffer << document.to_bson
                 end
               end
             RUBY
           else
             class_eval <<-RUBY, __FILE__, __LINE__ + 1
               def serialize_#{name}(buffer)
-                BSON::Document.serialize(#{name}, buffer)
+                buffer << #{name}.to_bson
               end
             RUBY
           end
@@ -277,14 +312,12 @@ module Moped
           class_eval <<-EOS, __FILE__, __LINE__ + 1
             def serialize(buffer = "")
               start = buffer.bytesize
-
               #{fields.map { |f| "serialize_#{f}(buffer)" }.join("\n")}
-
               self.length = buffer.bytesize - start
-              buffer[start, 4] = serialize_length ""
+              buffer[start, 4] = serialize_length("")
               buffer
             end
-            alias to_s serialize
+            alias :to_s :serialize
           EOS
         end
 
@@ -294,44 +327,9 @@ module Moped
         # identical fields.
         def inherited(subclass)
           super
-
-          subclass.fields.replace fields
-        end
-
-      end
-
-      # Default implementation for a message is to do nothing when receiving
-      # replies.
-      #
-      # @example Receive replies.
-      #   message.receive_replies(connection)
-      #
-      # @param [ Connection ] connection The connection.
-      #
-      # @since 1.0.0
-      #
-      # @return [ nil ] nil.
-      def receive_replies(connection); end
-
-      # Serializes the message and all of its fields to a new buffer or to the
-      # provided buffer.
-      #
-      # @param [String] buffer a buffer to serialize to
-      # @return [String] the result of serliazing this message
-      def serialize(buffer = "")
-        raise NotImplementedError, "This method is generated after calling #finalize on a message class"
-      end
-      alias to_s serialize
-
-      # @return [String] the nicely formatted version of the message
-      def inspect
-        fields = self.class.fields.map do |field|
-          "@#{field}=" + __send__(field).inspect
+          subclass.fields.replace(fields)
         end
-        "#<#{self.class.name}\n" <<
-        "  #{fields * "\n  "}>"
       end
-
     end
   end
 end

data/lib/moped/protocol/query.rb

@@ -1,123 +1,174 @@
 module Moped
   module Protocol
+
     # The Protocol class for querying a collection.
     #
-    # @example Find all users named John
-    #   Query.new "moped", "users", { name: "John" }
-    #
-    # @example Find all users named John skipping 5 and returning 10
-    #   Query.new "moped", "users", { name: "John" },
-    #     skip: 5, limit: 10
-    #
-    # @example Find all users on slave node
-    #   Query.new "moped", "users", {}, flags: [:slave_ok]
-    #
-    # @example Find all user ids
-    #   Query.new "moped", "users", {}, fields: { _id: 1 }
-    #
+    # @since 1.0.0
     class Query
       include Message
 
-      # @attribute
-      # @return [Number] the length of the message
+      # @!attribute length
+      #   @return [ Integer ] the length of the message
       int32 :length
 
-      # @attribute
-      # @return [Number] the request id of the message
+      # @!attribute request_id
+      #   @return [ Integer ] the request id of the message
       int32 :request_id
 
       int32 :response_to
 
-      # @attribute
-      # @return [Number] the operation code of this message
+      # @!attribute op_code
+      #   @return [ Integer ] the operation code of this message
       int32 :op_code
 
-      # @attribute
+      # @!attribute
       # The flags for the query. Supported flags are: +:tailable+, +:slave_ok+,
       # +:no_cursor_timeout+, +:await_data+, +:exhaust+.
       #
-      # @param  [Array] flags the flags for this message
-      # @return [Array] the flags for this message
-      flags    :flags, tailable:          2 ** 1,
-                       slave_ok:          2 ** 2,
-                       no_cursor_timeout: 2 ** 4,
-                       await_data:        2 ** 5,
-                       exhaust:           2 ** 6
-
-      # @attribute
-      # @return [String] the namespaced collection name
-      cstring  :full_collection_name
-
-      # @attribute
-      # @return [Number] the number of documents to skip
-      int32    :skip
-
-      # @attribute
-      # @return [Number] the number of documents to return
-      int32    :limit
-
-      # @attribute
-      # @return [Hash] the selector for this query
+      # @param  [ Array ] flags the flags for this message
+      # @return [ Array ] the flags for this message
+      flags :flags, tailable:          2 ** 1,
+                    slave_ok:          2 ** 2,
+                    no_cursor_timeout: 2 ** 4,
+                    await_data:        2 ** 5,
+                    exhaust:           2 ** 6
+
+      # @!attribute full_collection_name
+      #   @return [ String ] the namespaced collection name
+      cstring :full_collection_name
+
+      # @!attribute skip
+      #   @return [ Integer ] the number of documents to skip
+      int32 :skip
+
+      # @!attribute limit
+      #   @return [ Integer ] the number of documents to return
+      int32 :limit
+
+      # @!attribute selector
+      #   @return [ Hash ] the selector for this query
       document :selector
 
-      # @attribute
-      # @return [Hash, nil] the fields to include in the reply
+      # @!attribute fields
+      #   @return [ Hash, nil ] the fields to include in the reply
       document :fields, :optional => true
 
       finalize
 
-      undef op_code
-      # @return [Number] OP_QUERY operation code (2004)
-      def op_code
-        2004
-      end
+      # @!attribute collection
+      #   @return [ String ] The collection to query.
+      # @!attribute database
+      #   @return [ String ] The database to query
+      attr_reader :collection, :database
 
-      # @return [String, Symbol] the database to query
-      attr_reader :database
+      # @!attribute batch_size
+      #   @return [ Integer ] The batch size of the results.
+      attr_accessor :batch_size
 
-      # @return [String, Symbol] the collection to query
-      attr_reader :collection
+      # Get the basic selector.
+      #
+      # @example Get the basic selector.
+      #   query.basic_selector
+      #
+      # @note Sometimes, like in cases of deletion we need this since MongoDB
+      #   does not understand $query in operations like DELETE.
+      #
+      # @return [ Hash ] The basic selector.
+      #
+      # @since 2.0.0
+      def basic_selector
+        selector["$query"] || selector
+      end
 
-      attr_accessor :batch_size
+      # Get the exception specific to a failure of this particular operation.
+      #
+      # @example Get the failure exception.
+      #   query.failure_exception(document)
+      #
+      # @param [ Moped::Protocol::Reply ] reply The reply from the database.
+      #
+      # @return [ Moped::Errors::QueryFailure ] The failure exception.
+      #
+      # @since 2.0.0
+      def failure_exception(reply)
+        Errors::QueryFailure.new(self, reply.documents.first)
+      end
+
+      # Determine if the provided reply message is a failure with respect to a
+      # query.
+      #
+      # @example Is the reply a query failure?
+      #   query.failure?(reply)
+      #
+      # @param [ Reply ] reply The reply to the query.
+      #
+      # @return [ true, false ] If the reply is a failure.
+      #
+      # @since 2.0.0
+      def failure?(reply)
+        reply.query_failure?
+      end
 
+      # Set the option on the query to not timeout the cursor.
+      #
+      # @example Set the no timeout option.
+      #   query.no_timeout = true
+      #
+      # @param [ true, false ] enable Whether to enable the no timeout option.
+      #
+      # @since 1.3.0
       def no_timeout=(enable)
         @flags |= [:no_cursor_timeout] if enable
       end
 
-      # Create a new query command.
-      #
-      # @example
-      #   Query.new "moped", "users", { name: "John" },
-      #     skip: 5,
-      #     limit: 10,
-      #     request_id: 12930,
-      #     fields: { _id: -1, name: 1 }
-      #
-      # @param [String, Symbol] database the database to insert into
-      # @param [String, Symbol] collection the collection to insert into
-      # @param [Hash] selector the query
-      # @param [Hash] options additional options
-      # @option options [Number] :request_id the command's request id
-      # @option options [Number] :skip the number of documents to skip
-      # @option options [Number] :limit the number of documents to return
-      # @option options [Hash] :fields the fields to return
-      # @option options [Array] :flags the flags for querying. Supported
-      #   flags: +:tailable+, +:slave_ok+, +:no_cursor_timeout+, +:await_data+,
-      #   +:exhaust+.
+      # Instantiate a new query operation.
+      #
+      # @example Find all users named John.
+      #   Query.new("moped", "users", { name: "John" })
+      #
+      # @example Find all users named John skipping 5 and returning 10.
+      #   Query.new("moped", "users", { name: "John" }, skip: 5, limit: 10)
+      #
+      # @example Find all users on slave node.
+      #   Query.new("moped", "users", {}, flags: [ :slave_ok ])
+      #
+      # @example Find all user ids.
+      #   Query.new("moped", "users", {}, fields: { _id: 1 })
+      #
+      # @param [ String, Symbol ] database The database to query.
+      # @param [ String, Symbol ] collection The collection to query.
+      # @param [ Hash ] selector The query selector.
+      # @param [ Hash ] options The additional query options.
+      #
+      # @option options [ Integer ] :request_id The operation's request id.
+      # @option options [ Integer ] :skip The number of documents to skip.
+      # @option options [ Integer ] :limit The number of documents to return.
+      # @option options [ Hash ] :fields The limited fields to return.
+      # @option options [ Array ] :flags The flags for querying. Supported flags
+      #   are: :tailable, :slave_ok, :no_cursor_timeout, :await_data, :exhaust.
+      #
+      # @since 1.0.0
       def initialize(database, collection, selector, options = {})
         @database = database
         @collection = collection
-
         @full_collection_name = "#{database}.#{collection}"
-        @selector             = selector
-        @request_id           = options[:request_id]
-        @flags                = options[:flags] || []
-        @limit                = options[:limit]
-        @skip                 = options[:skip]
-        @fields               = options[:fields]
-        @batch_size           = options[:batch_size]
+        @selector = selector
+        @request_id = options[:request_id]
+        @flags = options[:flags] || []
+        @limit = options[:limit]
+        @skip = options[:skip]
+        @fields = options[:fields]
+        @batch_size = options[:batch_size]
       end
 
+      # Provide the value that will be logged when the query runs.
+      #
+      # @example Provide the log inspection.
+      #   query.log_inspect
+      #
+      # @return [ String ] The string value for logging.
+      #
+      # @since 1.0.0
       def log_inspect
         type = "QUERY"
         fields = []
@@ -134,19 +185,18 @@ module Moped
         f.join(" ") % v
       end
 
-      # Get the basic selector.
-      #
-      # @example Get the basic selector.
-      #   query.basic_selector
+      undef op_code
+
+      # Get the code for a query operation.
       #
-      # @note Sometimes, like in cases of deletion we need this since MongoDB
-      # does not understand $query in operations like DELETE.
+      # @example Get the operation code.
+      #   query.op_code
       #
-      # @return [ Hash ] The basic selector.
+      # @return [ Integer ] OP_QUERY operation code (2004).
       #
-      # @since 2.0.0
-      def basic_selector
-        selector["$query"] || selector
+      # @since 1.0.0
+      def op_code
+        2004
       end
 
       # Receive replies to the message.
@@ -162,6 +212,39 @@ module Moped
       def receive_replies(connection)
         connection.read
       end
+
+      # Take the provided reply and return the expected results to api
+      # consumers.
+      #
+      # @example Get the expected results of the reply.
+      #   query.results(reply)
+      #
+      # @param [ Moped::Protocol::Reply ] reply The reply from the database.
+      #
+      # @return [ Moped::Protocol::Reply ] The reply.
+      #
+      # @since 2.0.0
+      def results(reply)
+        reply
+      end
+
+      private
+
+      # Duplicate the attributes in the query that need to be.
+      #
+      # @api private
+      #
+      # @example Clone the query.
+      #   query.clone
+      #
+      # @param [ Query ] The query that was cloned from.
+      #
+      # @since 2.0.0
+      def initialize_copy(_)
+        @selector = selector.dup
+        @flags = flags.dup
+        @fields = fields.dup if fields
+      end
     end
   end
 end