aws-sdk 1.3.2 → 1.3.3

data/lib/aws/record/hash_model/finder_methods.rb

@@ -38,35 +38,28 @@ module AWS
         end
         alias_method :[], :find_by_id
   
-        # Finds records in SimpleDB and returns them as objects of the 
-        # current class.
+        # Finds records in Amazon DynamoDB and returns them as objects of 
+        # the current class.
         #
         # Finding +:all+ returns an enumerable scope object
         #
-        #  People.find(:all, :order => [:age, :desc], :limit => 10).each do |person|
+        #  People.find(:all, :limit => 10).each do |person|
         #    puts person.name
         #  end
         #
         # Finding +:first+ returns a single record (or nil)
         #
-        #  boss = People.find(:first, :where => { :boss => true })
+        #  boss = People.find(:first)
         #
-        # Find accepts a hash of find modifiers (+:where+, +:order+ and
-        # +:limit+).  You can also choose to omit these modifiers and
+        # Find accepts a hash of find modifiers (+:shard+ and +:limit+).
+        # You can also choose to omit these modifiers and
         # chain them on the scope object returned.  In the following
         # example only one request is made to SimpleDB (when #each is
         # called)
         #
-        #   people = People.find(:all)
+        #   people = People.find(:all, :limit => 10)
         #
-        #   johns = people.where(:name => 'John Doe')
-        #
-        #   johns.order(:age, :desc).limit(10).each do |suspects|
-        #     # ...
-        #   end
-        #
-        # See also {#where}, {#order} and {#limit} for more
-        # information and options.
+        #   people = people.limit(10).find(:all)
         #
         # @overload find(id)
         #   @param id The record to find, raises an exception if the record is
@@ -77,6 +70,8 @@ module AWS
         #     and array is returned of records.  When finding +:first+ then
         #     +nil+ or a single record will be returned.
         #   @param [Hash] options
+        #   @option options [Integer] :shard The shard name of the Amazon 
+        #     DynamoDB table to search.
         #   @option options [Integer] :limit The max number of records to fetch.
         def find *args
           new_scope.find(*args)

data/lib/aws/record/model.rb

@@ -48,9 +48,7 @@ module AWS
     # * +integer_attr+
     # * +float_attr+
     # * +datetime_attr+
-    #
-    # For more information about the various attribute macros available, 
-    # and what options they accept, see {AttributeMacros}.
+    # * +date_attr+
     #
     # === Usage 
     #

data/lib/aws/record/model/finder_methods.rb

@@ -65,7 +65,7 @@ module AWS
         #     # ...
         #   end
         #
-        # See also {#where}, {#order} and {#limit} for more
+        # See also {where}, {order} and {limit} for more
         # information and options.
         #
         # @overload find(id)
@@ -107,7 +107,7 @@ module AWS
         #   end
         #
         # This method is equivalent to +find(:all)+, and therefore you can also
-        # pass aditional options.  See {#find} for more information on what 
+        # pass aditional options.  See {.find} for more information on what 
         # options you can pass.
         #
         #   Book.all(:where => { :author' => 'me' }).each do |my_book|
@@ -138,7 +138,7 @@ module AWS
         #
         #   People.find(:all).where(:boss => true).count
         #
-        # See {#find} and {Scope#count} for more details.
+        # See {find} and {Scope#count} for more details.
         #
         # @param [Hash] options (<code>{}</code>) Options for counting
         #   records.

data/lib/aws/s3.rb

@@ -99,6 +99,7 @@ module AWS
       autoload :ACLObject,                    'acl_object'
       autoload :Bucket,                       'bucket'
       autoload :BucketCollection,             'bucket_collection'
+      autoload :BucketLifecycleConfiguration, 'bucket_lifecycle_configuration'
       autoload :BucketVersionCollection,      'bucket_version_collection'
       autoload :Client,                       'client'
       autoload :DataOptions,                  'data_options'

data/lib/aws/s3/bucket.rb

@@ -100,30 +100,27 @@ module AWS
         client.get_bucket_versioning(:bucket_name => @name).status
       end
 
-      # Deletes the current bucket.
-      # 
-      # @note This operation will fail if the bucket is not empty.
-      #
+      # Deletes all objects from this bucket.
+      # @return [nil]
+      def clear!
+        versions.each_batch do |versions|
+          objects.delete(versions)
+        end
+      end
+
+      # Deletes the current bucket.  An error will be raised if the
+      # bucket is not empty.
       # @return [nil]
-      #
       def delete
         client.delete_bucket(:bucket_name => @name)
         nil
       end
 
-      # Attempts to delete all objects (or object versions) from the bucket
-      # and then attempts to delete the bucket.
-      #
-      # @note This operation may fail if you do not have privileges to delete 
-      #   all objects from the bucket.
-      #
+      # Deletes all objects in a bucket and then deletes the bucket.
       # @return [nil]
-      #
       def delete!
-        versions.each_batch do |versions|
-          objects.delete(versions)
-        end
-        self.delete
+        clear!
+        delete
       end
 
       # @return [String] bucket owner id
@@ -286,6 +283,76 @@ module AWS
         nil
       end
 
+      # The primary interface for editing the lifecycle configuration.
+      # See {BucketLifecycleConfiguration} for more information.
+      #
+      # @example Adding rules to a bucket's lifecycle configuration
+      #
+      #   bucket.lifecycle_configuration.update do
+      #     add_rule 'cache-1/', 30
+      #     add_rule 'cache-2/', 30
+      #   end
+      #
+      # @example Deleting the lifecycle configuration
+      #
+      #   bucket.lifecycle_configuration.clear
+      #
+      # @return [BucketLifecycleConfiguration]
+      #
+      def lifecycle_configuration
+        @lifecycle_cfg ||= BucketLifecycleConfiguration.new(self)
+      end
+
+      # You can call this method if you prefer to build your own
+      # lifecycle configuration.
+      #
+      #   bucket.lifecycle_configuration = <<-XML
+      #     <LifecycleConfiguration>
+      #       ...
+      #     </LifecycleConfiguration>
+      #   XML
+      #
+      # You can also use this method to copy a lifecycle configuration
+      # from another bucket.
+      #
+      #   bucket.lifecycle_configuration = other_bucket.lifecycle_configuration
+      #
+      # If you call this method, passing nil, the lifecycle configuration 
+      # for this bucket will be deleted.
+      #
+      # @param [String,Object] config You can pass an xml string or any 
+      #   other object that responds to #to_xml (e.g. 
+      #   BucketLifecycleConfiguration).
+      #
+      # @return [nil]
+      #
+      def lifecycle_configuration= config
+
+        if config.nil?
+
+          client_opts = {}
+          client_opts[:bucket_name] = name
+          client.delete_bucket_lifecycle_configuration(client_opts)
+
+          @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :empty => true)
+
+        else
+        
+          xml = config.is_a?(String) ? config : config.to_xml
+
+          client_opts = {}
+          client_opts[:bucket_name] = name
+          client_opts[:lifecycle_configuration] = xml
+          client.set_bucket_lifecycle_configuration(client_opts)
+
+          @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :xml => xml)
+
+        end
+
+        nil
+
+      end
+
       # Returns a tree that allows you to expose the bucket contents
       # like a directory structure.
       #

data/lib/aws/s3/bucket_lifecycle_configuration.rb

@@ -0,0 +1,360 @@
+# 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.
+
+require 'builder'
+require 'uuidtools'
+
+module AWS
+  class S3
+
+    # A lifecycle configuration is collections of rules for a single
+    # bucket that instructs that instruct
+    # Amazon S3 to delete certain objects after a period of days.
+    #
+    # == Rules
+    #
+    # Each lifecycle configuration has a list of rules.  Each rule has the
+    # following attributes:
+    #
+    # * +#prefix+
+    # * +#expiration_days+
+    # * +#status+
+    # * +#id+
+    #
+    # Objects with keys matching a rule prefix will be deleted after 
+    # #expiration_days have passed.
+    # 
+    # A rule is comprised primarily of a prefix and number of expiration days.
+    # Objects with keys that start with the given prefix will be automatically
+    # deleted after "expiration days" have passed.  Rules also have an
+    # ID and a status (they can be disabled).
+    #
+    # See {Rule} for more information on all of the attributes and methods
+    # available for rules.
+    #
+    # == Adding Rules
+    #
+    # You can add a rule to a bucket lifecycle configuration using #{add_rule}.
+    #
+    #   # add a rule that deletes backups after they are 1 year old
+    #   bucket.lifecycle_configuration.update do
+    #     add_rule('backups/', 365)
+    #   end
+    #
+    # If you perfer to specify a rule's ID or status (defaults to 'Enabled')
+    # you can do this with {#add_rule}.
+    #
+    #   # add a rule that deletes backups after they are 1 year old
+    #   bucket.lifecycle_configuration.update do
+    #     add_rule('backups/', 365, :id => 'backup-rule', :disabled => true
+    #   end
+    #
+    # == Replacing Rules
+    #
+    # If you prefer to completely replace a lifecycle configuration, call
+    # #add_rule inside a #replace block instead of an #update block:
+    #
+    #   # replace all existing rules with the following
+    #   bucket.lifecycle_configuration.replace do
+    #     add_rule('backups/', 30)
+    #     add_rule('temp/', 10)
+    #   end
+    #
+    # == Removing Rules
+    #
+    # You can delete specific rules with #remove_rule.
+    #
+    #   # delete all disabled rules
+    #   bucket.lifecycle_configuration.update do
+    #     rules.each do |rule|
+    #       remove_rule(rule) if rule.disabled?
+    #     end
+    #   end
+    #   
+    # You can also remove all rules in a single call:
+    #
+    #   # remove all rules from this lifecycle configuration
+    #   bucket.lifecycle_configuration.clear
+    # 
+    # == Editing Existing Rules
+    #
+    # You can also make changes to existing rules.  
+    #
+    #   # change the expiration days to 10 for EVERY rule
+    #   bucket.lifecycle_configuration.update do
+    #     rules.each do |rule|
+    #       rule.expiration_days = 10
+    #     end
+    #   end
+    #
+    # Please be aware, if you add, remove or edit rules outside of an
+    # #update or #replace block, then you must call {#update} yourself
+    # or the changes will not be persisted.
+    #
+    class BucketLifecycleConfiguration
+      
+      # @private
+      def initialize bucket, options = {}
+        @bucket = bucket
+        @rules = parse_xml(options[:xml]) if options[:xml]
+        @rules = [] if options[:empty] == true
+      end
+
+      # @return [Bucket] Returns the bucket this lifecycle configuration 
+      #   belongs to.
+      attr_reader :bucket
+
+      # @return [Array<Hash>] Returns an array of rules.
+      def rules
+        @rules ||= begin
+          begin
+            opts = { :bucket_name => bucket.name }
+            response = bucket.client.get_bucket_lifecycle_configuration(opts)
+            parse_xml(response.http_response.body)
+          rescue Errors::NoSuchLifecycleConfiguration
+            []
+          end
+        end
+      end
+
+      # @param [String] prefix 
+      #
+      # @param [Integer] expiration_days Indicates the lifetime for objects
+      #   matching the given prefix.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :id A unique ID for this rule.  If an ID
+      #   is not provided, one will be generated.
+      #
+      # @option options [Boolean] :disabled (false) By default, all rules
+      #   will have the status of enabled.  You can override this default
+      #   by passing +:disabled+ => true.
+      #
+      # @return [Rule] Returns the rule that was added, as a {Rule} object.
+      #
+      def add_rule prefix, expiration_days, options = {}
+        id = options[:id] || UUIDTools::UUID.random_create.to_s
+        status = options[:disabled] == true ? 'Disabled' : 'Enabled'
+        rule = Rule.new(self, id, prefix, expiration_days, status)
+        self.rules << rule
+        rule
+      end
+
+      # Removes a single rule.  You can pass a rule id or a {Rule}
+      # object.
+      #
+      #   # remove a single rule by its ID
+      #   bucket.lifecycle_configuration.update do
+      #     remove_rule('rule-id')
+      #   end
+      #   
+      #   # remove all disabled rules
+      #   bucket.lifecycle_configuration.update do
+      #     rules.each do |rule|
+      #       remove_rule(rule) if rule.disabled?
+      #     end
+      #   end
+      #
+      # If you call #remove_rule outside an update block
+      # you need to call #update to save the changes.
+      #
+      # @param [Rule,String] rule_or_rule_id
+      #
+      # @return [nil]
+      # 
+      def remove_rule rule_or_rule_id
+        rule_id = rule_or_rule_id
+        if rule_id.nil?
+          raise ArgumentError, "expected a rule or rule id, got nil"
+        end
+        rule_id = rule_id.id unless rule_id.is_a?(String)
+        @rules = rules.select{|r| r.id != rule_id }
+        nil
+      end
+
+      # Saves changes made to this lifecycle configuration.
+      # 
+      #   # set the number of days before expiration for all rules to 10
+      #   config = bucket.lifecycle_configuration
+      #   config.rules.each do |rule|
+      #     rule.expiration_days = 10
+      #   end
+      #   config.update
+      #
+      # You can call #update with a block.  Changes are persisted at the
+      # end of the block.
+      #
+      #   # shorter version of the example above
+      #   bucket.lifecycle_configuration.update do
+      #     rules.each {|rule| rule.expiration_days = 10 }
+      #   end
+      #
+      # A block method for updating a BucketLifecycleConfiguration.
+      # All modifications made inside the block are persisted at the end of
+      # the block.
+      #
+      #  # 1 request
+      #  bucket.lifecycle_configuration.update do
+      #    add_rule 'prefix/a', 10
+      #    add_rule 'prefix/b', 5
+      #  end
+      #
+      #  # 2 requests
+      #  bucket.lifecycle_configuration.add_rule 'prefix/a', 10
+      #  bucket.lifecycle_configuration.add_rule 'prefix/b', 5
+      # 
+      # @return [nil]
+      #
+      def update &block
+        begin
+          @batching = true
+          instance_eval(&block) if block_given?
+          persist(true)
+        ensure
+          @batching = false
+        end
+        nil
+      end
+
+      # Yields to the given block.  Before yielding, the current
+      # rules will be blanked out.  This allows you to provide all
+      # new rules. 
+      #
+      # When the block is complete, a single call will be made to save
+      # the new rules.
+      #
+      #   bucket.lifecycle_configuration.rules.size #=> 3
+      #
+      #   # replace the existing 3 rules with a single rule
+      #   bucket.lifecycle_configuration.replace
+      #     add_rule 'temp/', 10
+      #   end
+      #
+      #   bucket.lifecycle_configuration.rules.size #=> 1
+      #
+      def replace &block
+        @rules = []
+        update(&block)
+      end
+
+      def clear
+        @rules = []
+        bucket.lifecycle_configuration = nil
+      end
+      alias_method :remove, :clear
+
+      # @return [String] Returns an xml string representation of this
+      #   bucket lifecycle configuration.
+      def to_xml
+        xml = Builder::XmlMarkup.new(:indent => 2)
+        xml.LifecycleConfiguration do
+          rules.each do |rule|
+            xml.Rule do
+              xml.ID rule.id
+              xml.Prefix rule.prefix
+              xml.Status rule.status
+              xml.Expiration do
+                xml.Days rule.expiration_days
+              end
+            end
+          end
+        end.strip
+      end
+
+      protected
+      def persist force = false
+        unless @batching and force == false
+          if rules.empty?
+            bucket.lifecycle_configuration = nil
+          else
+            bucket.lifecycle_configuration = self
+          end
+        end
+      end
+
+      protected
+      def parse_xml xml
+        Client::XML::GetBucketLifecycleConfiguration.parse(xml).rules.map do |r|
+          Rule.new(self, r.id, r.prefix, r.expiration.days, r.status)
+        end
+      end
+
+      # Represents a single rule from an Amazon S3 bucket lifecycle
+      # configuration.
+      #
+      #   # delete all objects with the prefix 'temporary/' after 10 days
+      #   bucket.lifecycle_configuration.add_rule 'temporary/', 10
+      #
+      #   # remove the rule created above
+      #   bucket.lifecycle_configuration.remove_rule 'temporary/'
+      #
+      # 
+      class Rule
+
+        def initialize configuration, id, prefix, expiration_days, status
+          @configuration = configuration
+          @id = id
+          @prefix = prefix
+          @expiration_days = expiration_days
+          @status = status
+        end
+
+        # @return [BucketLifecycleConfiguration]
+        attr_reader :configuration
+
+        # @return [String]
+        attr_reader :id
+
+        # @return [String]
+        attr_accessor :prefix
+
+        # @return [Integer]
+        attr_accessor :expiration_days
+
+        # @return [String] Returns the rule status, 'Enabled' or 'Disabled'
+        attr_accessor :status
+
+        def enabled?
+          status == 'Enabled'
+        end
+
+        def enable!
+          self.status = 'Enabled'
+        end
+
+        def disabled?
+          status == 'Disabled'
+        end
+
+        def disabled!
+          self.status = 'Disabled'
+        end
+
+        # @private
+        def eql? other
+          other.is_a?(Rule) and
+          other.configuration.bucket == configuration.bucket and
+          other.id == id and
+          other.prefix == prefix and
+          other.expiration_days == expiration_days and
+          other.status == status
+        end
+        alias_method :==, :eql?
+
+      end
+
+    end
+
+  end
+end