class AWS::S3::ObjectCollection

Represents a collection of S3 objects.

Getting an S3Object by Key

If you know the key of the object you want, you can reference it this way:

# this will not make any requests against S3
object = bucket.objects['foo.jpg']
object.key #=> 'foo.jpg'

Finding objects with a Prefix

Given a bucket with the following keys:

photos/sunset.jpg
photos/sunrise.jpg
photos/winter.jpg
videos/comedy.mpg
videos/dancing.mpg

You can list objects that share a prefix:

bucket.objects.with_prefix('videos').collect(&:key)
#=> ['videos/comedy.mpg', 'videos/dancing.mpg']

Exploring Objects with a Tree Interface

Given a bucket with the following keys:

README.txt
videos/wedding.mpg
videos/family_reunion.mpg
photos/2010/house.jpg
photos/2011/fall/leaves.jpg
photos/2011/summer/vacation.jpg
photos/2011/summer/family.jpg

tree = bucket.objects.with_prefix('photos').as_tree

directories = tree.children.select(&:branch?).collect(&:prefix)
#=> ['photos/2010', 'photos/2011']

Attributes

bucket[R]

@return [Bucket] The bucket this collection belongs to.

Public Class Methods

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

@param [Bucket] The S3 bucket this object collection belongs to.

# File lib/aws/s3/object_collection.rb, line 66
def initialize(bucket, options = {})
  @bucket = bucket
  super
end

Public Instance Methods

[](key) click to toggle source

Returns an S3Object given its name. For example:

@example

object = bucket.objects['file.txt']
object.class #=> S3Object

@param [String] key The object key. @return [S3Object]

# File lib/aws/s3/object_collection.rb, line 96
def [] key
  S3Object.new(bucket, key.to_s)
end

create(key, *args) click to toggle source

Writes a new object to S3.

The first param is the key you want to write this object to. All other params/options are documented in {AWS::S3::S3Object#write}.

@see AWS::S3::S3Object#write

@param [String] key Where in S3 to write the object. @return [S3Object]

# File lib/aws/s3/object_collection.rb, line 83
def create key, *args
  self[key].write(*args)
end

delete(*objects) click to toggle source

Deletes the objects provided in as few requests as possible.

# delete 2 objects (by key) in a single request
bucket.objects.delete('abc', 'xyz')

You can delete objects also by passing their S3Object representation:

to_delete = []
to_delete << buckets.objects['foo']
to_delete << buckets.objects['bar']

bucket.objects.delete(to_delete)

@param [Mixed] objects One or more objects to delete. Each object

can be one of the following:

* An object key (string)
* A hash with :key and :version_id (for versioned objects)
* An {S3Object} instance
* An {ObjectVersion} instance

@raise [BatchDeleteError] If any of the objects failed to delete,

a BatchDeleteError will be raised with a summary of the errors.

@return [nil]

# File lib/aws/s3/object_collection.rb, line 131
def delete *objects

  objects = objects.flatten.collect do |obj|
    case obj
    when String        then { :key => obj }
    when Hash          then obj
    when S3Object      then { :key => obj.key }
    when ObjectVersion then { :key => obj.key, :version_id => obj.version_id }
    else  
      msg = "objects must be keys (strings or hashes with :key and " +
            ":version_id), S3Objects or ObjectVersions, got " +
            object.class.name
      raise ArgumentError, msg
    end
  end

  batch_helper = BatchHelper.new(1000) do |batch|
    client_opts = {}
    client_opts[:bucket_name] = bucket.name
    client_opts[:quiet] = true
    client_opts[:objects] = batch
    client.delete_objects(client_opts)
  end

  error_counts = {}
  batch_helper.after_batch do |response|
    response.errors.each do |error|
      error_counts[error.code] ||= 0
      error_counts[error.code] += 1
    end
  end

  objects.each do |object|
    batch_helper.add(object)
  end

  batch_helper.complete!

  raise Errors::BatchDeleteError.new(error_counts) unless 
    error_counts.empty?

  nil

end

delete_all() click to toggle source

Deletes all objects represented by this collection.

@example Delete all objects from a bucket

bucket.objects.delete_all

@example Delete objects with a given prefix

bucket.objects.with_prefix('2009/').delete_all

@raise [BatchDeleteError] If any of the objects failed to delete,

a BatchDeleteError will be raised with a summary of the errors.

@return [Array] Returns an array of results

# File lib/aws/s3/object_collection.rb, line 230
def delete_all

  error_counts = {}

  each_batch do |objects|
    begin
      delete(objects)
    rescue Errors::BatchDeleteError => error
      error.error_counts.each_pair do |code,count|
        error_counts[code] ||= 0
        error_counts[code] += count
      end
    end
  end

  raise Errors::BatchDeleteError.new(error_counts) unless 
    error_counts.empty?

  nil

end

delete_if() { |object| ... } click to toggle source

Deletes each object in the collection that returns a true value from block passed to this method. Deletes are batched for efficiency.

# delete text files in the 2009 "folder"
bucket.objects.with_prefix('2009/').delete_if {|o| o.key =~ %r\.txt$/ }

@yieldparam [S3Object] object

@raise [BatchDeleteError] If any of the objects failed to delete,

a BatchDeleteError will be raised with a summary of the errors.

# File lib/aws/s3/object_collection.rb, line 187
def delete_if &block

  error_counts = {}

  batch_helper = BatchHelper.new(1000) do |objects| 
    begin
      delete(objects)
    rescue Errors::BatchDeleteError => error
      error.error_counts.each_pair do |code,count|
        error_counts[code] ||= 0
        error_counts[code] += count
      end
    end
  end

  each do |object|
    batch_helper.add(object) if yield(object)
  end

  batch_helper.complete!

  raise Errors::BatchDeleteError.new(error_counts) unless 
    error_counts.empty?

  nil

end

each(options = {}) click to toggle source

Iterates the collection, yielding instances of S3Object.

Use break or raise an exception to terminate the enumeration.

@param [Hash] options @option options [Integer] :limit (nil) The maximum number of

objects to yield.

@option options [Integer] :batch_size (1000) The number of objects to

fetch each request to S3.  Maximum is 1000 keys at time.

@return [nil]

# File lib/aws/s3/object_collection.rb, line 262
def each options = {}, &block
  super
end

with_prefix(prefix, mode = :replace) click to toggle source

(see AWS::S3::PrefixedCollection#with_prefix)

# File lib/aws/s3/object_collection.rb, line 101
def with_prefix prefix, mode = :replace
  super(prefix, mode)
end

Protected Instance Methods

each_member_in_page(page) { |s3_object| ... } click to toggle source

@private

# File lib/aws/s3/object_collection.rb, line 268
def each_member_in_page(page, &block)
  super
  page.contents.each do |content|
    yield(S3Object.new(bucket, content.key))
  end
end

limit_param() click to toggle source

@private

# File lib/aws/s3/object_collection.rb, line 283
def limit_param
  :max_keys
end

list_request(options) click to toggle source

@private

# File lib/aws/s3/object_collection.rb, line 277
def list_request options
  client.list_objects(options)
end

next_markers(page) click to toggle source

@private

# File lib/aws/s3/object_collection.rb, line 289
def next_markers page
  marker = (last = page.contents.last and last.key)
  if marker.nil?
    raise 'Unable to find marker in S3 list objects response'
  else
    { :marker => marker }
  end
end