Class: S3::Bucket

Inherits:
Object
  • Object
show all
Includes:
Proxies, Parser
Defined in:
lib/s3/bucket.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Parser

#parse_acl, #parse_copy_object_result, #parse_error, #parse_is_truncated, #parse_list_all_my_buckets_result, #parse_list_bucket_result, #parse_location_constraint, #rexml_document

Instance Attribute Details

#acl ⇒ Object

Returns the value of attribute acl.



6
7
8
 
# File 'lib/s3/bucket.rb', line 6

def acl
  @acl
end

#name ⇒ Object

Returns the value of attribute name.



6
7
8
 
# File 'lib/s3/bucket.rb', line 6

def name
  @name
end

#service ⇒ Object

Returns the value of attribute service.



6
7
8
 
# File 'lib/s3/bucket.rb', line 6

def service
  @service
end

Instance Method Details

#==(other) ⇒ Object

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)



27
28
29
 
# File 'lib/s3/bucket.rb', line 27

def ==(other)
  self.name == other.name and self.service == other.service
end

#destroy(force = false) ⇒ Object

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)



66
67
68
69
70
71
72
73
74
75
76
 
# 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? ⇒ Boolean

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

Returns:

  • (Boolean) 


54
55
56
57
58
59
60
61
 
# File 'lib/s3/bucket.rb', line 54

def exists?
  retrieve
  true
rescue Error::ForbiddenBucket
  true
rescue Error::NoSuchBucket
  false
end

#host ⇒ Object

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



99
100
101
 
# File 'lib/s3/bucket.rb', line 99

def host
  vhost? ? "#@name.#{S3.host}" : "#{S3.host}"
end

#inspect ⇒ Object

:nodoc:



125
126
127
 
# File 'lib/s3/bucket.rb', line 125

def inspect #:nodoc:
  "#<#{self.class}:#{name}>"
end

#location(reload = false) ⇒ Object

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



19
20
21
22
 
# 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) ⇒ Object

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



121
122
123
 
# File 'lib/s3/bucket.rb', line 121

def object(key)
  Object.send(:new, self, :key => key)
end

#objects(params = {}) ⇒ Object

Returns the objects in the bucket and caches the result

Parameters

  • params - additional params for list_bucket request.



114
115
116
 
# File 'lib/s3/bucket.rb', line 114

def objects(params = {})
  Proxy.new(lambda { list_bucket(params) }, :owner => self, :extend => ObjectsExtension)
end

#path_prefix ⇒ Object

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



105
106
107
 
# File 'lib/s3/bucket.rb', line 105

def path_prefix
  vhost? ? "" : "#@name/"
end

#request_acl ⇒ Object

Retrieves acl for bucket from the server.

Return: hash: user|group => permission



35
36
37
38
 
# File 'lib/s3/bucket.rb', line 35

def request_acl
  body = bucket_request(:get, :params => "acl").body
  parse_acl(body)
end

#retrieve ⇒ Object

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.



13
14
15
16
 
# File 'lib/s3/bucket.rb', line 13

def retrieve
  bucket_headers
  self
end

#save(options = {}) ⇒ Object

Saves the newly built bucket.

Options

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

  • Any other options are passed through to Connection#request



85
86
87
88
89
 
# 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 = {}) ⇒ Object 



129
130
131
132
133
134
135
 
# 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? ⇒ Boolean

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)

Returns:

  • (Boolean) 


94
95
96
 
# 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