aws_sdk 3.1.5

data/lib/aws/core/client/query_json.rb

@@ -0,0 +1,110 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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 AWS
+  module Core
+    class Client
+
+      # When a client class extends this module, its API configuration is
+      # parsed.  For each operation in the API configuration, one client
+      # method is added.
+      #
+      # Clients extending QueryJSON all have in common their method of
+      # serializing request (input) parameters and parsing response
+      # (output) JSON.
+      #
+      module QueryJSON
+          
+        def self.extended base
+          base.send(:include, ErrorParser)
+          base.send(:define_client_methods)
+        end
+  
+        # @return [Hash<Symbol,OptionGrammar>] Returns a hash option
+        #   parsers.  Hash keys are client method names and hash
+        #   values are {OptionGrammar} objects.
+        # @private
+        def option_parsers
+          @option_parsers ||= {}
+        end
+  
+        protected
+  
+        # Enumerates through the operations specified in the API 
+        # configuration (yaml configuration file found in lib/api_config/)
+        # and defines one request method per operation.
+        def define_client_methods
+          api_config[:operations].each do |op|
+  
+            method_name = op[:method]
+  
+            option_parsers[method_name] = OptionGrammar.customize(op[:inputs])
+  
+          end
+        end
+  
+        def define_client_method method_name, operation
+          add_client_request_method(method_name) do
+  
+            configure_request do |request, options|
+
+              parser = self.class.option_parsers[method_name]
+              x_amz_target = self.class::TARGET_PREFIX + operation
+
+              request.headers["content-type"] = "application/x-amz-json-1.0"
+              request.headers["x-amz-target"] = x_amz_target
+              request.body = parser.to_json(options)
+
+            end
+  
+            process_response do |response|
+              response_body = response.http_response.body
+              response_body = "{}" if response_body == ""
+              data = JSON.load(response_body)
+              MetaUtils.extend_method(response, :data) { data }
+            end
+  
+            simulate_response do |response|
+              data = {}
+              MetaUtils.extend_method(response, :data) { data }
+            end
+  
+          end
+        end
+  
+        module ErrorParser
+  
+          def extract_error_details response
+            if 
+              response.http_response.status >= 300 and
+              body = response.http_response.body and
+              json = (JSON.load(body) rescue nil) and
+              type = json["__type"] and
+              matches = type.match(/\#(.*)$/)
+            then
+              code = matches[1]
+              if code == 'RequestEntityTooLarge'
+                message = 'Request body must be less than 1 MB'
+              else
+                message = json['message']
+              end
+              [code, message]
+            end
+          end
+  
+        end
+
+      end
+    end
+  end
+end

data/lib/aws/core/client/query_xml.rb

@@ -0,0 +1,122 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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 AWS
+  module Core
+    class Client
+
+      # When a client class extends this module, its API configuration
+      # is parsed.  For each operation in the API configuration, one
+      # client method is added.
+      #
+      # Clients extending QueryXML all have in common their method
+      # of serializing request (input) paramters and parsing response
+      # (output) XML.
+      #
+      module QueryXML
+        
+        # @private
+        def self.extended base
+          base.send(:include, ErrorParser)
+          base.send(:define_parsers)
+        end
+  
+        # @return [Hash<Symbol,OptionGrammar>] Returns a hash option
+        #   parsers.  Hash keys are client method names and hash
+        #   values are {OptionGrammar} objects.
+        # @private
+        def option_parsers
+          @option_parsers ||= {}
+        end
+  
+        # @return [Hash<Symbol,XML::Parser>] Returns a hash of xml
+        #   parsers.  Hash keys are client method names and hash
+        #   values are {XML::Parser} objects.
+        # @private
+        def xml_parsers
+          @xml_parsers ||= {}
+        end
+  
+        protected
+  
+        # Enumerates through the operations specified in the API 
+        # configuration (yaml configuration file found in lib/api_config/)
+        # and defines one request method per operation.
+        def define_parsers
+          api_config[:operations].each do |op|
+  
+            method_name = op[:method]
+  
+            option_parsers[method_name] = OptionGrammar.customize(op[:inputs])
+            xml_parsers[method_name] = XML::Parser.new(op[:outputs])
+  
+          end
+        end
+  
+        def define_client_method method_name, operation_name
+          add_client_request_method(method_name) do
+  
+            configure_request do |request, options|
+  
+              now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+  
+              request.headers['Content-Type'] = 
+                'application/x-www-form-urlencoded; charset=utf-8'
+  
+              request.http_method = 'POST'
+              request.add_param 'Timestamp', now
+              request.add_param 'Version', self.class::API_VERSION
+              request.add_param 'Action', operation_name
+  
+              parser = self.class.option_parsers[method_name]
+              parser.request_params(options).each do |param|
+                request.add_param(param)
+              end
+  
+            end
+  
+            process_response do |response|
+              parser = self.class.xml_parsers[method_name]
+              response.data = parser.parse(response.http_response.body)
+            end
+  
+            simulate_response do |response|
+              parser = self.class.xml_parsers[method_name]
+              response.data = parser.simulate
+            end
+  
+          end
+        end
+  
+        module ErrorParser
+  
+          protected
+  
+          def extract_error_details response
+            if 
+              response.http_response.status >= 300 and
+              body = response.http_response.body and
+              error = errors_module::GRAMMAR.parse(body) and
+              error[:code]
+            then
+              [error[:code], error[:message]]
+            end
+          end
+          
+        end
+
+      end
+    end
+  end
+end
+

data/lib/aws/core/collection.rb

@@ -0,0 +1,234 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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 AWS
+  module Core
+
+    # = Different Collection Types in AWS
+    #
+    # The Collection module acts as a namespace and base implementation for
+    # the primary collection types in AWS:
+    #
+    # * {AWS::Core::Collection::Simple}
+    # * {AWS::Core::Collection::Limitable}
+    #
+    # Each AWS service allows provides a method to enumerate resources.
+    #
+    # * Services that return all results in a single response use
+    #   {AWS::Core::Collection::Simple}.
+    #
+    # * Services that truncate large results sets *AND* allow you to provide
+    #   a perfered maximum number of results use 
+    #   {AWS::Core::Collection::Limitable}.
+    #
+    module Collection
+
+      AWS.register_autoloads(self) do
+        autoload :Simple,    'simple'
+        autoload :Limitable, 'limitable'
+      end
+
+      include Enumerable
+  
+      # Yields once for every item in this collection.
+      #
+      #   collection.each {|item| ... }
+      #
+      # @note If you want fewer than all items, it is generally better 
+      #   to call {#page} than {#each} with a +:limit+.
+      #
+      # @param [Hash] options
+      #
+      # @option options [Integer] :limit (nil) The maximum number of
+      #   items to enumerate from this collection.
+      #
+      # @option options [next_token] :next_token (nil) 
+      #   Acts as an offset.  +:next_token+ may be returned by {#each} and
+      #   {#each_batch} when a +:limit+ is provided.
+      #
+      # @return [nil_or_next_token] Returns nil if all items were enumerated.
+      #   If some items were excluded because of a +:limit+ option then
+      #   a +next_token+ is returned.  Calling an enumerable method on 
+      #   the same collection with the +next_token+ acts like an offset.
+      #
+      def each options = {}, &block
+        each_batch(options) do |batch|
+          batch.each(&block)
+        end
+      end
+
+      # Yields items from this collection in batches.
+      #
+      #   collection.each_batch do |batch|
+      #     batch.each do |item|
+      #       # ...
+      #     end
+      #   end
+      #
+      # == Variable Batch Sizes
+      #
+      # Each AWS service has its own rules on how it returns results.
+      # Because of this batch size may very based on:
+      #
+      # * Service limits (e.g. S3 limits keys to 1000 per response)
+      #
+      # * The size of response objects (SimpleDB limits responses to 1MB)
+      #
+      # * Time to process the request
+      #
+      # Because of these variables, batch sizes may not be consistent for
+      # a single collection.  Each batch represents all of the items returned
+      # in a single resopnse.
+      #
+      # @note If you require fixed size batches, see {#in_groups_of}.
+      #
+      # @param (see #each)
+      #
+      # @option (see #each)
+      #
+      # @return (see #each)
+      #
+      def each_batch options = {}, &block
+        raise NotImplementedError
+      end
+
+      # Use this method when you want to call a method provided by 
+      # Enumerable, but you need to pass options:
+      #
+      #   # raises an error because collect does not accept arguments
+      #   collection.collect(:limit => 10) {|i| i.name }
+      #
+      #   # not an issue with the enum method
+      #   collection.enum(:limit => 10).collect(&:name)
+      #
+      # @param (see #each)
+      #
+      # @option (see #each)
+      #
+      # @return [Enumerable::Enumerator] Returns an enumerator for this
+      #   collection.
+      #
+      def enum options = {}
+        Enumerator.new(self, :each, options) 
+      end
+      alias_method :enumerator, :enum
+
+      # Returns the first item from this collection.
+      #
+      # @return [item_or_nil] Returns the first item from this collection or
+      #   nil if the collection is empty.
+      #
+      def first options = {}
+        enum(options.merge(:limit => 1)).first
+      end
+
+      # Yields items from this collection in groups of an exact
+      # size (except for perhaps the last group). 
+      #
+      #   collection.in_groups_of (10, :limit => 30) do |group|
+      #
+      #     # each group should be exactly 10 items unless
+      #     # fewer than 30 items are returned by the service
+      #     group.each do |item|
+      #       #...
+      #     end
+      #
+      #   end
+      #   
+      # @param [Integer] size Size each each group of objects
+      #   should be yielded in.
+      # @param [Hash] options
+      # @option (see #each)
+      # @return (see #each)
+      def in_groups_of size, options = {}, &block
+
+        group = []
+
+        nil_or_next_token = each_batch(options) do |batch|
+          batch.each do |item|
+            group << item
+            if group.size == size
+              yield(group)
+              group = []
+            end
+          end
+        end
+
+        yield(group) unless group.empty?
+
+        nil_or_next_token
+
+      end
+
+      # Returns a single page of results in a kind-of array ({PageResult}).
+      #
+      #   items = collection.page(:per_page => 10) # defaults to 10 items
+      #   items.is_a?(Array) # => true
+      #   items.size         # => 8
+      #   items.per_page     # => 10
+      #   items.last_page?   # => true
+      #
+      # If you need to display a "next page" link in a web view you can
+      # use the #more? method.  Just make sure the generated link
+      # contains the +next_token+.
+      #
+      #   <% if items.more? %>
+      #     <%= link_to('Next Page', params.merge(:next_token => items.next_token) %>
+      #   <% end %>
+      #
+      # Then in your controller you can find the next page of results:
+      #
+      #   items = collection.page(:next_token => params[:next_token])
+      #
+      # Given a {PageResult} you can also get more results directly:
+      #
+      #   more_items = items.next_page
+      #
+      # @note This method does not accept a +:page+ option, which means you
+      #   can only start at the begining of the collection and request
+      #   the next page of results.  You can not choose an offset
+      #   or know how many pages of results there will be.
+      #
+      # @param [Hash] options A hash of options that modifies the
+      #   items returned in the page of results.
+      #
+      # @option options [Integer] :per_page (10) The number of results
+      #   to return for each page.
+      #
+      # @option options [String] :next_token (nil) A token that indicates
+      #   an offset to use when paging items.  Next tokens are returned
+      #   by {PageResult#next_token}.  
+      #
+      #   Next tokens should only be consumed by the same collection that
+      #   created them.
+      #
+      def page options = {}
+        
+        each_opts = options.dup
+
+        per_page = each_opts.delete(:per_page)
+        per_page = [nil,''].include?(per_page) ? 10 : per_page.to_i
+
+        each_opts[:limit] = per_page
+
+        items = []
+        next_token = each(each_opts) do |item|
+          items << item
+        end
+
+        Core::PageResult.new(self, items, per_page, next_token)
+
+      end
+  
+    end
+  end
+end