aws-sdk 1.2.6 → 1.3.0

data/lib/aws/dynamo_db/batch_get.rb

@@ -0,0 +1,206 @@
+# 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
+  class DynamoDB
+    
+    # A utility class for configuring a list of tables, attributes and
+    # items to request information for.
+    #
+    # @see DynamoDB#batch_get
+    # @see Table#batch_get
+    #
+    class BatchGet
+
+      include Keys
+      include Enumerable
+      include Core::Model
+
+      def initialize options = {}
+        super(options)
+        @request_items = {}
+      end
+
+      # Add a list of items to fetch in this batch.  
+      #
+      # @param [String] table_name The name of the table to fetch attributes
+      #   from.
+      #
+      # @param [Symbol, String, Array<String>] attributes The list of attributes
+      #   to fetch.  If you want to load *ALL* attributes for the named items,
+      #   then pass the symbol +:all+.
+      #
+      #     # get all attributes
+      #     batch_get.table('mytable', :all, items)
+      #
+      #     # get one attribute for each item
+      #     batch_get.table('mytable', ['name'], items)
+      #
+      #     # get a list of attributes for each item
+      #     batch_get.table('mytable', ['name', 'size'], items)
+      #
+      # @param [Array<Item,Array>] items One or more items to fetch attributes
+      #   for.  Each attribute should be one of the following:
+      #
+      #   * an {Item} object
+      #   * a hash key value
+      #   * a hash key value and a range key value
+      #
+      #   You must provide both the hash key and range key values if the table
+      #   schema has both.
+      #
+      #     batch_get.table('mytable', :all, [%w(hk1 rk1), %w(hk1 rk2), ...])
+      #
+      # @return [nil]
+      #
+      def table table, attributes, items
+
+        table = table.is_a?(Table) ? table.name : table.to_s
+
+        attributes = attributes == :all ? nil : [attributes].flatten
+
+        keys = items.collect do |item|
+          case item
+          when Item then item_key_hash(item)
+          when Array 
+            {
+              :hash_key_element => format_attribute_value(item[0]),
+              :range_key_element => format_attribute_value(item[1]),
+            }
+          else
+            { :hash_key_element => format_attribute_value(item) }
+          end
+        end
+
+        ## ensure we don't receive 2 different lists of attributes for
+        ## the same table
+
+        if 
+          @request_items.has_key?(table) and 
+          @request_items[table][:attributes_to_get] != attributes
+        then
+          msg = "When batch getting attributes, you may only provide " +
+            "1 list of attributes per table, but the `#{table}` table " +
+            "has received reqeusts for 2 different sets of attributes"
+          raise ArgumentError, msg
+        end
+
+        ## merge attributes and items with the request items
+
+        @request_items[table] ||= { :keys => [] } 
+        @request_items[table][:attributes_to_get] = attributes if attributes
+        @request_items[table][:keys] += keys
+
+        nil
+
+      end
+
+      # Specify a list of {Item} objects to batch fetch attributes for.
+      # The table name is retrieved from the items objects, this means
+      # the items do not need to belong to the same table.
+      #
+      # @param [Symbol, String, Array<String>] attributes The list of attributes
+      #   to fetch.  If you want to load *ALL* attributes for the named items,
+      #   then pass the symbol +:all+.
+      #
+      #     # get all attributes
+      #     batch_get.table('mytable', :all, items)
+      #
+      #     # get one attribute for each item
+      #     batch_get.table('mytable', ['name'], items)
+      #
+      #     # get a list of attributes for each item
+      #     batch_get.table('mytable', ['name', 'size'], items)
+      #
+      # @param [Item] items One or more {Item} objects to fetch attributes
+      #   for.  These items may come from any number of different tables.  
+      #
+      def items attributes, *items
+        [items].flatten.each do |item|
+          self.table(item.table, attributes, [item])
+        end
+      end
+
+      # @return [nil]
+      def each &block
+
+        options = { :request_items => @request_items }
+
+        begin
+
+          response = client.batch_get_item(options)
+
+          response.data['Responses'].each_pair do |table_name,details|
+            details['Items'].each do |hash_data|
+              attributes = values_from_response_hash(hash_data)
+              yield(table_name, attributes)
+            end
+          end
+
+          options[:request_items] = convert_unprocessed_keys(response)
+
+        end while options[:request_items]
+
+        nil
+
+      end
+
+      # Yields only attribute hashes.  This removes the outer hash that
+      # normally provides the :table_name and :attributes keys. This is 
+      # useful when your batch get requested items from a single table.
+      def each_attributes
+        each do |table_name, attributes|
+          yield(attributes)
+        end
+      end
+
+      protected
+      def convert_unprocessed_keys response
+        
+        return nil if response.data['UnprocessedKeys'].empty?
+        
+        # convert the json response keys into symbolized keys
+        str2sym = lambda do |key_desc|
+          type, value = key_desc.to_a.flatten
+          case type
+          when "S" then { :s => value }
+          when "N" then { :n => value }
+          else 
+            raise "unhandled key type: #{type}"
+          end
+        end
+
+        request_items = {}
+        response.data['UnprocessedKeys'].each_pair do |table,keys|
+
+          request_items[table] = {}
+
+          request_items[table][:attributes_to_get] = keys['AttributesToGet'] if
+            keys['AttributesToGet']
+
+          request_items[table][:keys] = keys['Keys'].collect do |desc|
+            key = {}
+            key[:hash_key_element] = str2sym.call(desc['HashKeyElement'])
+            key[:range_key_element] = str2sym.call(desc['RangeKeyElement']) if
+              desc['RangeKeyElement']
+            key
+          end
+
+        end
+        request_items
+
+      end
+
+    end
+  end
+end

data/lib/aws/dynamo_db/client.rb

@@ -0,0 +1,119 @@
+# 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
+  class DynamoDB
+
+    # @private
+    class Client < Core::Client
+
+      API_VERSION = '2011-06-01'
+
+      REGION_US_E1 = 'dynamodb.us-east-1.amazonaws.com'
+
+      TARGET_PREFIX = "DynamoDB_20111205."
+
+      REQUEST_CLASS = DynamoDB::Request
+
+      CACHEABLE_REQUESTS = Set[:list_tables, :describe_table]
+
+      include Core::ConfiguredJsonClientMethods
+
+      configure_client
+
+      def initialize *args
+
+        super
+
+        # If the signer does not provide a session token, then we will
+        # replace it with another signer that manages an AWS STS session.
+        # This session will auto renew whenever it has expired and will
+        # be shared across threads.
+        if config.signer.session_token.nil?
+          @signer = Core::SessionSigner.for(config) 
+        end
+
+      end
+
+      protected
+      def new_request
+        req = super
+        req.headers["content-type"] = "application/x-amz-json-1.0"
+        req
+      end
+
+      protected
+      def extract_error_code response
+        if response.http_response.status == 413
+          'RequestEntityTooLarge'
+        elsif response.http_response.status >= 300 and
+            body = response.http_response.body and
+            json = (JSON.load(body) rescue nil) and
+            type = json["__type"] and
+            type =~ /\#(.*)$/
+          $1
+        end
+      end
+
+      private
+      def should_retry? response 
+        if possible_expired_credentials?(response)
+          true
+        elsif response.error.is_a?(Errors::ProvisionedThroughputExceededException)
+          config.dynamo_db_retry_throughput_errors?
+        else
+          super
+        end
+      end
+
+      private
+      def rebuild_http_request response
+        # called when a request is going to be retried, in case of 
+        # expired credentials we should refresh the session
+        signer.refresh_session if possible_expired_credentials?(response)
+        super
+      end
+
+      private
+      def sleep_durations response
+
+        retry_count = 
+          if possible_expired_credentials?(response)
+            config.max_retries == 0 ? 0 : 1
+          else
+            config.max_retries { 10 }
+          end
+
+        # given a retry_count of 10, the sleep durations will look like:
+        # 0, 50, 100, 200, 400, 800, 1600, 3200, 6400, 12800 (milliseconds)
+        (0...retry_count).map do |n|
+          if n == 0
+            0
+          else
+            50 * (2 ** (n - 1)) / 1000.0
+          end
+        end
+
+      end
+
+      private
+      # Returns true if we get an access denied error from the service AND
+      # our signer is capible of getting new short-term credentials
+      def possible_expired_credentials? response
+        signer.respond_to?(:refresh_session) and
+        response.error.is_a?(Errors::AccessDeniedException)
+      end
+
+    end
+  end
+end

data/lib/aws/dynamo_db/config.rb

@@ -0,0 +1,20 @@
+# 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.
+
+AWS::Core::Configuration.module_eval do
+
+  add_service 'DynamoDB', 'dynamo_db', 'dynamodb.us-east-1.amazonaws.com'
+
+  add_option :dynamo_db_retry_throughput_errors, true, :boolean => true
+
+end

data/lib/aws/dynamo_db/errors.rb

@@ -0,0 +1,57 @@
+# 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
+  class DynamoDB
+
+    module Errors
+
+      module ModeledError
+
+        def initialize(request = nil, response = nil)
+          message = extract_message(response)
+          include_error_type(response) if response
+          super(request, response, message)
+        end
+
+        def extract_message(response)
+          if response and response.body != ''
+            JSON.load(response.body)["message"] || code
+          elsif code == 'RequestEntityTooLarge'
+            'Request body must be less than 1 MB'
+          else
+            code
+          end
+        end
+
+        def include_error_type(response)
+          if response.status >= 500
+            extend Errors::ServerError
+          else
+            extend Errors::ClientError
+          end
+        end
+
+        def code
+          self.class.name =~ /(::)?([^:]+)$/
+          $2
+        end
+
+      end
+
+      include Core::LazyErrorClasses
+
+    end
+
+  end
+end

data/lib/aws/dynamo_db/expectations.rb

@@ -0,0 +1,40 @@
+# 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
+  class DynamoDB
+
+    module Expectations
+
+      private
+      def expect_conditions(options)
+        expected = {}
+
+        options[:if].each do |name, value|
+          context = "expected value for attribute #{name}"
+          expected[name.to_s] = {
+            :value => format_attribute_value(value, context)
+          }
+        end if options[:if]
+
+        [options[:unless_exists]].flatten.each do |name|
+          expected[name.to_s] = { :exists => false }
+        end if options[:unless_exists]
+
+        expected
+      end
+
+    end
+
+  end
+end

data/lib/aws/dynamo_db/item.rb

@@ -0,0 +1,130 @@
+# 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
+  class DynamoDB
+
+    # Represents a DynamoDB item.  An item is identified by simple or
+    # complex primary key (according to the table schema) and consists
+    # of a collection of attributes.  Attributes are name/value pairs
+    # where the value may be a string, number, string set, or number
+    # set.  
+    #
+    # Getting an item by hash key value:
+    #
+    #   item = table.items['hash-key-value'] 
+    #
+    # Getting an item from a table with both hash and range keys:
+    #
+    #   item = table.items['hash-key','range-key']
+    # 
+    class Item < Core::Resource
+
+      extend Types
+      include Keys
+      include Expectations
+
+      # @return [Table] The table in which the item is stored.
+      attr_reader :table
+
+      # @return [String, Numeric] The hash key value of the item.
+      attr_reader :hash_value
+
+      # @return [String, Numeric, nil] The range key value of the
+      #   item, or +nil+ if the table has a simple primary key.
+      attr_reader :range_value
+
+      # @private
+      def initialize(table, *args)
+        opts = args.pop if args.last.kind_of?(Hash)
+        (@hash_value, @range_value) = args
+        @table = table
+        super(table, opts)
+      end
+
+      # Deletes the item.
+      #
+      # @param [Hash] options Options for deleting the item.
+      #
+      # @option options [Hash] :if Designates a conditional delete.
+      #   The operation will fail unless the item exists and has the
+      #   attributes in the value for this option.  For example:
+      #
+      #     # throws DynamoDB::Errors::ConditionalCheckFailedException
+      #     # unless the item has "color" set to "red"
+      #     item.delete(:if => { :color => "red" })
+      #
+      # @option options [String, Symbol, Array] :unless_exists A name
+      #   or collection of attribute names; if the item has a value
+      #   for any of these attributes, this method will raise
+      #   +DynamoDB::Errors::ConditionalCheckFailedException+.  For
+      #   example:
+      #
+      #     item.delete(:unless_exists => "version")
+      def delete(options = {})
+        client_opts = item_key_options(self)
+
+        expected = expect_conditions(options)
+        client_opts[:expected] = expected unless expected.empty?
+
+        client_opts[:return_values] = options[:return].to_s.upcase if
+          options[:return]
+
+        resp = client.delete_item(client_opts)
+
+        values_from_response_hash(resp.data["Attributes"]) if
+          options[:return] and resp.data["Attributes"]
+      end
+
+      # @return [Boolean] True if the item exists.
+      def exists?(options = {})
+        client_opts = item_key_options(self, options)
+        client_opts[:attributes_to_get] = [table.hash_key.name]
+        resp = client.get_item(client_opts)
+        resp.data.key?("Item")
+      end
+
+      # @return [AttributeCollection] An object representing the
+      #   attributes of the item.
+      def attributes
+        AttributeCollection.new(self)
+      end
+
+      # @private
+      def self.new_from(op, response_object, table, *args)
+        table.assert_schema!
+        hash_value =
+          value_from_response(response_object[table.hash_key.name])
+        range_value =
+          value_from_response(response_object[table.range_key.name]) if
+          table.range_key
+
+        raise "missing hash key value in put_item response" unless hash_value
+        raise "missing range key value in put_item response" unless
+          range_value || !table.range_key
+
+        super(op, response_object,
+              table, hash_value, range_value, *args)
+      end
+
+      protected
+      def resource_identifiers
+        [[:table_name, table.name],
+         [:hash_value, hash_value],
+         [:range_value, range_value]]
+      end
+
+    end
+
+  end
+end