Class AWS::S3::ObjectCollection
In: lib/aws/s3/object_collection.rb
Parent: Object

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']

Methods

Included Modules

Core::Model Enumerable PrefixAndDelimiterCollection

Classes and Modules

Class AWS::S3::ObjectCollection::BatchHelper

Attributes

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

Public Class methods

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

Public Instance methods

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]

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 {S3Object#write}.

@see S3Object#write

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

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]

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

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 =~ /\.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.

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]

Protected Instance methods

[Validate]