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 29
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 49
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)

def destroy(force = false)
  delete_bucket
  true
rescue Error::BucketNotEmpty
  if force
    objects.destroy_all
    retry
  else
    raise
  end
end
# File lib/s3/bucket.rb, line 81
def destroy(force = false)
  if objects.any?
          if force
       objects.destroy_all
       delete_bucket
       true
    else
      raise
    end
  else
    delete_bucket
    true
  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 56
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 122
def host
  vhost? ? "#@name.#{HOST}" : "#{service.host}"
end
location(reload = false) click to toggle source

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

# File lib/s3/bucket.rb, line 21
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 144
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 137
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 128
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 37
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 15
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 103
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 153
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 112
def vhost?
    #MEGAM_FIX. If this method returns true "MethodNotAllowed" exception arises. (parse_error': undefined method `text' for nil:NilClass)
    #Fix for bucketname without '_'
    #HOST & PATH======vhost=flase======>192.168.1.102<======>asd2/<==========
    #HOST & PATH======vhost=true======>asd2.s3.amazonaws.com<======><==========
  #!service.use_ssl && service.use_vhost && "#@name.#{HOST}" =~ /\A#{URI::REGEXP::PATTERN::HOSTNAME}\Z/
    false
end

Private Instance Methods

bucket_headers(options = {}) click to toggle source
# File lib/s3/bucket.rb, line 192
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 229
def bucket_request(method, options = {})
  path = "#{path_prefix}#{options[:path]}"
  service_request(method, options.merge(:host => host, :path => path))
end
create_bucket_configuration(options = {}) click to toggle source
# File lib/s3/bucket.rb, line 205
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 215
def delete_bucket
  bucket_request(:delete)
end
list_bucket(params = {}) click to toggle source
# File lib/s3/bucket.rb, line 170
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 165
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 224
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 234
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