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] bucket The S3 bucket this object collection belongs to. @param [Hash] options

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)

@overload delete(objects)

  @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

@overload delete(objects, options)

  Deletes multiple objects, with additional options. The array can
  contain any of the types of objects the first method invocation style
  accepts.
  @param [Array] objects One or more objects to delete.
  @param [Hash] options Optional headers to pass on.

@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

@api private

[Validate]