Class: AWS::S3::Bucket

Inherits:
Base
  • Object
show all
Includes:
Enumerable
Defined in:
lib/aws/s3/bucket.rb,
lib/aws/s3/response.rb

Overview

Buckets are containers for objects (the files you store on S3). To create a new bucket you just specify its name.

# Pick a unique name, or else you'll get an error 
# if the name is already taken.
Bucket.create('jukebox')

Bucket names must be unique across the entire S3 system, sort of like domain names across the internet. If you try to create a bucket with a name that is already taken, you will get an error.

Assuming the name you chose isn’t already taken, your new bucket will now appear in the bucket list:

Service.buckets
# => [#<AWS::S3::Bucket @attributes={"name"=>"jukebox"}>]

Once you have succesfully created a bucket you can you can fetch it by name using Bucket.find.

music_bucket = Bucket.find('jukebox')

The bucket that is returned will contain a listing of all the objects in the bucket.

music_bucket.objects.size
# => 0

If all you are interested in is the objects of the bucket, you can get to them directly using Bucket.objects.

Bucket.objects('jukebox').size
# => 0

By default all objects will be returned, though there are several options you can use to limit what is returned, such as specifying that only objects whose name is after a certain place in the alphabet be returned, and etc. Details about these options can be found in the documentation for Bucket.find.

To add an object to a bucket you specify the name of the object, its value, and the bucket to put it in.

file = 'black-flowers.mp3'
S3Object.store(file, open(file), 'jukebox')

You’ll see your file has been added to it:

music_bucket.objects
# => [#<AWS::S3::S3Object '/jukebox/black-flowers.mp3'>]

You can treat your bucket like a hash and access objects by name:

jukebox['black-flowers.mp3']
# => #<AWS::S3::S3Object '/jukebox/black-flowers.mp3'>

In the event that you want to delete a bucket, you can use Bucket.delete.

Bucket.delete('jukebox')

Keep in mind, like unix directories, you can not delete a bucket unless it is empty. Trying to delete a bucket that contains objects will raise a BucketNotEmpty exception.

Passing the :force => true option to delete will take care of deleting all the bucket’s objects for you.

Bucket.delete('photos', :force => true)
# => true

Defined Under Namespace

Classes: BucketConfiguration, Response

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

current_bucket, current_host, current_host=, request, set_current_bucket_to

Constructor Details

#initialize(attributes = {}) ⇒ Bucket

:nodoc:



218
219
220
221
222
223
 
# File 'lib/aws/s3/bucket.rb', line 218

def initialize(attributes = {}) #:nodoc:
  super
  @object_cache = []
  @common_prefix_cache = []
  build_contents!
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class AWS::S3::Base

Instance Attribute Details

#common_prefix_cache ⇒ Object (readonly)

:nodoc:



214
215
216
 
# File 'lib/aws/s3/bucket.rb', line 214

def common_prefix_cache
  @common_prefix_cache
end

#object_cache ⇒ Object (readonly)

:nodoc:



214
215
216
 
# File 'lib/aws/s3/bucket.rb', line 214

def object_cache
  @object_cache
end

Class Method Details

.common_prefixes(name = nil, options = {}) ⇒ Object 



171
172
173
 
# File 'lib/aws/s3/bucket.rb', line 171

def common_prefixes(name= nil, options = {})
  find(name, options).common_prefix_cache
end

.create(name, options = {}) ⇒ Object

Creates a bucket named name. 

Bucket.create('jukebox')

Your bucket name must be unique across all of S3. If the name you request has already been taken, you will get a 409 Conflict response, and a BucketAlreadyExists exception will be raised.

By default new buckets have their access level set to private. You can override this using the :access option.

Bucket.create('internet_drop_box', :access => :public_read_write)

By default new buckets will be created in US. You can override this using the :location option.

Bucket.create('internet_drop_box', :location => :eu)

The full list of access levels that you can set on Bucket and S3Object creation are listed in the README in the section called ‘Setting access levels’.



81
82
83
84
85
 
# File 'lib/aws/s3/bucket.rb', line 81

def create(name, options = {})
  validate_name!(name)
  self.current_host = name
  put("/", options, BucketConfiguration.new(options[:location]).to_s).success?
end

.delete(name = nil, options = {}) ⇒ Object

Deletes the bucket named name.

All objects in the bucket must be deleted before the bucket can be deleted. If the bucket is not empty, BucketNotEmpty will be raised.

You can side step this issue by passing the :force => true option to delete which will take care of emptying the bucket before deleting it.

Bucket.delete('photos', :force => true)

Only the owner of a bucket can delete a bucket, regardless of the bucket’s access control policy.



186
187
188
189
190
191
 
# File 'lib/aws/s3/bucket.rb', line 186

def delete(name = nil, options = {})
  find(name).delete_all if options[:force]
  
  name = path(name)
  Base.delete(name).success?
end

.find(name = nil, options = {}) ⇒ Object

Fetches the bucket named name. 

Bucket.find('jukebox')

If a default bucket is inferable from the current connection’s subdomain, or if set explicitly with Base.set_current_bucket, it will be used if no bucket is specified.

MusicBucket.current_bucket
=> 'jukebox'
MusicBucket.find.name
=> 'jukebox'

By default all objects contained in the bucket will be returned (sans their data) along with the bucket. You can access your objects using the Bucket#objects method.

Bucket.find('jukebox').objects

There are several options which allow you to limit which objects are retrieved. The list of object filtering options are listed in the documentation for Bucket.objects.



124
125
126
 
# File 'lib/aws/s3/bucket.rb', line 124

def find(name = nil, options = {})
  new(get(path(name, options)).bucket)
end

.list(reload = false) ⇒ Object

List all your buckets. This is a convenient wrapper around AWS::S3::Service.buckets.



194
195
196
197
 
# File 'lib/aws/s3/bucket.rb', line 194

def list(reload = false)
  self.current_host = nil
  Service.buckets(reload)
end

.objects(name = nil, options = {}) ⇒ Object

Return just the objects in the bucket named name.

By default all objects of the named bucket will be returned. There are options, though, for filtering which objects are returned.

Object filtering options

  • :max_keys - The maximum number of keys you’d like to see in the response body. The server may return fewer than this many keys, but will not return more.

    Bucket.objects('jukebox').size
# => 3
Bucket.objects('jukebox', :max_keys => 1).size
# => 1

  • :prefix - Restricts the response to only contain results that begin with the specified prefix.

    Bucket.objects('jukebox')
# => [<AWS::S3::S3Object '/jazz/miles.mp3'>, <AWS::S3::S3Object '/jazz/dolphy.mp3'>, <AWS::S3::S3Object '/classical/malher.mp3'>]
Bucket.objects('jukebox', :prefix => 'classical')
# => [<AWS::S3::S3Object '/classical/malher.mp3'>]

  • :marker - Marker specifies where in the result set to resume listing. It restricts the response to only contain results that occur alphabetically after the value of marker. To retrieve the next set of results, use the last key from the current page of results as the marker in your next request.

    # Skip 'mahler'
Bucket.objects('jukebox', :marker => 'mb')
# => [<AWS::S3::S3Object '/jazz/miles.mp3'>]

Examples

# Return no more than 2 objects whose key's are listed alphabetically after the letter 'm'.
Bucket.objects('jukebox', :marker => 'm', :max_keys => 2)
# => [<AWS::S3::S3Object '/jazz/miles.mp3'>, <AWS::S3::S3Object '/classical/malher.mp3'>]

# Return no more than 2 objects whose key's are listed alphabetically after the letter 'm' and have the 'jazz' prefix.
Bucket.objects('jukebox', :marker => 'm', :max_keys => 2, :prefix => 'jazz')
# => [<AWS::S3::S3Object '/jazz/miles.mp3'>]



167
168
169
 
# File 'lib/aws/s3/bucket.rb', line 167

def objects(name = nil, options = {})
  find(name, options).object_cache
end

Instance Method Details

#[](object_key) ⇒ Object

Fetches the object named object_key, or nil if the bucket does not contain an object with the specified key.

bucket.objects
=> [#<AWS::S3::S3Object '/marcel_molina/beluga_baby.jpg'>,
    #<AWS::S3::S3Object '/marcel_molina/tongue_overload.jpg'>]
bucket['beluga_baby.jpg']
=> #<AWS::S3::S3Object '/marcel_molina/beluga_baby.jpg'>



233
234
235
 
# File 'lib/aws/s3/bucket.rb', line 233

def [](object_key)
  detect {|file| file.key == object_key.to_s}
end

#common_prefixes(options = {}) ⇒ Object 



276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/aws/s3/bucket.rb', line 276

def common_prefixes(options = {})
  if options.is_a?(Hash)
    reload = !options.empty?
  else
    reload = options
    options = {}
  end
  
  reload!(options) if reload || common_prefix_cache.empty?
  common_prefix_cache
end

#delete(options = {}) ⇒ Object

Deletes the bucket. See its class method counter part Bucket.delete for caveats about bucket deletion and how to ensure a bucket is deleted no matter what.



310
311
312
 
# File 'lib/aws/s3/bucket.rb', line 310

def delete(options = {})
  self.class.delete(name, options)
end

#delete_all ⇒ Object Also known as: clear

Delete all files in the bucket. Use with caution. Can not be undone.



315
316
317
318
319
320
 
# File 'lib/aws/s3/bucket.rb', line 315

def delete_all
  each do |object|
    object.delete
  end
  self
end

#each(&block) ⇒ Object

Iterates over the objects in the bucket.

bucket.each do |object|
  # Do something with the object ...
end



293
294
295
296
 
# File 'lib/aws/s3/bucket.rb', line 293

def each(&block)
  # Dup the collection since we might be destructively modifying the object_cache during the iteration.
  objects.dup.each(&block)
end

#empty? ⇒ Boolean

Returns true if there are no objects in the bucket.

Returns:

  • (Boolean) 


299
300
301
 
# File 'lib/aws/s3/bucket.rb', line 299

def empty?
  objects.empty? && common_prefixes.empty?
end

#new_object(attributes = {}) ⇒ Object

Initializes a new S3Object belonging to the current bucket.

object = bucket.new_object
object.value = data
object.key   = 'classical/mahler.mp3'
object.store
bucket.objects.include?(object)
=> true



245
246
247
248
249
 
# File 'lib/aws/s3/bucket.rb', line 245

def new_object(attributes = {})
  object = S3Object.new(attributes)
  register(object)
  object
end

#objects(options = {}) ⇒ Object

List S3Object’s of the bucket.

Once fetched the objects will be cached. You can reload the objects by passing :reload.

bucket.objects(:reload)

You can also filter the objects using the same options listed in Bucket.objects.

bucket.objects(:prefix => 'jazz')

Using these filtering options will implictly reload the objects.

To reclaim all the objects for the bucket you can pass in :reload again.



264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/aws/s3/bucket.rb', line 264

def objects(options = {})
  if options.is_a?(Hash)
    reload = !options.empty?
  else
    reload  = options
    options = {}
  end
  
  reload!(options) if reload || object_cache.empty?
  object_cache
end

#size ⇒ Object

Returns the number of objects in the bucket.



304
305
306
 
# File 'lib/aws/s3/bucket.rb', line 304

def size
  objects.size
end

#update(action, object) ⇒ Object

Buckets observe their objects and have this method called when one of their objects is either stored or deleted.



325
326
327
328
329
330
 
# File 'lib/aws/s3/bucket.rb', line 325

def update(action, object) #:nodoc:        
  case action
  when :stored  then add object unless objects.include?(object)
  when :deleted then object_cache.delete(object)
  end
end