eson-core 0.7.0 → 0.8.0

data/lib/eson/error.rb

@@ -1,14 +1,22 @@
 module Eson
+  # Special error class for errors happening in the Eson context. In contrast
+  # to StandardErrors, this error also holds the response associated with this
+  # Error.
   class Error < StandardError
     attr_accessor :response
     
+    #
+    # @param [String] msg The error message
+    # @param [Object] response The raw response object.
     def initialize(msg, response)
-      super(msg)
+      super(response.body)
       
       self.response = response
     end
   end
-  
+
+  # Error class that indicates a missing document.
   NotFoundError = Class.new(Error)
+  # Error class that indicates a missing index.
   IndexNotFoundError = Class.new(NotFoundError)
 end

data/lib/eson/request.rb

@@ -1,9 +1,18 @@
 module Eson
+  # A request is a generic object that implements parameter manipulation
+  # methods and Esons plugin API. It is always bound to a client.
+  #
+  # This class cannot be used directly but must be subclassed by protocol
+  # implementations. Proper implementations must respond to `#call`.
+  #
+  # @example constructing a request by hand
+  #   r = protocol::Request.new(protocol::IndexExists, [ResponseParser], client)
   class Request
     attr_accessor :api, :client
 
     attr_accessor :pretty, :source, :index, :indices, :case
 
+    
     def initialize(api, plugins, client)
       self.api = api
       self.client = client
@@ -16,11 +25,35 @@ module Eson
       end
     end
 
+    # This is a default implementation of `handle_block` that can be overriden
+    # by apis or plugins.
+    #
+    # @yield self
     def handle_block
       yield self
     end
 
-    def params=(params)
+    # This is an internal method that allows the client to set default
+    # parameters to requests without having to check for the presence of the
+    # method beforehand.
+    #
+    # @api internal
+    def set_parameters_without_exceptions(params)
+      params.each do |k,v|
+        begin
+          self.send("#{k}=", v)
+        rescue NoMethodError => e
+          #drop
+        end
+      end
+    end
+
+    # Mass assignment of parameters to a request. Invalid parameters will
+    # raise an exception.
+    #
+    # @param [Hash] params The parameters, keyed by name
+    # @raise [NoMethodError]
+    def parameters=(params)
       params.each do |k,v|
         begin
           self.send("#{k}=", v)
@@ -30,6 +63,17 @@ module Eson
       end
     end
 
+    # Checks whether a Plugin works with a certain type of request. For example,
+    # Search plugins usually only work with Search requests. The decision is up
+    # to the plugin. If the plugin does not list a set of APIs that it works
+    # with, it will be considered compatible to all.
+    #
+    # @param [Eson::Api] api the api in question
+    # @param [Module] plugin the plugin module
+    # @param [Eson::Client] client the client to which the plugin should be added
+    #
+    # @return [true,false] Whether the plugin is compatible or not.
+    # @api internal
     def pluggable?(api, plugin, client)
       if plugin.respond_to? :plugin_for
         plugin.plugin_for(client.protocol).include?(api)
@@ -64,8 +108,9 @@ module Eson
       @source || source_from_params
     end
 
-    # TODO: woah, this needs refactoring
-
+    # Extracts the source parameters from the parameter set.
+    #
+    # @return [String] the request source, as String
     def source_from_params
       return nil unless self.respond_to? :source_param
 
@@ -77,27 +122,23 @@ module Eson
           return encode(obj)
         end
       else
-        pairs = source_param.map do |p|
+        obj = {}
+        source_param.each_with_object(obj) do |p, o|
           if v = self.send(p)
-            [p, v]
-          else
-            nil
+            o[p] = v
           end
         end
-        pairs.compact!
-
-        return nil if pairs.empty?
-
-        obj = {}
-
-        pairs.each do |p, v|
-          obj[p] = v
-        end
 
+        return nil if obj.empty?
         return encode(obj)
       end
     end
 
+    # Encode any object. If it is an {Eson}-Object and responds to 
+    # `to_query_hash`, this will be preferred. Otherwise, MultiJson is used.
+    #
+    # @param [Object] obj the object to encode
+    # @return [String] the object, encoded as JSON
     def encode(obj)
       if obj.respond_to? :to_query_hash
         obj = obj.to_query_hash

data/lib/eson/shared/cluster/health.rb

@@ -1,16 +1,23 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Health#parameters}
+    # {include:Health#source_param}
+    # {include:Health#multi_index}
+    # {include:Health#multi_types}
     module Health
       extend API
       
+      # @!macro multi_index
       multi_index true
-      
+
+      # @!macro parameters
       parameters :wait_for_status,
                  :level,
                  :wait_for_relocating_shards,
                  :wait_for_nodes,
                  :timeout
-      
     end
   end
 end

data/lib/eson/shared/cluster/nodes.rb

@@ -1,10 +1,18 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Nodes#parameters}
+    # {include:Nodes#source_param}
+    # {include:Nodes#multi_index}
+    # {include:Nodes#multi_types}
     module Nodes
       extend API
       
+      # @!macro no_multi_index
       multi_index false
       
+      # @!macro parameters
       parameters :nodes
       
       def nodes
@@ -12,4 +20,4 @@ module Eson
       end
     end
   end
-end
+end

data/lib/eson/shared/cluster/shutdown.rb

@@ -1,11 +1,19 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Shutdown#parameters}
+    # {include:Shutdown#source_param}
+    # {include:Shutdown#multi_index}
+    # {include:Shutdown#multi_types}
     module Shutdown
       #TODO fully implement and test this
       extend API
       
+      # @!macro no_multi_index
       multi_index false
 
+      # @!macro parameters
       parameters :nodes,
                  :delay,
                  :master,
@@ -17,4 +25,4 @@ module Eson
       end
     end
   end
-end
+end

data/lib/eson/shared/cluster/state.rb

@@ -1,11 +1,19 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:State#parameters}
+    # {include:State#source_param}
+    # {include:State#multi_index}
+    # {include:State#multi_types}
     module State
       extend API
       #TODO implement filter_indices correctly
       
+      # @!macro multi_index
       multi_index true
       
+      # @!macro parameters
       parameters :filter_nodes,
                  :filter_routing_table,
                  :filter_metadata,
@@ -14,4 +22,4 @@ module Eson
             
     end
   end
-end
+end

data/lib/eson/shared/cluster/stats.rb

@@ -1,10 +1,18 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Stats#parameters}
+    # {include:Stats#source_param}
+    # {include:Stats#multi_index}
+    # {include:Stats#multi_types}
     module Stats
       extend API
       
+      # @!macro no_multi_index
       multi_index false
       
+      # @!macro parameters
       parameters :nodes
       
       def nodes
@@ -12,4 +20,4 @@ module Eson
       end
     end
   end
-end
+end

data/lib/eson/shared/core/bulk.rb

@@ -1,9 +1,17 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Bulk#parameters}
+    # {include:Bulk#source_param}
+    # {include:Bulk#multi_index}
+    # {include:Bulk#multi_types}
     module Bulk
       extend API
 
+      # @!macro source_param
       source_param :bulk
+      # @!macro parameters
       parameters :bulk
 
       def bulk
@@ -23,4 +31,4 @@ module Eson
       end
     end
   end
-end
+end

data/lib/eson/shared/core/count.rb

@@ -1,12 +1,20 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # @note {include:Count#parameters}
+    # @note {include:Count#source_param}
+    # @note {include:Count#multi_index}
+    # @note {include:Count#multi_types}
     module Count
       extend API
       
       attr_accessor :type
       
+      # @!macro multi_index
       multi_index true
       
+      # @!macro source_param
       source_param :query,
                    :timeout,
                    :from,
@@ -23,6 +31,7 @@ module Eson
                    :version,
                    :min_score
                    
+      # @!macro parameters
       parameters :timeout, 
                  :types, 
                  :routing,
@@ -60,4 +69,4 @@ module Eson
       
     end
   end
-end
+end

data/lib/eson/shared/core/delete.rb

@@ -1,12 +1,21 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Delete#parameters}
+    # {include:Delete#source_param}
+    # {include:Delete#multi_index}
+    # {include:Delete#multi_types}
     module Delete
       extend API
       
+      # @!macro no_multi_index
       multi_index false
       
+      # @!macro source_param
       source_param :item
       
+      # @!macro parameters
       parameters(
         :type, 
         :id,
@@ -23,4 +32,4 @@ module Eson
       )  
     end
   end
-end
+end

data/lib/eson/shared/core/delete_by_query.rb

@@ -1,15 +1,24 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # @note {include:DeleteByQuery#parameters}
+    # @note {include:DeleteByQuery#source_param}
+    # @note {include:DeleteByQuery#multi_index}
+    # @note {include:DeleteByQuery#multi_types}
     module DeleteByQuery
       extend API
 
       attr_accessor :type
 
+      # @!macro multi_index
       multi_index true
 
+      # @!macro source_param
       source_param :query
       
       # TODO: check the parameter list
+      # @!macro parameters
       parameters :timeout, 
                  :types, 
                  :routing,
@@ -47,4 +56,4 @@ module Eson
       
     end
   end
-end
+end

data/lib/eson/shared/core/explain.rb

@@ -0,0 +1,44 @@
+module Eson
+  module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Explain#parameters}
+    # {include:Explain#source_param}
+    # {include:Explain#multi_index}
+    # {include:Explain#multi_types}
+    module Explain
+      extend API
+
+      # @!macro multi_index
+      multi_index false
+
+      # @!macro multi_types
+      multi_types false
+
+  
+      # @!macro source_param
+      source_param :query,
+                   :fields,
+                   :facets,
+                   :filter
+      
+      # @!macro parameters
+      parameters :id,
+                 :type,
+                 :query,
+                 :routing,
+                 :parent,
+                 :preference,
+                 :q,
+                 :df,
+                 :analyzer,
+                 :analyze_wildcard,
+                 :lowercase_expanded_terms,
+                 :lenient,
+                 :default_operator,
+                 :fields,
+                 :facets,
+                 :filter
+    end
+  end
+end

data/lib/eson/shared/core/get.rb

@@ -1,10 +1,18 @@
 module Eson
   module Shared
+    # Requests using this API have the following properties:
+    #
+    # {include:Get#parameters}
+    # {include:Get#source_param}
+    # {include:Get#multi_index}
+    # {include:Get#multi_types}
     module Get
       extend API
             
+      # @!macro no_multi_index
       multi_index false
       
+      # @!macro parameters
       parameters(
         :id, 
         :type,
@@ -16,4 +24,4 @@ module Eson
       
     end
   end
-end
+end