class AWS::S3::Bucket

@return [String] The bucket name

@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.

# 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

@return [Boolean] Returns true if the two buckets have the same name.

# File lib/aws/s3/bucket.rb, line 137
def ==(other)
  other.kind_of?(Bucket) && other.name == name
end

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

@return [AccessControlList]

# File lib/aws/s3/bucket.rb, line 204
def acl
  acl = client.get_bucket_acl(:bucket_name => name).acl
  acl.extend ACLProxy
  acl.bucket = self
  acl
end

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.

@param [AccessControlList] acl @return [nil]

# File lib/aws/s3/bucket.rb, line 221
def acl=(acl)
  client.set_bucket_acl(:bucket_name => name, :acl => acl)
  nil
end

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

@see Tree @param [Hash] options @option options [String] :prefix (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.

@option options [String] :delimiter (‘/’) The string that separates

each level of the tree.  This is usually a directory separator.

@option options [Boolean] :append (true) If true, the delimiter is

appended to the prefix when the prefix does not already end
with the delimiter.

@return [Tree]

# File lib/aws/s3/bucket.rb, line 373
def as_tree options = {}
  objects.as_tree(options)
end

Deletes all objects from this bucket. @return [nil]

# File lib/aws/s3/bucket.rb, line 105
def clear!
  versions.each_batch do |versions|
    objects.delete(versions)
  end
end

Deletes the current bucket. An error will be raised if the bucket is not empty. @return [nil]

# File lib/aws/s3/bucket.rb, line 114
def delete
  client.delete_bucket(:bucket_name => @name)
  nil
end

Deletes all objects in a bucket and then deletes the bucket. @return [nil]

# File lib/aws/s3/bucket.rb, line 121
def delete!
  clear!
  delete
end

@return [Boolean] Returns true if the bucket has no objects

(this includes versioned objects that are delete markers).

# File lib/aws/s3/bucket.rb, line 58
def empty?
  versions.first ? false : true
end

Enables versioning on this bucket. @return [nil]

# File lib/aws/s3/bucket.rb, line 70
def enable_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :enabled)
  nil
end

@return [Boolean] Returns true if the two buckets have the same name

# File lib/aws/s3/bucket.rb, line 142
def eql?(other_bucket)
  self == other_bucket
end

@note This method only indicates if there is a bucket in S3, not

if you have permissions to work with the bucket or not.

@return [Boolean] Returns true if the bucket exists in S3.

# File lib/aws/s3/bucket.rb, line 149
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

@private

# File lib/aws/s3/bucket.rb, line 132
def inspect
  "#<AWS::S3::Bucket:#{name}>"
end

The primary interface for editing the lifecycle configuration. See {BucketLifecycleConfiguration} for more information.

@example Adding rules to a bucket’s lifecycle configuration

bucket.lifecycle_configuration.update do
  add_rule 'cache-1/', 30
  add_rule 'cache-2/', 30
end

@example Deleting the lifecycle configuration

bucket.lifecycle_configuration.clear

@return [BucketLifecycleConfiguration]

# File lib/aws/s3/bucket.rb, line 302
def lifecycle_configuration
  @lifecycle_cfg ||= BucketLifecycleConfiguration.new(self)
end

You can call this method if you prefer to build your own lifecycle configuration.

bucket.lifecycle_configuration = <<-XML
  <LifecycleConfiguration>
    ...
  </LifecycleConfiguration>
XML

You can also use this method to copy a lifecycle configuration from another bucket.

bucket.lifecycle_configuration = other_bucket.lifecycle_configuration

If you call this method, passing nil, the lifecycle configuration for this bucket will be deleted.

@param [String,Object] config You can pass an xml string or any

other object that responds to #to_xml (e.g. 
BucketLifecycleConfiguration).

@return [nil]

# File lib/aws/s3/bucket.rb, line 329
def lifecycle_configuration= config

  if config.nil?

    client_opts = {}
    client_opts[:bucket_name] = name
    client.delete_bucket_lifecycle_configuration(client_opts)

    @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :empty => true)

  else
  
    xml = config.is_a?(String) ? config : config.to_xml

    client_opts = {}
    client_opts[:bucket_name] = name
    client_opts[:lifecycle_configuration] = xml
    client.set_bucket_lifecycle_configuration(client_opts)

    @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :xml => xml)

  end

  nil

end

@return [String,nil] Returns the location constraint for a bucket

(if it has one), nil otherwise.

# File lib/aws/s3/bucket.rb, line 64
def location_constraint
  client.get_bucket_location(:bucket_name => name).location_constraint
end

@return [MultipartUploadCollection] Represents all of the

multipart uploads that are in progress for this bucket.

# File lib/aws/s3/bucket.rb, line 177
def multipart_uploads
  MultipartUploadCollection.new(self)
end

@return [ObjectCollection] Represents all objects(keys) in

this bucket.

# File lib/aws/s3/bucket.rb, line 165
def objects
  ObjectCollection.new(self)
end

@return [String] bucket owner id

# File lib/aws/s3/bucket.rb, line 127
def owner
  @owner || client.list_buckets.owner
end

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.

@return [Policy,nil] Returns the bucket policy (if it has one),

or it returns +nil+ otherwise.

# File lib/aws/s3/bucket.rb, line 265
def policy
  policy = client.get_bucket_policy(:bucket_name => name).policy
  policy.extend(PolicyProxy)
  policy.bucket = self
  policy
rescue Errors::NoSuchBucketPolicy => e
  nil
end

Sets the bucket’s policy.

@param 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+.

@see Policy @return [nil]

# File lib/aws/s3/bucket.rb, line 281
def policy=(policy)
  client.set_bucket_policy(:bucket_name => name, :policy => policy)
  nil
end

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

@see PresignedPost

# File lib/aws/s3/bucket.rb, line 381
def presigned_post(options = {})
  PresignedPost.new(self, options)
end

Suspends versioning on this bucket. @return [nil]

# File lib/aws/s3/bucket.rb, line 79
def suspend_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :suspended)
  nil
end

Returns the url for this bucket. @return [String] url to the bucket

# 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

@return [Boolean] returns true if version is enabled on this bucket.

# File lib/aws/s3/bucket.rb, line 87
def versioning_enabled?
  versioning_state == :enabled
end

Returns the versioning status for this bucket. States include:

• :enabled - currently enabled

• :suspended - currently suspended

• :unversioned - versioning has never been enabled

@return [Symbol] the versioning state

# File lib/aws/s3/bucket.rb, line 99
def versioning_state
  client.get_bucket_versioning(:bucket_name => @name).status
end

@return [BucketVersionCollection] Represents all of the versioned

objects stored in this bucket.

# File lib/aws/s3/bucket.rb, line 171
def versions
  BucketVersionCollection.new(self)
end