aws-sdk-euca 1.8.5

data/lib/aws/simple_db/attribute.rb

@@ -0,0 +1,154 @@
+# Copyright 2011-2013 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
+
+    # Represents a single named item attribute in SimpleDB.
+    class Attribute
+
+      include Core::Model
+      include Enumerable
+      include ConsistentReadOption
+      include PutAttributes
+      include DeleteAttributes
+
+      # @private
+      def initialize item, name, options = {}
+        @item = item
+        @name = name
+        super
+      end
+
+      # @return [Item] The item this attribute belongs to.
+      attr_reader :item
+
+      # @return [String] The name of this attribute.
+      attr_reader :name
+
+      # Sets all values for this attribute, replacing current values.
+      #
+      # @example Setting a list of values
+      #   attributes['colors'].set 'red', 'blue', 'green'
+      #
+      # @example Setting an array of values
+      #   attributes['colors'].set ['red', 'blue']
+      #
+      # @param [String] values A list of attribute values to set.
+      # @return [nil]
+      def set *values
+        put(values, true)
+        nil
+      end
+
+      # Appends values to this attribute.  Duplicate values are ignored 
+      # by SimpleDB.
+      #
+      # @example Adding a list of values
+      #
+      #   attributes['colors'].add 'red', 'blue', 'green'
+      #
+      # @example Adding an array of values
+      #
+      #   attributes['colors'].add ['red', 'blue']
+      #
+      # @param [String] values A list of attribute values to add.
+      # @return [nil]
+      def add *values
+        put(values, false)
+        nil
+      end
+      alias_method :<<, :add
+
+      # Deletes this attribute or specific values from this attribute.
+      #
+      # @example Delete the attribute and all of its values
+      #
+      #   item.attributes['color'].delete
+      #
+      # @example Delete specific attribute values
+      #
+      #   item.attributes['color'].delete('red', 'blue')
+      #
+      # @param values One ore more values to remove from this attribute.
+      #   If values is empty, then all attribute values are deleted 
+      #   (which deletes this attribute).
+      # @return [nil]
+      def delete *values
+        expect_opts = values.pop if values.last.kind_of?(Hash)
+
+        if values.empty?
+          delete_named_attributes(name, expect_opts || {})
+        else
+          delete_attribute_values(Hash[[[name, values]]].
+                                  merge(expect_opts || {}))
+        end
+        nil
+      end
+
+      # Yields once for each value on this attribute. 
+      #
+      # @yield [attribute_value] Yields once for each domain in the account.
+      # @yieldparam [String] attribute_value
+      # @param [Hash] options 
+      # @option options [Boolean] :consistent_read (false) A consistent read
+      #   returns values that reflects all writes that received a successful
+      #   response prior to the read. 
+      # @return [nil]
+      def each options = {}, &block
+
+        resp = client.get_attributes(
+          :domain_name => item.domain.name,
+          :item_name => item.name,
+          :attribute_names => [name],
+          :consistent_read => consistent_read(options))
+
+        resp.attributes.each do |attribute|
+          yield(attribute.value)
+        end
+
+        nil
+
+      end
+
+      # Returns all values for this attribute as an array of strings.
+      #
+      # @example
+      #   item.attributes['ratings'].values
+      #   #=> ['5', '3', '4']
+      #
+      # @param [Hash] options 
+      # @option options [Boolean] :consistent_read (false) A consistent read
+      #   returns values that reflects all writes that received a successful
+      #   response prior to the read. 
+      # @return [Array<String>] An array of attribute values
+      def values options = {}
+        values = []
+        self.each(options) do |value|
+          values << value
+        end
+        values
+      end
+
+      # @private
+      protected
+      def put values, replace
+        expect_opts = values.pop if values.last.kind_of?(Hash)
+        do_put(attribute_hashes(Hash[[[name, values]]],
+                                replace),
+               expect_opts || {})
+      end
+
+    end
+  end
+end

data/lib/aws/simple_db/attribute_collection.rb

@@ -0,0 +1,231 @@
+# Copyright 2011-2013 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
+
+      # Returns 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 attributes.
+      #
+      #   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,287 @@
+# Copyright 2011-2013 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::QueryClient
+
+      # @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 #
+
+      # @!method batch_delete_attributes(options = {})
+      # Calls the BatchDeleteAttributes API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method batch_put_attributes(options = {})
+      # Calls the BatchPutAttributes API operation.
+      # @param [Hash] 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+ .
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method create_domain(options = {})
+      # Calls the CreateDomain API operation.
+      # @param [Hash] 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 '.'.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method delete_attributes(options = {})
+      # Calls the DeleteAttributes API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method delete_domain(options = {})
+      # Calls the DeleteDomain API operation.
+      # @param [Hash] options
+      #   * +:domain_name+ - *required* - (String) The name of the domain to
+      #     delete.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method domain_metadata(options = {})
+      # Calls the DomainMetadata API operation.
+      # @param [Hash] options
+      #   * +:domain_name+ - *required* - (String) The name of the domain for
+      #     which to display the metadata of.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following 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)
+
+      # @!method get_attributes(options = {})
+      # Calls the GetAttributes API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following 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)
+
+      # @!method list_domains(options = {})
+      # Calls the ListDomains API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:domain_names+ - (Array<String>)
+      #   * +:next_token+ - (String)
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method put_attributes(options = {})
+      # Calls the PutAttributes API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following structure:
+      #   * +:response_metadata+ - (Hash)
+      #     * +:box_usage+ - (Numeric)
+      #     * +:response_id+ - (String)
+
+      # @!method select(options = {})
+      # Calls the Select API operation.
+      # @param [Hash] 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.
+      # @return [Core::Response]
+      #   The #data method of the response object returns
+      #   a hash with the following 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)
+
+      # end client methods #
+
+      define_client_methods('2009-04-15')
+
+    end
+  end
+end