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 29 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 49 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)
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
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
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
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
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
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
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
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
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 103 def save(options = {}) options = {:location => options} unless options.is_a?(Hash) create_bucket_configuration(options) true end
# 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
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
# 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
# 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
# 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
# File lib/s3/bucket.rb, line 215 def delete_bucket bucket_request(:delete) end
# 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
# File lib/s3/bucket.rb, line 165 def location_constraint response = bucket_request(:get, :params => {:location => nil}) parse_location_constraint(response.body) end
# File lib/s3/bucket.rb, line 224 def name=(name) raise ArgumentError.new("Invalid bucket name: #{name}") unless name_valid?(name) @name = name end
# 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