Class: AWS::S3::ObjectCollection

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/aws/s3/object_collection.rb

Overview

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.prefix('photos').as_tree

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

Instance Attribute Summary collapse

Attributes included from PrefixedCollection

#prefix

Instance Method Summary collapse

Constructor Details

#initialize(bucket, options = {}) ⇒ ObjectCollection

Returns a new instance of ObjectCollection.

Parameters:

  • The (Bucket) —

    S3 bucket this object collection belongs to.



70
71
72
73
 
# File 'lib/aws/s3/object_collection.rb', line 70

def initialize(bucket, options = {})
  @bucket = bucket
  super
end

Instance Attribute Details

#bucket ⇒ Bucket (readonly)

Returns The bucket this collection belongs to.

Returns:

  • (Bucket) —

    The bucket this collection belongs to.



76
77
78
 
# File 'lib/aws/s3/object_collection.rb', line 76

def bucket
  @bucket
end

Instance Method Details

#[](key) ⇒ S3Object

Returns an S3Object given its name. For example:

Examples:


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

Parameters:

  • key (String) —

    The object key.

Returns:



100
101
102
 
# File 'lib/aws/s3/object_collection.rb', line 100

def [] key
  S3Object.new(bucket, key.to_s)
end

#create(key, *args) ⇒ 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.

Parameters:

  • key (String) —

    Where in S3 to write the object.

Returns:

See Also:



87
88
89
 
# File 'lib/aws/s3/object_collection.rb', line 87

def create key, *args
  self[key].write(*args)
end

#each(options = {}, &block) ⇒ nil

Iterates the collection, yielding instances of S3Object.

Use break or raise an exception to terminate the enumeration.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :limit (Integer) — default: nil —

    The maximum number of objects to yield.

  • :batch_size (Integer) — default: 1000 —

    The number of objects to fetch each request to S3. Maximum is 1000 keys at time.

Returns:

  • (nil) 


119
120
121
 
# File 'lib/aws/s3/object_collection.rb', line 119

def each options = {}, &block
  super
end

#with_prefix(prefix, mode = :replace) ⇒ Collection

Returns a new collection with a different prefix

Examples:

objects = collection.with_prefix('photos')
objects.prefix #=> 'photos'

Chaining with_prefix replaces previous prefix

objects = collection.with_prefix('photos').with_prefix('videos')
objects.prefix #=> 'videos'

Chaining with_prefix with :append

objects = collection.with_prefix('a/').with_prefix('b/', :append)
objects.prefix #=> 'a/b/'

Chaining with_prefix with :prepend

objects = collection.with_prefix('a/').with_prefix('b/', :prepend)
objects.prefix #=> 'b/a/'

Parameters:

  • prefix (String) —

    The prefix condition that limits what objects are returned by this collection.

  • mode (Symbol) (defaults to: :replace) —

    (:replace) If you chain calls to #with_prefix the mode affects if the prefix prepends, appends, or replaces. Valid modes are:

    • :replace

    • :append

    • :prepend

Returns:

  • (Collection) —

    Returns a new collection with a modified prefix.



105
106
107
 
# File 'lib/aws/s3/object_collection.rb', line 105

def with_prefix prefix, mode = :replace
  super(prefix, mode)
end