aws-sdk 1.4.1 → 1.5.0

data/lib/aws/core/http/request.rb

@@ -15,7 +15,10 @@ module AWS
   module Core
     module Http
   
-      # Base class for all service reqeusts.
+      # Base class for all service reqeusts.  This class describes
+      # a basic HTTP request, but will not make one.  It is consumed
+      # by a HTTP handler class that sends the actual request
+      # and parses the actual response.
       class Request
   
         # Returns a new empty http request object.
@@ -67,9 +70,9 @@ module AWS
         #   to be populated for requests against signature v4 endpoints.
         attr_accessor :region
   
-        # @param [Boolean] ssl If the request should be sent over ssl or not.
-        def use_ssl= use_ssl
-          @use_ssl = use_ssl
+        # @param [Boolean] state If the request should be sent over ssl or not.
+        def use_ssl= state
+          @use_ssl = state
         end
   
         # @return [Boolean] If this request should be sent over ssl or not.

data/lib/aws/core/lazy_error_classes.rb

@@ -16,53 +16,75 @@ require 'thread'
 module AWS
   module Core
 
-    # @private
+    # Provides lazy creation of error classes via {#const_missing}.  
+    #
+    # Extend this module provides 3 benefits to another module:
+    #
+    # * A method that accepts strings and returns error classes.
+    # * Thread-safe dynamic error class creation via {#const_missing}
+    # * An error grammar for parsing AWS xml errors
+    #
+    # Here is an example of how it works:
+    #
+    #  Class Foo 
+    #    module Errors
+    #      extend AWS::Core::LazyErrorClasses
+    #    end
+    #  end
+    #
+    #  Foo::Errors.error_class('NoSuchKey')
+    #  #=> Foo::Errors::NoSuckKey
+    #
+    #  Foo::Errors.error_class('Nested.Error.Klasses')
+    #  #=> Foo::Errors::Nested::Error::Klasses
+    #
+    # The errors returned from {#error_class} are subclasses
+    # of {AWS::Errors::Base}.
+    #
     module LazyErrorClasses
-  
-      # @private
-      module ClassMethods
-  
-        def const_missing(name)
-          base_error_grammar = self::BASE_ERROR_GRAMMAR
-          mod = self::ERROR_MODULE
-          const_missing_mutex.synchronize do
-            const_set(name,
-                      Class.new(self::Base) do
-                        include mod::ModeledError
 
-                        # so that MyService::Errors::Foo::Bar will work
-                        const_set(:BASE_ERROR_GRAMMAR, base_error_grammar)
-                        const_set(:ERROR_MODULE, mod)
-                        include LazyErrorClasses
-                      end)
-          end
-        end
-  
-        def error_class(code)
-          module_eval("#{self}::#{code.gsub('.Range','Range').gsub(".","::")}")
+      # This grammar parses the defualt AWS XML error format  
+      BASE_ERROR_GRAMMAR = XML::Grammar.customize do
+        element("Error") do
+          ignore
         end
-  
-        def included(mod)
-          raise NotImplementedError.new("#{self} lazy-generates error classes; "+
-                                        "therefore it is not suitable for "+
-                                        "inclusion in other modules")
+      end
+
+      # @private
+      def self.extended base
+
+        unless base.const_defined?(:GRAMMAR)
+          base.const_set(:GRAMMAR, BASE_ERROR_GRAMMAR)
         end
-  
+      
+        mutex = Mutex.new
+        MetaUtils.extend_method(base, :const_missing_mutex) { mutex }
+
       end
   
-      def self.included(mod)
-        unless mod.const_defined?(:BASE_ERROR_GRAMMAR)
-          mod.const_set(:BASE_ERROR_GRAMMAR, XmlGrammar)
-        end
-        unless mod.const_defined?(:ERROR_MODULE)
-          mod.const_set(:ERROR_MODULE, mod)
+      # Defines a new error class.
+      # @param [String,Symbol] constant
+      # @return [nil]
+      def const_missing constant
+        const_missing_mutex.synchronize do
+          const_set(constant, Class.new(Errors::Base) { extend LazyErrorClasses })
         end
-        mutex = Mutex.new
-        MetaUtils.extend_method(mod, :const_missing_mutex) { mutex }
-        mod.send(:include, Errors)
-        mod.extend(ClassMethods)
+      end
+
+      # Converts the error code into an error class constant.
+      #
+      #   AWS::EC2::Errors.error_class('Non.Existent.Error')
+      #   #=> AWS::EC2::Errors::Non::Existent::Error
+      # 
+      # @param [String] code An AWS error code.
+      #
+      # @return [Class] Returns the error class defiend by the error code.
+      #
+      def error_class code
+        module_eval("#{self}::#{code.gsub('.Range','Range').gsub(".","::")}")
       end
   
     end
+
   end
 end

data/lib/aws/core/option_grammar.rb

@@ -477,6 +477,7 @@ module AWS
           descriptors.each do |desc|
             if desc.kind_of?(Hash)
               (name, arg) = desc.to_a.first
+              next if name == :documentation
             else
               name = desc
               arg = nil

data/lib/aws/core/policy.rb

@@ -354,7 +354,7 @@ module AWS
         #   http://docs.amazonwebservices.com/AmazonS3/latest/dev/UsingResOpsConditions.html
         #   for a list of the available keys for each action in S3.
         #
-        # @param value The value to compare against.
+        # @param [Mixed] values The value to compare against.
         #   This can be:
         #   * a String
         #   * a number
@@ -362,6 +362,7 @@ module AWS
         #   * a boolean value
         #   This method does not attempt to validate that the values
         #   are valid for the operators or keys they are used with.
+        #
         def add(operator, key, *values)
           if operator.kind_of?(Symbol)
             converted_values = values.map { |v| convert_value(v) }

data/lib/aws/core/resource.rb

@@ -121,21 +121,31 @@ module AWS
       # @private
       public
       def attributes_from_response resp
-  
-        attributes = {}
-  
+
+        # check each provider for this request type to see if it
+        # can find the resource and some of its attributes
+        attributes = []
         self.class.attribute_providers_for(resp.request_type).each do |provider|
-          attributes.merge!(provider.attributes_from_response(self, resp))
+          attributes << provider.attributes_from_response(self, resp)
         end
+
+        # drop out those that returned no attributesj
+        attributes.compact!
+
+        # stop here if nothing was found for this resource
+        return nil if attributes.empty?
+
+        # merge the attributes together into a single hash
+        attributes = attributes.inject({}) {|hash,attribs| hash.merge(attribs) }
   
         # cache static attributes
-        attributes.each do |attr_name,value|
+        attributes.each_pair do |attr_name,value|
           if self.class.attributes[attr_name].static?
             static_attributes[attr_name] = value
           end
         end
-  
-        attributes.empty? ? nil : attributes
+
+        attributes
   
       end
   
@@ -347,15 +357,16 @@ module AWS
         # Indicates that all of the the named attributes can be retrieved
         # from an appropriate response object.
         # 
-        # @param [Symbol] attr_names A list of attributes provided
-        # @param [Hash] options
-        # @option options [Boolean] :value_wrapped (false) If true, then
-        #   the value returned by the response object will also receive
-        #   the message :value before it is translated and returned.
-        # @option options [Symbol] :get_as Defaults to the method named
-        #   by the attribute.  This is useful when you have two providers
-        #   for the same attribute but their response object name
-        #   them differently.
+        # @overload provides(*attr_names, options = {})
+        #   @param [Symbol] attr_names A list of attributes provided
+        #   @param [Hash] options
+        #   @option options [Boolean] :value_wrapped (false) If true, then
+        #     the value returned by the response object will also receive
+        #     the message :value before it is translated and returned.
+        #   @option options [Symbol] :get_as Defaults to the method named
+        #     by the attribute.  This is useful when you have two providers
+        #     for the same attribute but their response object name
+        #     them differently.
         def provides *attr_names
           options = attr_names.last.is_a?(Hash) ? attr_names.pop : {}
           attr_names.each do |attr_name|
@@ -369,32 +380,26 @@ module AWS
           if response_object = resource.send(finder_method, response)
             attributes_from_response_object(response_object)
           else
-            {}
+            nil
           end
         end
   
         def attributes_from_response_object resp_obj
-          attributes = {}
-          @provides.each do |attr_name, options|
-  
+          
+          @provides.inject({}) do |attributes,(attr_name,options)|
+
             attr = @klass.attributes[attr_name]
+
             method = options[:get_as] || attr.get_as
   
-            v = case
-            when resp_obj.respond_to?(:key?) && resp_obj.key?(method.to_s)
-              resp_obj[method.to_s]
-            when resp_obj.respond_to?(method)
-              resp_obj.send(method)
-            else
-              nil
-            end
-            v = v.value if v and options[:value_wrapped]
+            v = resp_obj.key?(method) ? resp_obj[method] : resp_obj[method.to_s]
+            v = v[:value] if v and options[:value_wrapped]
             v = attr.translate_output_value(v)
-  
-            attributes[attr_name] = v
-  
+
+            attributes.merge(attr_name => v)
+
           end
-          attributes
+  
         end
   
       end

data/lib/aws/core/response.rb

@@ -14,33 +14,76 @@
 module AWS
   module Core
 
-    # @private
+    # = Response
+    #
+    # Each service request returns a response object.  Responses provide
+    # access to response data and request/response metadata.
+    #
+    # == Response Data
+    #
+    # Each response has a hash of data that represents the data
+    # returned by the service.  You can get at this data by
+    # calling {#data} (you can also use the {#[]} method as a shortcut)
+    #
+    #   # make a request to describe one instance
+    #   ec2 = AWS::EC2.new
+    #   response = ec2.client.describe_instances(:instance_ids => ['i-12345678'])
+    #
+    #   # find the instance in the response data (2 ways to get the data)
+    #   instance = response[:reservation_set].first[:instance_set].first
+    #   instance = response.data[:reservation_set].first[:instance_set].first
+    #
+    #   instance[:status] #=> 'running'
+    # 
+    # == Response Metadata
+    #
+    # In addition to the response data, there is additional information
+    # available with the response, including:
+    #
+    # * the name of the client request method called
+    # * the hash of options passed to the client request
+    # * the HTTP request object (useful for debugging)
+    # * the HTTP response object (useful for debugging)
+    #
+    # Given the example and response object from above:
+    #
+    #   response.request_type #=> :describe_instances
+    #   response.request_options #=> { :instance_ids => ['i-12345678'] }
+    #   response.http_request #=> #<AWS::Core::Http::Request>
+    #   response.http_response #=> #<AWS::Core::Http::Response>
+    #
     class Response
   
       include AsyncHandle
+
+      # @return [Hash] Returns the response data as a hash.
+      attr_accessor :data
   
-      # @return [AWS::Error] Returns nil unless the request failed.
-      #   Normally this will be nil unless you are using the Asynchronous 
-      #   interface.
-      attr_accessor :error
+      # @return [Symbol] The name of the client request method that 
+      #   returned this response.
+      attr_accessor :request_type
       
-      # @return [Hash] The hash of options passed to the low level request 
-      #   method that generated this response.
+      # @return [Hash] Returns the hash of options passed to the client
+      #   request method that generated this response.
       attr_accessor :request_options
-  
-      # @return [Symbol] The low-level request method that generated
-      #   this response
-      attr_accessor :request_type
       
-      # @return [Http::Request] the HTTP request object 
+      # @return [Core::Http::Request]
       attr_accessor :http_request
   
-      # @return [Http::Response] the HTTP response object 
+      # @return [Core::Http::Response]
       attr_accessor :http_response
   
-      # @return [Boolean] true if the response is cached
+      # @return [Boolean] true if the response was generated from a
+      #   another cached response.
       attr_accessor :cached
 
+      alias_method :cached?, :cached
+  
+      # @return [AWS::Error,nil] Returns nil unless the request failed.
+      #   Normally this will be nil unless you are using the Asynchronous 
+      #   interface.
+      attr_accessor :error
+
       # @return [Integer] Returns the number of times the request
       #   was retried.
       attr_accessor :retry_count
@@ -50,22 +93,27 @@ module AWS
       attr_accessor :duration
   
       # @param [Http::Request] http_request
-      # @param [Http::Response] http_request
+      # @param [Http::Response] http_response
       def initialize http_request = nil, http_response = nil, &block
         @http_request = http_request
         @http_response = http_response
         @request_builder = block
+        @data = {}
         @retry_count = 0
         @duration = 0
         rebuild_request if @request_builder && !http_request
       end
-  
-      # Rebuilds the HTTP request using the block passed to the initializer
-      def rebuild_request
-        @http_request = @request_builder.call
+
+      # Provides access to the response data.  This is a short-cut
+      # for calling +response.data[key]+.
+      #
+      # @param [Symbol,String] key
+      # @return [Hash,nil]
+      def [] key
+        data[key]
       end
   
-      # @return [Boolean] Returns true unless there is a response error.
+      # @return [Boolean] Returns true if there is no response error.
       def successful?
         error.nil?
       end
@@ -74,9 +122,9 @@ module AWS
       #   by AWS.
       def throttled?
         if !successful? and http_response.body
-          error = XmlGrammar.parse(http_response.body)
-          error = error.error if error.respond_to?(:error)
-          error.respond_to?(:code) and error.code == "Throttling"
+          error = XML::Parser.new.parse(http_response.body)
+          error = error[:error] if error[:error]
+          error[:code] == "Throttling"
         else
           false
         end
@@ -87,49 +135,66 @@ module AWS
         http_response.timeout?
       end
   
+      # @return [String]
       # @private
       def inspect
-        if request_type
-          "<#{self.class}:#{request_type}>"
-        else
-          "<#{self.class}>"
-        end
+        data.inspect
       end
   
+      # @return [String]
+      # @private
       def cache_key
-        [http_request.access_key_id,
-         http_request.host,
-         request_type,
-         serialized_options].join(":")
+        [
+          http_request.access_key_id,
+          http_request.host,
+          request_type,
+          serialized_options
+        ].join(":")
+      end
+  
+      # Rebuilds the HTTP request using the block passed to the initializer.
+      # This is primarily used by the client when a request must be retried
+      # (throttling, server errors, socket errors, etc).
+      # @private
+      def rebuild_request
+        @http_request = @request_builder.call
+      end
+
+      protected
+
+      # @note The prefered method to get as response data is to use {#[]}.
+      # 
+      # This provides a backwards-compat layer to the old response objects
+      # where each response value had a method extended onto this object.
+      # Now all response data is accessible as a hash.
+      #
+      # @see #[]
+      # @see #data
+      #
+      def method_missing *args, &block
+        Core::Data.new(data).send(*args, &block)
       end
   
       def serialized_options
         serialize_options_hash(request_options)
       end
   
-      private
       def serialize_options_hash(hash)
         "(" + hash.keys.sort_by(&:to_s).map do |key|
           "#{key}=#{serialize_options_value(hash[key])}"
         end.join(" ") + ")"
       end
   
-      private
       def serialize_options_value(value)
         case value
-        when Hash
-          serialize_options_hash(value)
-        when Array
-          serialize_options_array(value)
-        else
-          value.inspect
+        when Hash  then serialize_options_hash(value)
+        when Array then serialize_options_array(value)
+        else value.inspect
         end
       end
   
-      private
-      def serialize_options_array(ary)
-        "[" + ary.map { |v| serialize_options_value(v) }.join(" ") +
-          "]"
+      def serialize_options_array array
+        "[" + array.map{|v| serialize_options_value(v) }.join(" ") + "]"
       end
   
     end