aws_sdk 3.1.5

data/lib/aws/simple_db/attribute_collection.rb

@@ -0,0 +1,231 @@
+# 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 SimpleDB
+    class AttributeCollection
+
+      include Core::Model
+      include Enumerable
+      include ConsistentReadOption
+      include PutAttributes
+      include DeleteAttributes
+
+      # @param [Item] item The item to create an attribute collection for.
+      # @return [AttributeCollection]
+      def initialize item, options = {}
+        @item = item
+        super
+      end
+
+      # @return [Item] The item this collection belongs to.
+      attr_reader :item
+
+      # Retuns an Attribute with the given name.
+      #
+      # @note This does not make a request to SimpleDB.
+      #
+      # You can ask for any attribute by name.  The attribute may or may not
+      # actually exist in SimpleDB.
+      # 
+      # @example Get an attribute by symbol or string name
+      #   colors = item.attributes[:colors]
+      #   colors = item.attributes['colors']
+      # @param [String, Symbol] attribute_name name of the attribute to get.
+      # @return [Item] An item with the given name.
+      def [] attribute_name
+        Attribute.new(item, attribute_name.to_s)
+      end
+
+      # Sets the values for a given attribute.
+      #
+      # @example Replace all of the values for the named attribute.
+      #   item.attributes[:color] = 'red', 'blue'
+      # @return This method returns the values passed to it.
+      def []= attribute_name, *values
+        self[attribute_name].set(*values)
+      end
+
+      # Yields all attribute values with their names.
+      #
+      # @example Getting all values for an item
+      #
+      #   item.attributes.each_value do |name, value|
+      #     puts "#{name}: #{value}"
+      #   end
+      #
+      # @yield [attribute_name, attribute_value] Yields once for every 
+      #   attribute value on the item.
+      # @yieldparam [String] attribute_name
+      # @yieldparam [String] attribute_value
+      # @param [Hash] options 
+      # @option options [Boolean] :consistent_read (false) Causes this 
+      #   method to yield the most current attributes for this item.
+      # @return [nil]
+      def each_value options = {}, &block
+
+        list = client.get_attributes(
+          :domain_name => item.domain.name,
+          :item_name => item.name,
+          :consistent_read => consistent_read(options))
+
+        list.attributes.each do |attribute|
+          attribute_name = attribute.name
+          attribute_value = attribute.value
+          yield(attribute_name, attribute_value)
+        end
+
+        nil
+
+      end
+
+      # Yields all attribute for this item.
+      #
+      # @example Getting all attributes for an item
+      #
+      #   item.attributes.each do |attribute|
+      #     puts attribute.name
+      #   end
+      #
+      # @yield [attribute] Yields once for every attribute
+      #   on the item.  Yields each attribute only one time, even it
+      #   has multiple values.
+      # @yieldparam [Attribute] attribute
+      # @param [Hash] options 
+      # @option options [Boolean] :consistent_read (false) Causes this 
+      #   method to yield the most current attributes for this item.
+      # @return [nil]
+      def each options = {}, &block
+        yielded = {}
+        each_value(options) do |attribute_name, attribute_value| 
+          unless yielded[attribute_name]
+            attribute = self[attribute_name]
+            yield(attribute)
+            yielded[attribute_name] = true
+          end
+        end
+        nil
+      end
+
+      # Replaces attributes for the {#item}.
+      #
+      # The +attributes_hash+ should have attribute names as keys.  The 
+      # hash values should be either strings or arrays of strings.
+      #
+      # Attributes not named in this hash are left alone.  Attributes named
+      # in this hash are replaced.
+      #
+      # @example
+      #
+      #   item.attributes.set(
+      #     'colors' => ['red', 'blue'],  
+      #     'category' => 'clearance')
+      #
+      # @param [Hash] attributes
+      # @return [nil]
+      def replace attributes
+        do_put(attribute_hashes(attributes, true), attributes)
+      end
+      alias_method :set, :replace
+
+      # Adds values to attributes on the {#item}.
+      #
+      # The +attributes_hash+ should have attribute names as keys.  The 
+      # hash values should be either strings or arrays of strings.
+      #
+      # @example
+      #
+      #   item.attributes.add(
+      #     'colors' => ['red', 'blue'],  
+      #     'category' => 'clearance')
+      #
+      # @param[Hash] attribute_hash
+      # @return [nil]
+      def add attributes
+        do_put(attribute_hashes(attributes, false), attributes)
+      end
+
+      # Perform a mixed update of added and replace attribues.
+      #
+      #   item.attributes.put(
+      #     :add => { 'colors' => %w(green blue), 'tags' => 'cool' }
+      #     :replace => { 'quantity' => 5 }
+      #   )
+      #
+      # @param [Hash] options
+      # @option options [Hash] :add A hash of attribute names and values to
+      #   append to this item.
+      # @option options [Hash] :replace A hash of attribute names and values to
+      #   add to this item.  If there are currently attributes of the same
+      #   name they will be replaced (not appended to).
+      # @option options [Hash] :replace
+      # @return [nil]
+      def put options = {}
+        add = options[:add] || {}
+        replace = options[:replace] || {}
+        attributes = attribute_hashes(add, false)
+        attributes += attribute_hashes(replace, true)
+        do_put(attributes, options)
+      end
+
+      # Returns a hash of all attributes (names and values).
+      # The attribute names are strings and the values are
+      # arrays of strings.
+      #
+      # @example
+      #   item.attributes.to_h
+      #   #=> { 'colors' => ['red','blue'], 'size' => ['large'] }
+      #
+      # @param [Hash] options 
+      # @option options [Boolean] :consistent_read (false) Causes this 
+      #   method to return the most current attributes values.
+      # @return [Hash]
+      def to_h options = {}
+        hash = {}
+        each_value(options) do |attribute_name,attribute_value|
+          hash[attribute_name] ||= []
+          hash[attribute_name] << attribute_value
+        end
+        hash
+      end
+
+      # Delete one or more attributes from {#item}.
+      #
+      # @example Delete a list of attributes by name (accepts a list or array)
+      #   item.attributes.delete 'size', 'color'
+      #   item.attributes.delete %w(size color)
+      #
+      # @example Delete a specific list of attribute values
+      #   item.attributes.delete(:color => 'red', :tags => %w(special limited))
+      #
+      # @overload delete(attributes)
+      #   @param [Hash] attributes A hash of attribute names and values to
+      #     delete.
+      #   @return [nil]
+      #
+      # @overload delete(*attribute_names)
+      #   @param [String] A list of attribute names to delete.
+      #   @return [nil]
+      #
+      def delete *args
+        if args.size == 1 and args.first.kind_of?(Hash)
+          delete_attribute_values(args.first)
+        else
+          delete_named_attributes(*args)
+        end
+        nil
+      end
+
+    end
+  end
+end

data/lib/aws/simple_db/client.rb

@@ -0,0 +1,349 @@
+# 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 SimpleDB
+
+    # Client class for Amazon SimpleDB.
+    class Client < Core::Client
+
+      API_VERSION = '2009-04-15'
+
+      extend Core::Client::QueryXML
+
+      # @private
+      REGION_US_E1 = 'sdb.amazonaws.com'
+
+      # @private
+      REGION_US_W1 = 'sdb.us-west-1.amazonaws.com'
+
+      # @private
+      REGION_EU_W1 = 'sdb.eu-west-1.amazonaws.com'
+
+      # @private
+      REGION_APAC_SE1 = 'sdb.ap-southeast-1.amazonaws.com'
+
+      # @private
+      CACHEABLE_REQUESTS = Set[
+        :domain_metadata,
+        :get_attributes,
+        :list_domains,
+        :select,
+      ]
+
+      # @param [String] name
+      # @return [Boolean] Returns true if the given name is a valid
+      #   Amazon SimpleDB domain name.
+      # @private
+      def valid_domain_name? name
+        self.class.valid_domain_name?(name)
+      end
+
+      # @param [String] name
+      # @return [Boolean] Returns true if the given name is a valid
+      #   Amazon SimpleDB domain name.
+      def self.valid_domain_name? name
+        name.to_s =~ /^[a-z_\-\.]{3,255}$/i ? true : false
+      end
+
+      ## client methods ##
+
+      # Calls the BatchDeleteAttributes API operation.
+      # @method batch_delete_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain in
+      #   which the attributes are being deleted.
+      # * +:items+ - *required* - (Array<Hash>) A list of items on which to
+      #   perform the operation.
+      #   * +:name+ - *required* - (String)
+      #   * +:attributes+ - (Array<Hash>)
+      #     * +:name+ - *required* - (String) The name of the attribute.
+      #     * +:value+ - *required* - (String) The value of the attribute.
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :batch_delete_attributes, 'BatchDeleteAttributes'
+
+      # Calls the BatchPutAttributes API operation.
+      # @method batch_put_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain in
+      #   which the attributes are being stored.
+      # * +:items+ - *required* - (Array<Hash>) A list of items on which to
+      #   perform the operation.
+      #   * +:name+ - *required* - (String) The name of the replaceable item.
+      #   * +:attributes+ - *required* - (Array<Hash>) The list of attributes
+      #     for a replaceable item.
+      #     * +:name+ - *required* - (String) The name of the replaceable
+      #       attribute.
+      #     * +:value+ - *required* - (String) The value of the replaceable
+      #       attribute.
+      #     * +:replace+ - (Boolean) A flag specifying whether or not to
+      #       replace the attribute/value pair or to add a new attribute/value
+      #       pair. The default setting is +false+ .
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :batch_put_attributes, 'BatchPutAttributes'
+
+      # Calls the CreateDomain API operation.
+      # @method create_domain(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain to
+      #   create. The name can range between 3 and 255 characters and can
+      #   contain the following characters: a-z, A-Z, 0-9, '_', '-', and '.'.
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :create_domain, 'CreateDomain'
+
+      # Calls the DeleteAttributes API operation.
+      # @method delete_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain in
+      #   which to perform the operation.
+      # * +:item_name+ - *required* - (String) The name of the item. Similar to
+      #   rows on a spreadsheet, items represent individual objects that
+      #   contain one or more value-attribute pairs.
+      # * +:attributes+ - (Array<Hash>) A list of Attributes. Similar to
+      #   columns on a spreadsheet, attributes represent categories of data
+      #   that can be assigned to items.
+      #   * +:name+ - *required* - (String) The name of the attribute.
+      #   * +:value+ - (String) The value of the attribute.
+      # * +:expected+ - (Hash) The update condition which, if specified,
+      #   determines whether the specified attributes will be deleted or not.
+      #   The update condition must be satisfied in order for this request to
+      #   be processed and the attributes to be deleted.
+      #   * +:name+ - (String) The name of the attribute involved in the
+      #     condition.
+      #   * +:value+ - (String) The value of an attribute. This value can only
+      #     be specified when the Exists parameter is equal to +true+ .
+      #   * +:exists+ - (Boolean) A value specifying whether or not the
+      #     specified attribute must exist with the specified value in order
+      #     for the update condition to be satisfied. Specify +true+ if the
+      #     attribute must exist for the update condition to be satisfied.
+      #     Specify +false+ if the attribute should not exist in order for the
+      #     update condition to be satisfied.
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :delete_attributes, 'DeleteAttributes'
+
+      # Calls the DeleteDomain API operation.
+      # @method delete_domain(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain to
+      #   delete.
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :delete_domain, 'DeleteDomain'
+
+      # Calls the DomainMetadata API operation.
+      # @method domain_metadata(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain for
+      #   which to display the metadata of.
+      #
+      # === Response Structure:
+      #
+      # * +:item_count+ - (Integer)
+      # * +:item_names_size_bytes+ - (Integer)
+      # * +:attribute_name_count+ - (Integer)
+      # * +:attribute_names_size_bytes+ - (Integer)
+      # * +:attribute_value_count+ - (Integer)
+      # * +:attribute_values_size_bytes+ - (Integer)
+      # * +:timestamp+ - (Integer)
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :domain_metadata, 'DomainMetadata'
+
+      # Calls the GetAttributes API operation.
+      # @method get_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain in
+      #   which to perform the operation.
+      # * +:item_name+ - *required* - (String) The name of the item.
+      # * +:attribute_names+ - (Array<String>) The names of the attributes.
+      # * +:consistent_read+ - (Boolean) Determines whether or not strong
+      #   consistency should be enforced when data is read from SimpleDB. If
+      #   +true+ , any data previously written to SimpleDB will be returned.
+      #   Otherwise, results will be consistent eventually, and the client may
+      #   not see data that was written immediately before your read.
+      #
+      # === Response Structure:
+      #
+      # * +:attributes+ - (Array<Hash>)
+      #   * +:name+ - (String)
+      #   * +:alternate_name_encoding+ - (String)
+      #   * +:value+ - (String)
+      #   * +:alternate_value_encoding+ - (String)
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :get_attributes, 'GetAttributes'
+
+      # Calls the ListDomains API operation.
+      # @method list_domains(options = {})
+      #
+      # === Options:
+      #
+      # * +:max_number_of_domains+ - (Integer) The maximum number of domain
+      #   names you want returned. The range is 1 to 100. The default setting
+      #   is 100.
+      # * +:next_token+ - (String) A string informing Amazon SimpleDB where to
+      #   start the next list of domain names.
+      #
+      # === Response Structure:
+      #
+      # * +:domain_names+ - (Array<String>)
+      # * +:next_token+ - (String)
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :list_domains, 'ListDomains'
+
+      # Calls the PutAttributes API operation.
+      # @method put_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain_name+ - *required* - (String) The name of the domain in
+      #   which to perform the operation.
+      # * +:item_name+ - *required* - (String) The name of the item.
+      # * +:attributes+ - *required* - (Array<Hash>) The list of attributes.
+      #   * +:name+ - *required* - (String) The name of the replaceable
+      #     attribute.
+      #   * +:value+ - *required* - (String) The value of the replaceable
+      #     attribute.
+      #   * +:replace+ - (Boolean) A flag specifying whether or not to replace
+      #     the attribute/value pair or to add a new attribute/value pair. The
+      #     default setting is +false+ .
+      # * +:expected+ - (Hash) The update condition which, if specified,
+      #   determines whether the specified attributes will be updated or not.
+      #   The update condition must be satisfied in order for this request to
+      #   be processed and the attributes to be updated.
+      #   * +:name+ - (String) The name of the attribute involved in the
+      #     condition.
+      #   * +:value+ - (String) The value of an attribute. This value can only
+      #     be specified when the Exists parameter is equal to +true+ .
+      #   * +:exists+ - (Boolean) A value specifying whether or not the
+      #     specified attribute must exist with the specified value in order
+      #     for the update condition to be satisfied. Specify +true+ if the
+      #     attribute must exist for the update condition to be satisfied.
+      #     Specify +false+ if the attribute should not exist in order for the
+      #     update condition to be satisfied.
+      #
+      # === Response Structure:
+      #
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :put_attributes, 'PutAttributes'
+
+      # Calls the Select API operation.
+      # @method select(options = {})
+      #
+      # === Options:
+      #
+      # * +:select_expression+ - *required* - (String) The expression used to
+      #   query the domain.
+      # * +:next_token+ - (String) A string informing Amazon SimpleDB where to
+      #   start the next list of ItemNames.
+      # * +:consistent_read+ - (Boolean) Determines whether or not strong
+      #   consistency should be enforced when data is read from SimpleDB. If
+      #   +true+ , any data previously written to SimpleDB will be returned.
+      #   Otherwise, results will be consistent eventually, and the client may
+      #   not see data that was written immediately before your read.
+      #
+      # === Response Structure:
+      #
+      # * +:items+ - (Array<Hash>)
+      #   * +:name+ - (String)
+      #   * +:alternate_name_encoding+ - (String)
+      #   * +:attributes+ - (Array<Hash>)
+      #     * +:name+ - (String)
+      #     * +:alternate_name_encoding+ - (String)
+      #     * +:value+ - (String)
+      #     * +:alternate_value_encoding+ - (String)
+      # * +:next_token+ - (String)
+      # * +:response_metadata+ - (Hash)
+      #   * +:box_usage+ - (Numeric)
+      #   * +:response_id+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :select, 'Select'
+
+      ## end client methods ##
+
+    end
+  end
+end