aws-sdk 1.0.0

data/lib/aws/s3/uploaded_part.rb

@@ -0,0 +1,82 @@
+# 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 S3
+
+    # Represents a part of a multipart upload that has been uploaded
+    # to S3.
+    #
+    # @example Get the total size of the uploaded parts
+    #  upload.parts.inject(0) { |sum, part| sum + part.size }
+    class UploadedPart
+
+      include Model
+
+      # @return [MultipartUpload] The upload to which this belongs.
+      attr_reader :upload
+
+      # @return [Integer] The part number.
+      attr_reader :part_number
+
+      # @private
+      def initialize(upload, part_number, opts = {})
+        @upload = upload
+        @part_number = part_number
+        super
+      end
+
+      def ==(other)
+        other.kind_of?(UploadedPart) and
+          other.upload == upload and
+          other.part_number == part_number
+      end
+      alias_method :eql?, :==
+
+      # @return [Integer] The size of the part as it currently
+      #   exists in S3.
+      def size
+        get_attribute(:size)
+      end
+
+      # @return [DateTime] The time at which the part was last
+      #   modified.
+      def last_modified
+        get_attribute(:last_modified)
+      end
+
+      # @return [String] The ETag of the part.
+      def etag
+        get_attribute(:etag)
+      end
+
+      # @private
+      private
+      def get_attribute(name)
+        (resp = client.list_parts(:bucket_name => upload.object.bucket.name,
+                                  :key => upload.object.key,
+                                  :upload_id => upload.id,
+                                  :part_number_marker => part_number-1,
+                                  :max_parts => 1) and
+         part = resp.parts.first and
+         part.part_number == part_number and
+         part.send(name)) or
+          raise "part 3 of upload abc123 does not exist"
+      end
+
+    end
+
+  end
+end

data/lib/aws/s3/uploaded_part_collection.rb

@@ -0,0 +1,86 @@
+# 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/s3/paginated_collection'
+require 'aws/s3/uploaded_part'
+
+module AWS
+  class S3
+
+    # Represents the collection of parts that have been uploaded for
+    # a given multipart upload.  You can get an instance of this
+    # class by calling {MultipartUpload#parts}.
+    #
+    # @example Get the total size of the uploaded parts
+    #  upload.parts.inject(0) { |sum, part| sum + part.size }
+    class UploadedPartCollection
+
+      include Enumerable
+      include Model
+      include PaginatedCollection
+
+      # @return [MultipartUpload] The upload to which the parts belong.
+      attr_reader :upload
+
+      # @private
+      def initialize(upload, opts = {})
+        @upload = upload
+        super
+      end
+
+      # @return [UploadedPart] An object representing the part with
+      #   the given part number.
+      #
+      # @param [Integer] number The part number.
+      def [](number)
+        UploadedPart.new(upload, number)
+      end
+
+      # @private
+      protected
+      def each_member_in_page(page, &block)
+        page.parts.each do |part_info|
+          part = UploadedPart.new(upload, part_info.part_number)
+          yield(part)
+        end
+      end
+
+      # @private
+      protected
+      def list_options(options)
+        opts = super
+        opts.merge!(:bucket_name => upload.object.bucket.name,
+                    :key => upload.object.key,
+                    :upload_id => upload.id)
+        opts
+      end
+
+      # @private
+      protected
+      def limit_param; :max_parts; end
+
+      # @private
+      protected
+      def list_request(options)
+        client.list_parts(options)
+      end
+
+      # @private
+      protected
+      def pagination_markers; [:part_number_marker]; end
+
+    end
+
+  end
+end

data/lib/aws/service_interface.rb

@@ -0,0 +1,60 @@
+# 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'
+
+module AWS
+
+  # @private
+  module ServiceInterface
+
+    def self.included base
+
+      base.send(:attr_reader, :config)
+      base.send(:attr_reader, :client)
+
+      base.module_eval('module Errors; end')
+
+      unless base::Errors.include?(AWS::Errors)
+        base::Errors.module_eval { include AWS::Errors }
+      end
+
+    end
+
+    # Returns a new interface object for this service.  You can override
+    # any of the global configuration parameters by passing them in as
+    # hash options.  They are merged with AWS.config or merged
+    # with the provided +:config+ object.
+    #
+    #   @ec2 = AWS::EC2.new(:max_retries => 2)
+    #
+    # @see AWS::Cofiguration
+    #
+    # @param [Hash] options
+    # @option options [Configuration] :config An AWS::Configuration
+    #   object to initialize this service interface object with.  Defaults
+    #   to AWS.config when not provided.
+    def initialize options = {}
+      @config = options[:config]
+      @config ||= AWS.config
+      @config = @config.with(options)
+      @client = config.send(Inflection.ruby_name(self.class.to_s) + '_client')
+    end
+
+    # @private
+    def inspect
+      "<#{self.class}>"
+    end
+
+  end
+end

data/lib/aws/simple_db.rb

@@ -0,0 +1,202 @@
+# 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/common'
+require 'aws/service_interface'
+require 'aws/s3/errors'
+require 'aws/simple_db/client'
+require 'aws/simple_db/domain_collection'
+
+module AWS
+
+  # This class is the starting point for working with Amazon SimpleDB.
+  #
+  # To use Amazon SimpleDB you must first 
+  # {sign up here}[http://aws.amazon.com/simpledb/].
+  #
+  # For more information about Amazon SimpleDB:
+  #
+  # * {Amazon SimpleDB}[http://aws.amazon.com/simpledb/]
+  # * {Amazon SimpleDB Documentation}[http://aws.amazon.com/documentation/simpledb/]
+  #
+  # = Credentials
+  #
+  # You can setup default credentials for all AWS services via 
+  # AWS.config:
+  #
+  #   AWS.config(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  # 
+  # Or you can set them directly on the SimpleDB interface:
+  #
+  #   sdb = AWS::SimpleDB.new(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  #
+  # = Understanding the SimpleDB Interface
+  #
+  # SimpleDB stores data in a hierarchy of:
+  #
+  # Domains > Items > Attributes
+  #
+  # These are modeled with the following classes:
+  #
+  # * {DomainCollection} 
+  # * {Domain} 
+  # * {ItemCollection} 
+  # * {Item} 
+  # * {AttributeCollection} 
+  # * {Attribute} 
+  #
+  # The collection classes listed above make it easy to enumerate,
+  # the objects they represent.  They also make it easy to perform
+  # bulk operations on all objects in that collection.
+  #
+  # = Domains
+  #
+  # Domains are like database tables.  A domain must exist before you can
+  # write to it.  To create a domain:
+  #
+  #   sdb = SimpleDB.new
+  #   domain = sdb.domains.create('mydomain')
+  #
+  # For more information about working with domains see {DomainCollection}
+  # and {Domain}.
+  #
+  # = Items & Attributes
+  #
+  # Items exist in SimpleDB when they have attributes.  You can delete an 
+  # item by removing all of its attributes.  You create an item by adding
+  # an attribute to it.
+  #
+  # The following example illustrates how you can reference an item that
+  # does not exist yet:
+  #
+  #   sdb = SimpleDB.new
+  #
+  #   # this domain is empty, it has no items
+  #   domain = sdb.domains.create('newdomain')
+  #   domain.items.collect(&:name)
+  #   #=> []
+  #
+  #   # this item doesn't exist yet, so it has no attributes
+  #   item = domain.items['newitem']
+  #   item.attributes.collect(&:name)
+  #   #=> []
+  #
+  #   # the item has no attributes
+  #   tags = item.attributes['tags']
+  #   tags.values
+  #   #=> []
+  #
+  # To create the item in SimpleDB you just need to add an attribute.
+  #
+  #   tags.add %w(first new)
+  #
+  #   domain.items.collect(&:name)
+  #   #=> ['newitem']
+  #
+  #   item.attributes.collect(&:name)
+  #   #=> ['tags']
+  #
+  #   tags.values
+  #   #=> ['first', 'new']
+  #
+  # For more information about working with items and attributes, see:
+  #
+  # * {ItemCollection}
+  # * {Item}
+  # * {AttributeCollection}
+  # * {Attribute}
+  #
+  # = Lazy Execution
+  #
+  # Requests are not made until necessary.  This means you can drill down
+  # all the way to an attribute, by name, without making any requets
+  # to SimpleDB.
+  #
+  #   # makes no request to SimpleDB
+  #   sdb = SimpleDB.new
+  #   colors = sdb.domains['mydomain'].items['car'].attributes['colors']
+  #
+  #   # one request to get the values for 'colors'
+  #   puts colors.values
+  #
+  #   # one request to add blue and green
+  #   colors.add 'blue', 'green'
+  #
+  #   # one request to delete the colors attribute
+  #   colors.delete
+  #
+  class SimpleDB
+
+    include ServiceInterface
+
+    # Returns a collection object that represents the domains in your
+    # account.
+    #
+    # @return [DomainCollection] Returns a collection representing all your 
+    #   domains.
+    def domains
+      DomainCollection.new(:config => config)
+    end
+
+    # Call this method with a block.  Code executed inside the block
+    # make consistent reads until the block ends.
+    #
+    #   AWS::SimpleDB.consistent_reads do
+    #     # ...
+    #   end
+    #
+    # === Other Modes
+    #
+    # You can also use this same function to disable consistent reads insie
+    # a block.  This is useful if you have consistent reads enabled by 
+    # default:
+    #
+    #   AWS::SimpleDB.consistent_reads(false) do
+    #     # ...
+    #   end
+    # 
+    # @param [Boolean] state (true) When true, all SimpleDB read operations
+    #   will be consistent reads inside the block.  When false, all 
+    #   reads operations will not be consistent reads.  The previous state
+    #   will be restored after the block executes.
+    # @return Returns the final block value.
+    def self.consistent_reads state = true, &block
+      begin
+        prev_state = Thread.current['_simple_db_consistent_reads_']
+        Thread.current['_simple_db_consistent_reads_'] = state
+        yield
+      ensure
+        Thread.current['_simple_db_consistent_reads_'] = prev_state
+      end
+    end
+
+    # @return [Boolean] Returns true if we are inside an AWS::SimpleDB
+    #   #consistent_reads method block.
+    # @private
+    def self.in_consistent_reads_block?
+      !Thread.current['_simple_db_consistent_reads_'].nil?
+    end
+
+    # @return [Boolean] Returns true if the consistent_reads block has
+    #   a true state, false otherwise.
+    # @private
+    def self.consistent_reads_state
+      Thread.current['_simple_db_consistent_reads_']
+    end
+
+  end
+end

data/lib/aws/simple_db/attribute.rb

@@ -0,0 +1,159 @@
+# 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/consistent_read_option'
+require 'aws/simple_db/put_attributes'
+require 'aws/simple_db/delete_attributes'
+
+module AWS
+  class SimpleDB
+
+    # Represents a single named item attribute in SimpleDB.
+    class Attribute
+
+      include 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 *values An array or 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 *values An array or 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