aws-sdk 1.0.0

data/lib/aws/simple_db/domain.rb

@@ -0,0 +1,118 @@
+# Copyright 2011 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.
+
+require 'aws/errors'
+require 'aws/model'
+require 'aws/simple_db/domain_metadata'
+require 'aws/simple_db/item_collection'
+
+module AWS
+  class SimpleDB
+
+    # Represents a domain in SimpleDB.
+    #
+    # Domains, like database tables, must exist before you can write to one.
+    #
+    # @example Creating a domain
+    #   domain = SimpleDB.new.domains.create('mydomain')
+    #
+    # @example Getting a domain
+    #   domain = SimpleDB.new.domains['mydomain']
+    #
+    # @see DomainCollection
+    #
+    class Domain
+
+      # @private
+      class NonEmptyDeleteError < StandardError; end
+
+      include Model
+
+      # @param [String] The name of a SimpleDB domain to reference.
+      def initialize(name, options = {})
+        super(options)
+        @name = name
+      end
+
+      # Returns the name for this domain.
+      #
+      # @return [String] The name of this domain.
+      attr_reader :name
+
+      # Returns true if the domain has no items, false otherwise.
+      #
+      # @return [Boolean] Returns true if the domain has no items.
+      def empty?
+        metadata.item_count == 0
+      end
+
+      # Deletes the (empty) domain.
+      #
+      # @note If you need to delete a domain with items, call {#delete!}
+      # @raise [NonEmptyDeleteError] Raises if the domain is not empty.
+      # @return [nil]
+      def delete
+        unless empty?
+          raise NonEmptyDeleteError, "delete called without :force " +
+           "on a non-empty domain"
+        end
+        client.delete_domain(:domain_name => name)
+        nil
+      end
+
+      # Deletes the domain and all of its items.
+      #
+      # @return [nil]
+      def delete!
+        client.delete_domain(:domain_name => name)
+        nil
+      end
+
+      # Returns true if this domain exists, false otherwise.
+      #
+      # @return [Boolean] Returns true if the domain exists.
+      def exists?
+        begin
+          client.domain_metadata(:domain_name => name)
+          true
+        rescue Errors::NoSuchDomain
+          false
+        end
+      end
+
+      # Returns a metadata object that can provide information about
+      # this domain.
+      #
+      # @return [DomainMetadata]
+      def metadata
+        DomainMetadata.new(self)
+      end
+
+      # Returns a collection that represents all of the items in this domain.
+      #
+      # @return [ItemCollection]
+      def items
+        ItemCollection.new(self)
+      end
+
+      # An irb-friendly string representation of this object.
+      #
+      # @return [String]
+      # @private
+      def inspect
+        "#<#{self.class}:#{name}>"
+      end
+
+    end
+  end
+end

data/lib/aws/simple_db/domain_collection.rb

@@ -0,0 +1,116 @@
+# Copyright 2011 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.
+
+require 'aws/model'
+require 'aws/simple_db/domain'
+
+module AWS
+  class SimpleDB
+
+    # An Enumerable collection representing all your domains in SimpleDB.
+    #
+    # Use a DomainCollection to create, get and list domains.
+    #
+    # @example Creating a domain in SimpleDB
+    #
+    #   sdb = SimpleDB.new
+    #   domain = sdb.domains.create('mydomain')
+    #
+    # @example Getting a domain with indifferent access
+    #
+    #   domain = sdb.domains[:mydomain]
+    #   domain = sdb.domains['mydomain']
+    #
+    # @example Enumerating domains
+    #
+    #   sdb.domains.each do |domain|
+    #     puts domain.name
+    #   end
+    #
+    class DomainCollection
+
+      include Model
+      include Enumerable
+
+      # Creates a domain in SimpleDB and returns a domain object.
+      #
+      # @note This operation might take 10 or more seconds to complete.
+      # @note Creating a domain in SimpleDB is an idempotent operation; 
+      #   running it multiple times using the same domain name will not 
+      #   result in an error.
+      # @note You can create up to 100 domains per account.
+      # @param [String] domain_name 
+      # @return [Domain] Returns a new domain with the given name.
+      def create(domain_name)
+        client.create_domain(:domain_name => domain_name)
+        domain_named(domain_name)
+      end
+
+      # Returns a domain object with the given name.
+      #
+      # @note This does not attempt to create the domain if it does not 
+      #   already exist in SimpleDB.  Use {#create} to add a domain to SDB.
+      #
+      # @param [String] domain_name The name of the domain to return.
+      # @return [Domain] Returns the domain with the given name.
+      def [] domain_name
+        domain_named(domain_name)
+      end
+
+      # @note Normally your account has a limit of 100 SimpleDB domains.  You can {request more here}[http://aws.amazon.com/contact-us/simpledb-limit-request/]
+      # @yield [domain] Yields once for every domain in your account. 
+      # @yieldparam [Domain] domain
+      # @param [Hash] options
+      # @option options [Integer] :limit (nil) The maximum number of 
+      #   domains to yield.
+      # @option options [Integer] :batch_size (100) The number of domains to
+      #   fetch each request to SimpleDB.  Maximum is 100.
+      # @return [nil]
+      def each options = {}, &block
+
+        total_limit = options[:limit]
+        batch_size = options[:batch_size] || 100
+        received = 0
+        next_token = nil
+
+        begin
+
+          limit = total_limit ? 
+            [total_limit - received, batch_size].min : 
+            batch_size
+
+          list_options = { :limit => limit }
+          list_options[:next_token] = next_token if next_token
+          list = client.list_domains(list_options)
+
+          next_token = list.next_token
+          received += list.domain_names.length
+
+          list.domain_names.each do |name|
+            yield(domain_named(name))
+          end
+        
+        end while next_token and (total_limit.nil? or received < total_limit)
+        nil
+      end
+
+      # @return [Domain] Returns a domain with the given name.
+      # @private
+      protected
+      def domain_named name
+        Domain.new(name.to_s, :config => config)
+      end
+
+    end
+  end
+end

data/lib/aws/simple_db/domain_metadata.rb

@@ -0,0 +1,112 @@
+# Copyright 2011 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.
+
+require 'aws/model'
+
+module AWS
+  class SimpleDB
+
+    # SimpleDB can report on the amount of data stored in a domain,
+    # the number of items, etc.
+    #
+    # @example
+    #
+    #  sdb = SimpleDB.new
+    #  sdb.domains['mydomain'].metadata.to_h
+    #
+    #  # the hash returned above might look like:
+    #  {
+    #    :timestamp => 1300841880,
+    #    :attribute_names_size_bytes => 12,
+    #    :item_count => 1,
+    #    :attribute_value_count => 6,
+    #    :attribute_values_size_bytes => 25,
+    #    :item_names_size_bytes => 3,
+    #    :attribute_name_count => 3
+    #  }
+    # 
+    class DomainMetadata
+
+      include Model
+
+      # @private
+      ATTRIBUTES = [
+        :item_count,
+        :item_names_size_bytes,
+        :attribute_name_count,
+        :attribute_names_size_bytes,
+        :attribute_value_count,
+        :attribute_values_size_bytes,
+        :timestamp,
+      ]
+
+      # @param [Domain] The domain to fetch metadata for.
+      # @return [DomainMetadata]
+      def initialize domain, options = {}
+        @domain = domain
+        super
+      end
+
+      # @return [Domain] The domain this metadata is describing.
+      attr_reader :domain
+
+      # @return [Integer] The number of all items in the {#domain}.
+      def item_count
+        self.to_h[:item_count]
+      end
+
+      # @return [Integer] The total size of all item names in the {#domain},
+      #   in bytes.
+      def item_names_size_bytes
+        self.to_h[:item_names_size_bytes]
+      end
+
+      # @return [Integer] The number of unique attribute names in the 
+      #   {#domain}.
+      def attribute_name_count
+        self.to_h[:attribute_name_count]
+      end
+
+      # @return [Integer] The total size of all unique attribute names, 
+      #   in bytes.
+      def attribute_names_size_bytes
+        self.to_h[:attribute_names_size_bytes]
+      end
+
+      # @return [Integer] The number of all attribute name/value pairs in 
+      #   the {#domain}.
+      def attribute_value_count
+        self.to_h[:attribute_value_count]
+      end
+
+      # @return [Integer] The total size of all attribute values, in bytes.
+      def attribute_values_size_bytes
+        self.to_h[:attribute_values_size_bytes]
+      end
+
+      # @return [Integer] The data and time when metadata was calculated
+      #   in Epoch (UNIX) time.
+      def timestamp
+        self.to_h[:timestamp]
+      end
+
+      # @return [Hash] A hash of all of the metadata attributes for 
+      #   this {#domain}.
+      def to_h
+        meta = client.domain_metadata(:domain_name => domain.name)
+        ATTRIBUTES.inject({}) {|h,attr| h[attr] = meta.send(attr); h }
+      end
+
+    end
+  end
+end

data/lib/aws/simple_db/errors.rb

@@ -0,0 +1,46 @@
+# Copyright 2011 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.
+
+require 'aws/lazy_error_classes'
+require 'aws/simple_db/client/xml'
+
+module AWS
+  class SimpleDB
+
+    # This module contains exception classes for each of the error
+    # types that SimpleDB can return.  You can use these classes to
+    # rescue specific errors, for example:
+    #
+    #  begin
+    #    SimpleDB.new.domains.mydomain.
+    #      items["foo"].attributes.set(:color => "red")
+    #  rescue SimpleDB::Errors::NoSuchDomain => e
+    #    SimpleDB.new.domians.create("mydomain")
+    #    retry
+    #  end
+    #
+    # Each exception has:
+    #
+    # * +code+: returns the error code as a string.
+    # * +box_usage+: returns the box usage for the operation.
+    #
+    # All errors raised as a result of error responses from the
+    # service are instances of either {ClientError} or {ServerError}.
+    # @private
+    module Errors
+      BASE_ERROR_GRAMMAR = Client::XML::BaseError
+      include LazyErrorClasses
+    end
+
+  end
+end

data/lib/aws/simple_db/expect_condition_option.rb

@@ -0,0 +1,45 @@
+# Copyright 2011 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
+
+    # @private
+    module ExpectConditionOption
+
+      # @private
+      protected
+      def expect_condition_opts(opts)
+        expected = []
+        opts.each do |name, value|
+          case name
+          when :if
+            (expected_name, expected_value) = value.to_a.first
+            expected << {
+              :name => expected_name.to_s,
+              :value => expected_value
+            }
+          when :unless
+            expected << {
+              :name => value.to_s,
+              :exists => false
+            }
+          end
+        end
+        expected
+      end
+
+    end
+
+  end
+end

data/lib/aws/simple_db/item.rb

@@ -0,0 +1,84 @@
+# Copyright 2011 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.
+
+require 'aws/model'
+require 'aws/simple_db/item_data'
+require 'aws/simple_db/attribute_collection'
+require 'aws/simple_db/expect_condition_option'
+require 'aws/simple_db/consistent_read_option'
+
+module AWS
+  class SimpleDB
+
+    # Represents a single item in a SimpleDB domain.  You can use
+    # this class to delete the item or get its data.  You can also
+    # use it to access the {AttributeCollection} for the item in
+    # order to add, remove, or read the item's attributes.
+    #
+    #   item = AWS::SimpleDB.new.domains['mydomain'].items['item-id']
+    #
+    class Item
+
+      include Model
+      include ExpectConditionOption
+      include ConsistentReadOption
+
+      # @param [Domain] domain The domain the item belongs to
+      # @param [String] name The name of the item in SimpleDB.
+      # @param [Hash] options
+      def initialize domain, name, options = {}
+        @domain = domain
+        @name = name
+        super
+      end
+      
+      # @return [Domain] The domain this item belongs to.
+      attr_reader :domain
+
+      # @return [String] The item name.
+      attr_reader :name
+
+      # @return [AttributeCollection] A collection representing all attributes
+      #   for this item.
+      def attributes
+        AttributeCollection.new(self)
+      end
+
+      # Deletes the item and all of its attributes from SimpleDB.
+      # @return [nil]
+      def delete options = {}
+        delete_opts = {}
+        delete_opts[:domain_name] = domain.name
+        delete_opts[:item_name] = name
+        delete_opts[:expected] = expect_condition_opts(options)
+        delete_opts.delete(:expected) if delete_opts[:expected].empty?
+        client.delete_attributes(delete_opts)
+        nil
+      end
+
+      # Returns all of the item's attributes in an {ItemData} instance.
+      # @return [ItemData] An object with all of the loaded attribute names
+      #   and values for this item.
+      def data options = {}
+        get_opts = {}
+        get_opts[:domain_name] = domain.name
+        get_opts[:item_name] = name
+        get_opts[:consistent_read] = consistent_read(options)
+        r = client.get_attributes(get_opts)
+        ItemData.new(:name => name, :domain => domain, :response_object => r)
+      end
+
+    end
+
+  end
+end