class S3::Bucket
Attributes
Public Instance Methods
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
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
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
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
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
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
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
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
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
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
Saves the newly built bucket.
Options¶ ↑
-
:location
- location of the bucket (:eu
orus
) -
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
# 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
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
# 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
# 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
# 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
# File lib/s3/bucket.rb, line 191 def delete_bucket bucket_request(:delete) end
# 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
# File lib/s3/bucket.rb, line 141 def location_constraint response = bucket_request(:get, :params => {:location => nil}) parse_location_constraint(response.body) end
# File lib/s3/bucket.rb, line 200 def name=(name) raise ArgumentError.new("Invalid bucket name: #{name}") unless name_valid?(name) @name = name end
# 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