Class: AWS::S3::Bucket

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/s3/bucket.rb

Overview

Represents a single S3 bucket.

Examples:

Creating a Bucket


bucket = s3.buckets.create('mybucket')

Getting an Existing Bucket


bucket = s3.buckets['mybucket']

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Bucket

Returns a new instance of Bucket.

Parameters:

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

Options Hash (options):

  • :owner (String) — default: nil —

    The owner id of this bucket.



34
35
36
37
38
39
40
41
 
# File 'lib/aws/s3/bucket.rb', line 34

def initialize(name, options = {})
  # the S3 docs disagree with what the service allows,
  # so it's not safe to toss out invalid bucket names
  # S3::Client.validate_bucket_name!(name)
  @name = name
  @owner = options[:owner]
  super
end

Instance Attribute Details

#name ⇒ String (readonly)

Returns The bucket name.

Returns:

  • (String) —

    The bucket name



44
45
46
 
# File 'lib/aws/s3/bucket.rb', line 44

def name
  @name
end

Instance Method Details

#==(other) ⇒ Boolean

Returns true if the two buckets have the same name.

Returns:

  • (Boolean) —

    Returns true if the two buckets have the same name.



140
141
142
 
# File 'lib/aws/s3/bucket.rb', line 140

def ==(other)
  other.kind_of?(Bucket) && other.name == name
end

#acl ⇒ AccessControlList

Returns the bucket’s access control list. This will be an instance of AccessControlList, plus an additional change method:

bucket.acl.change do |acl|
  acl.grants.reject! do |g|
    g.grantee.canonical_user_id != bucket.owner.id
  end
end

Returns:



207
208
209
210
211
212
 
# File 'lib/aws/s3/bucket.rb', line 207

def acl
  acl = client.get_bucket_acl(:bucket_name => name).acl
  acl.extend ACLProxy
  acl.bucket = self
  acl
end

#acl=(acl) ⇒ nil

Sets the bucket’s access control list. acl can be:

  • An XML policy as a string (which is passed to S3 uninterpreted)

  • An AccessControlList object

  • Any object that responds to to_xml

  • Any Hash that is acceptable as an argument to AccessControlList#initialize.

Parameters:

Returns:

  • (nil) 


224
225
226
227
 
# File 'lib/aws/s3/bucket.rb', line 224

def acl=(acl)
  client.set_bucket_acl(:bucket_name => name, :acl => acl)
  nil
end

#as_tree(options = {}) ⇒ Tree

Returns a tree that allows you to expose the bucket contents like a directory structure.

Parameters:

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

Options Hash (options):

  • :prefix (String) — default: nil —

    Set prefix to choose where the top of the tree will be. A value of nil means that the tree will include all objects in the collection.

  • :delimiter (String) — default: '/' —

    The string that separates each level of the tree. This is usually a directory separator.

  • :append (Boolean) — default: true —

    If true, the delimiter is appended to the prefix when the prefix does not already end with the delimiter.

Returns:

See Also:



306
307
308
 
# File 'lib/aws/s3/bucket.rb', line 306

def as_tree options = {}
  objects.as_tree(options)
end

#delete ⇒ nil

Note:

This operation will fail if the bucket is not empty.

Deletes the current bucket.

Returns:

  • (nil) 


109
110
111
112
 
# File 'lib/aws/s3/bucket.rb', line 109

def delete
  client.delete_bucket(:bucket_name => @name)
  nil
end

#delete! ⇒ nil

Note:

This operation may fail if you do not have privileges to delete all objects from the bucket.

Attempts to delete all objects (or object versions) from the bucket and then attempts to delete the bucket.

Returns:

  • (nil) 


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

def delete!
  versions.each_batch do |versions|
    objects.delete(versions)
  end
  self.delete
end

#empty? ⇒ Boolean

Returns true if the bucket has no objects (this includes versioned objects that are delete markers).

Returns:

  • (Boolean) —

    Returns true if the bucket has no objects (this includes versioned objects that are delete markers).



58
59
60
 
# File 'lib/aws/s3/bucket.rb', line 58

def empty?
  versions.first ? false : true
end

#enable_versioning ⇒ nil

Enables versioning on this bucket.

Returns:

  • (nil) 


70
71
72
73
74
75
 
# File 'lib/aws/s3/bucket.rb', line 70

def enable_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :enabled)
  nil
end

#eql?(other_bucket) ⇒ Boolean

Returns true if the two buckets have the same name

Returns:

  • (Boolean) —

    Returns true if the two buckets have the same name



145
146
147
 
# File 'lib/aws/s3/bucket.rb', line 145

def eql?(other_bucket)
  self == other_bucket
end

#exists? ⇒ Boolean

Note:

This method only indicates if there is a bucket in S3, not if you have permissions to work with the bucket or not.

Returns true if the bucket exists in S3.

Returns:

  • (Boolean) —

    Returns true if the bucket exists in S3.



152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/aws/s3/bucket.rb', line 152

def exists?
  begin
    versioned? # makes a get bucket request without listing contents
               # raises a client error if the bucket doesn't exist or
               # if you don't have permission to get the bucket 
               # versioning status.
    true
  rescue Errors::NoSuchBucket => e
    false # bucket does not exist
  rescue Errors::ClientError => e
    true # bucket exists
  end
end

#location_constraint ⇒ String?

Returns the location constraint for a bucket (if it has one), nil otherwise.

Returns:

  • (String, nil) —

    Returns the location constraint for a bucket (if it has one), nil otherwise.



64
65
66
 
# File 'lib/aws/s3/bucket.rb', line 64

def location_constraint
  client.get_bucket_location(:bucket_name => name).location_constraint
end

#multipart_uploads ⇒ MultipartUploadCollection

Returns Represents all of the multipart uploads that are in progress for this bucket.

Returns:



180
181
182
 
# File 'lib/aws/s3/bucket.rb', line 180

def multipart_uploads
  MultipartUploadCollection.new(self)
end

#objects ⇒ ObjectCollection

Returns Represents all objects(keys) in this bucket.

Returns:



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

def objects
  ObjectCollection.new(self)
end

#owner ⇒ String

Returns bucket owner id.

Returns:

  • (String) —

    bucket owner id



130
131
132
 
# File 'lib/aws/s3/bucket.rb', line 130

def owner
  @owner || client.list_buckets.owner
end

#policy ⇒ Policy?

Returns the bucket policy. This will be an instance of Policy. The returned policy will also have the methods of PolicyProxy mixed in, so you can use it to change the current policy or delete it, for example:

if policy = bucket.policy
  # add a statement
  policy.change do |p|
    p.allow(...)
  end

  # delete the policy
  policy.delete
end

Note that changing the policy is not an atomic operation; it fetches the current policy, yields it to the block, and then sets it again. Therefore, it’s possible that you may overwrite a concurrent update to the policy using this method.

Returns:

  • (Policy, nil) —

    Returns the bucket policy (if it has one), or it returns nil otherwise.



268
269
270
271
272
273
274
275
 
# File 'lib/aws/s3/bucket.rb', line 268

def policy
  policy = client.get_bucket_policy(:bucket_name => name).policy
  policy.extend(PolicyProxy)
  policy.bucket = self
  policy
rescue Errors::NoSuchBucketPolicy => e
  nil
end

#policy=(policy) ⇒ nil

Sets the bucket’s policy.

Parameters:

  • policy —

    The new policy. This can be a string (which is assumed to contain a valid policy expressed in JSON), a Policy object or any object that responds to to_json.

Returns:

  • (nil)

See Also:



284
285
286
287
 
# File 'lib/aws/s3/bucket.rb', line 284

def policy=(policy)
  client.set_bucket_policy(:bucket_name => name, :policy => policy)
  nil
end

#presigned_post(options = {}) ⇒ Object

Generates fields for a presigned POST to this object. All options are sent to the PresignedPost constructor.

See Also:



314
315
316
 
# File 'lib/aws/s3/bucket.rb', line 314

def presigned_post(options = {})
  PresignedPost.new(self, options)
end

#suspend_versioning ⇒ nil

Suspends versioning on this bucket.

Returns:

  • (nil) 


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

def suspend_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :suspended)
  nil
end

#url ⇒ String

Returns the url for this bucket.

Returns:

  • (String) —

    url to the bucket



48
49
50
51
52
53
54
 
# File 'lib/aws/s3/bucket.rb', line 48

def url
  if client.dns_compatible_bucket_name?(name)
    "http://#{name}.s3.amazonaws.com/"
  else
    "http://s3.amazonaws.com/#{name}/"
  end
end

#versioning_enabled? ⇒ Boolean Also known as: versioned?

Returns true if version is enabled on this bucket.

Returns:

  • (Boolean) —

    returns true if version is enabled on this bucket.



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

def versioning_enabled?
  versioning_state == :enabled
end

#versioning_state ⇒ Symbol

Returns the versioning status for this bucket. States include:

  • :enabled - currently enabled

  • :suspended - currently suspended

  • :unversioned - versioning has never been enabled

Returns:

  • (Symbol) —

    the versioning state



99
100
101
 
# File 'lib/aws/s3/bucket.rb', line 99

def versioning_state
  client.get_bucket_versioning(:bucket_name => @name).status
end

#versions ⇒ BucketVersionCollection

Returns Represents all of the versioned objects stored in this bucket.

Returns:



174
175
176
 
# File 'lib/aws/s3/bucket.rb', line 174

def versions
  BucketVersionCollection.new(self)
end