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)

[View source]

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)

[View source]

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)
[View source]

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)

[View source]

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

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

#inspect ⇒ Object

:nodoc:

[View source]

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”

[View source]

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

[View source]

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.

[View source]

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/”

[View source]

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

[View source]

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.

[View source]

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

[View source]

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

[View source]

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)
[View source]

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