class AWS::S3::BucketLifecycleConfiguration

A lifecycle configuration specify {Rule rules} that manage the way Amazon S3 stores objects. The rules apply to objects whose keys match the rule's prefix.

## Rules

A rule is comprised primarily of an id, prefix and set of configuration options. Configuration options on the rules can specify:

See {Rule} for more information on all of the attributes and methods available for rules.

## Expiring Objects

You can add a rule to a bucket lifecycle configuration using {#add_rule} inside of an {#update} block that will expire an object after a given number of days:

# delete backups after they are 1 year old
bucket.lifecycle_configuration.update do
  add_rule('backups/', :expiration_time => 365)
end

You can also define the rule to expire objects at a specific date:

# delete backups on January 1st of next year
bucket.lifecycle_configuration.update do
  date = Date.new(Time.now.year + 1, 01, 01)
  add_rule('backups/', :expiration_time => date)
end

## Transitioning Objects to Glacier

You can add a rule to a bucket lifecycle configuration using {#add_rule} inside of an {#update} block that will transition objects to Glacier after a given number of days:

# move backups to Glacier after 3 days
bucket.lifecycle_configuration.update do
  add_rule('backups/', :glacier_transition_time => 3)
end

You can also define the rule to transition objects at a specific date:

# transition all backups on January 1st of next year
bucket.lifecycle_configuration.update do
  date = Date.new(Time.now.year + 1, 01, 01)
  add_rule('backups/', :glacier_transition_time => date)
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/', :glacier_transition_time => 10)
  add_rule('temp/', :expiration_time => 30)
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 with {#clear}:

# 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_time = 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.

Attributes

bucket[R]

@return [Bucket] Returns the bucket this lifecycle configuration

belongs to.

Public Class Methods

new(bucket, options = {}) click to toggle source

@api private

# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 119
def initialize bucket, options = {}
  @bucket = bucket
  @rules = parse_xml(options[:xml]) if options[:xml]
  @rules = [] if options[:empty] == true
end

Public Instance Methods

add_rule(prefix, expiration_time = nil, options = {}) click to toggle source

@overload #add_rule(prefix, options = {})

@param [String] prefix objects whose keys begin with this prefix
  will be affected by the rule.

@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 %x:disabled` => true.

@option options [Date, Integer] :expiration_time (nil) Indicates
  the lifetime for objects matching the given prefix.

@option options [Date, Integer] :glacier_transition_time (nil)
  Indicates the time before objects matching the given prefix will
  be transitioned into the Amazon Glacier storage tier.

@return [Rule] Returns the rule that was added, as a {Rule} object.
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 161
def add_rule prefix, expiration_time = nil, options = {}
  if Hash === expiration_time
    options = expiration_time
  else
    options[:expiration_time] = expiration_time
  end

  id = options[:id] || UUIDTools::UUID.random_create.to_s
  opts = {
    :status => options[:disabled] == true ? 'Disabled' : 'Enabled',
    :expiration_time => options[:expiration_time],
    :glacier_transition_time => options[:glacier_transition_time]
  }
  rule = Rule.new(self, id, prefix, opts)
  self.rules << rule
  rule
end
clear() click to toggle source
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 275
def clear
  @rules = []
  bucket.lifecycle_configuration = nil
end
Also aliased as: remove
remove()
Alias for: clear
remove_rule(rule_or_rule_id) click to toggle source

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]

# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 201
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
replace(&block) click to toggle source

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
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 270
def replace &block
  @rules = []
  update(&block)
end
rules() click to toggle source

@return [Array<Hash>] Returns an array of rules.

# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 130
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
to_xml() click to toggle source

@return [String] Returns an xml string representation of this

bucket lifecycle configuration.
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 283
def to_xml
  Nokogiri::XML::Builder.new do |xml|
    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
            if Integer === rule.expiration_time
              xml.Days rule.expiration_time
            else
              date = rule.expiration_time.to_s
              xml.Date "#{date}T00:00:00Z"
            end
          end if rule.expiration_time
          xml.Transition do
            xml.StorageClass 'GLACIER'
            if Integer === rule.glacier_transition_time
              xml.Days rule.glacier_transition_time
            else
              date = rule.glacier_transition_time.to_s
              xml.Date "#{date}T00:00:00Z"
            end
          end if rule.glacier_transition_time
        end
      end
    end
  end.doc.root.to_xml
end
update(&block) click to toggle source

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_time = 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_time = 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]

# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 244
def update &block
  begin
    @batching = true
    instance_eval(&block) if block_given?
    persist(true)
  ensure
    @batching = false
  end
  nil
end

Protected Instance Methods

parse_xml(xml) click to toggle source
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 436
def parse_xml xml
  Client::XML::GetBucketLifecycleConfiguration.parse(xml).rules.map do |r|
    opts = { :status => r[:status] }

    if r[:expiration]
      opts[:expiration_time] =
        r[:expiration][:days] || r[:expiration][:date]
    end

    if r[:transition]
      opts[:glacier_transition_time] =
        r[:transition][:days] || r[:transition][:date]
    end

    Rule.new(self, r[:id], r[:prefix], opts)
  end
end
persist(force = false) click to toggle source
# File lib/aws/s3/bucket_lifecycle_configuration.rb, line 315
def persist force = false
  unless @batching and force == false
    if rules.empty?
      bucket.lifecycle_configuration = nil
    else
      bucket.lifecycle_configuration = self
    end
  end
end