class S3::Bucket

Attributes

acl[R]
name[R]
service[RW]

Public Instance Methods

==(other) click to toggle source

Compares the bucket with other bucket. Returns true if the names of the buckets are the same, and both have the same services (see Service equality)

# File lib/s3/bucket.rb, line 27
def ==(other)
  self.name == other.name and self.service == other.service
end
acl=(acl) click to toggle source

Assigns a new ACL to the bucket. Please note that ACL is not retrieved from the server and set to “private” by default.

Valid Values: :private | :public_read | :public_read_write | authenticated_read

Example

bucket.acl = :public_read
# File lib/s3/bucket.rb, line 47
def acl=(acl)
  @acl = acl.to_s.gsub("_","-") if acl
end
destroy(force = false) click to toggle source

Destroys given bucket. Raises an S3::Error::BucketNotEmpty exception if the bucket is not empty. You can destroy non-empty bucket passing true (to force destroy)

# File lib/s3/bucket.rb, line 66
def destroy(force = false)
  delete_bucket
  true
rescue Error::BucketNotEmpty
  if force
    objects.destroy_all
    retry
  else
    raise
  end
end
exists?() click to toggle source

Similar to retrieve, but catches S3::Error::NoSuchBucket exceptions and returns false instead. Also catch S3::Error::ForbiddenBucket and return true

# File lib/s3/bucket.rb, line 54
def exists?
  retrieve
  true
rescue Error::ForbiddenBucket
  true
rescue Error::NoSuchBucket
  false
end
host() click to toggle source

Returns host name of the bucket according (see vhost? method)

# File lib/s3/bucket.rb, line 99
def host
  vhost? ? "#@name.#{S3.host}" : "#{S3.host}"
end
location(reload = false) click to toggle source

Returns location of the bucket, e.g. “EU”

# File lib/s3/bucket.rb, line 19
def location(reload = false)
  return @location if defined?(@location) and not reload
  @location = location_constraint
end
object(key) click to toggle source

Returns the object with the given key. Does not check whether the object exists. But also does not issue any HTTP requests, so it's much faster than objects.find

# File lib/s3/bucket.rb, line 121
def object(key)
  Object.send(:new, self, :key => key)
end
objects(params = {}) click to toggle source

Returns the objects in the bucket and caches the result

Parameters

  • params - additional params for list_bucket request.

# File lib/s3/bucket.rb, line 114
def objects(params = {})
  Proxy.new(lambda { list_bucket(params) }, :owner => self, :extend => ObjectsExtension)
end
path_prefix() click to toggle source

Returns path prefix for non VHOST bucket. Path prefix is used instead of VHOST name, e.g. “bucket_name/”

# File lib/s3/bucket.rb, line 105
def path_prefix
  vhost? ? "" : "#@name/"
end
request_acl() click to toggle source

Retrieves acl for bucket from the server.

Return: hash: user|group => permission

# File lib/s3/bucket.rb, line 35
def request_acl
  body = bucket_request(:get, :params => "acl").body
  parse_acl(body)
end
retrieve() click to toggle source

Retrieves the bucket information from the server. Raises an S3::Error exception if the bucket doesn't exist or you don't have access to it.

# File lib/s3/bucket.rb, line 13
def retrieve
  bucket_headers
  self
end
save(options = {}) click to toggle source

Saves the newly built bucket.

Options

  • :location - location of the bucket (:eu or us)

  • Any other options are passed through to Connection#request

# File lib/s3/bucket.rb, line 85
def save(options = {})
  options = {:location => options} unless options.is_a?(Hash)
  create_bucket_configuration(options)
  true
end
save_acl(options = {}) click to toggle source
# File lib/s3/bucket.rb, line 129
def save_acl(options = {})
  headers = {}
  headers[:content_length] = 0
  headers[:x_amz_acl] = options[:acl] || acl || "private"

  bucket_request(:put, :headers => headers, :path => name)
end
vhost?() click to toggle source

Returns true if the name of the bucket can be used like VHOST name. If the bucket contains characters like underscore it can't be used as VHOST (e.g. bucket_name.s3.amazonaws.com)

# File lib/s3/bucket.rb, line 94
def vhost?
  !service.use_ssl && service.use_vhost && "#@name.#{S3.host}" =~ /\A#{URI::REGEXP::PATTERN::HOSTNAME}\Z/
end

Private Instance Methods

bucket_headers(options = {}) click to toggle source
# File lib/s3/bucket.rb, line 168
def bucket_headers(options = {})
  bucket_request(:head, :params => options)
rescue Error::ResponseError => e
  case e.response.code.to_i
    when 404
      raise Error::ResponseError.exception("NoSuchBucket").new("The specified bucket does not exist.", nil)
    when 403
      raise Error::ResponseError.exception("ForbiddenBucket").new("The specified bucket exist but you do not have access to it.", nil)
    else
      raise e
  end
end
bucket_request(method, options = {}) click to toggle source
# File lib/s3/bucket.rb, line 205
def bucket_request(method, options = {})
  path = "#{path_prefix}#{options[:path]}"
  service.send(:service_request, method, options.merge(:host => host, :path => path))
end
create_bucket_configuration(options = {}) click to toggle source
# File lib/s3/bucket.rb, line 181
def create_bucket_configuration(options = {})
  location = options[:location].to_s.upcase if options[:location]
  options[:headers] ||= {}
  if location and location != "US"
    options[:body] = "<CreateBucketConfiguration><LocationConstraint>#{location}</LocationConstraint></CreateBucketConfiguration>"
    options[:headers][:content_type] = "application/xml"
  end
  bucket_request(:put, options)
end
delete_bucket() click to toggle source
# File lib/s3/bucket.rb, line 191
def delete_bucket
  bucket_request(:delete)
end
list_bucket(params = {}) click to toggle source
# File lib/s3/bucket.rb, line 146
def list_bucket(params = {})
  response = bucket_request(:get, :params => params)
  max_keys = params[:max_keys]
  objects_attributes = parse_list_bucket_result(response.body)

  # If there are more than 1000 objects S3 truncates listing and
  # we need to request another listing for the remaining objects.
  while parse_is_truncated(response.body)
    next_request_options = {:marker => URI.escape(objects_attributes.last[:key])}

    if max_keys
      break if objects_attributes.length >= max_keys
      next_request_options[:max_keys] = max_keys - objects_attributes.length
    end

    response = bucket_request(:get, :params => params.merge(next_request_options))
    objects_attributes += parse_list_bucket_result(response.body)
  end

  objects_attributes.map { |object_attributes| Object.send(:new, self, object_attributes) }
end
location_constraint() click to toggle source
# File lib/s3/bucket.rb, line 141
def location_constraint
  response = bucket_request(:get, :params => {:location => nil})
  parse_location_constraint(response.body)
end
name=(name) click to toggle source
# File lib/s3/bucket.rb, line 200
def name=(name)
  raise ArgumentError.new("Invalid bucket name: #{name}") unless name_valid?(name)
  @name = name
end
name_valid?(name) click to toggle source
# File lib/s3/bucket.rb, line 210
def name_valid?(name)
  name =~ /\A[a-z0-9][a-z0-9\._-]{2,254}\Z/i and name !~ /\A#{URI::REGEXP::PATTERN::IPV4ADDR}\Z/
end