Class: AWS::S3::Base
- Inherits:
-
Object
- Object
- AWS::S3::Base
- Defined in:
- lib/aws/s3/base.rb,
lib/aws/s3/response.rb
Overview
AWS::S3::Base is the abstract super class of all classes who make requests against S3, such as the built in Service, Bucket and S3Object classes. It provides methods for making requests, inferring or setting response classes, processing request options, and accessing attributes from S3’s response data.
Establishing a connection with the Base class is the entry point to using the library:
AWS::S3::Base.establish_connection!(:access_key_id => '...', :secret_access_key => '...')
The :access_key_id
and :secret_access_key
are the two required connection options. More details can be found in the docs for Connection::Management::ClassMethods.
Extensive examples can be found in the README.
Defined Under Namespace
Classes: RequestOptions, Response
Class Method Summary collapse
- .current_bucket ⇒ Object
-
.current_host ⇒ Object
Called when a method which requires a bucket name is called without that bucket name specified.
- .current_host=(host) ⇒ Object
-
.request(verb, path, options = {}, body = nil, attempts = 0, &block) ⇒ Object
Wraps the current connection’s request method and picks the appropriate response class to wrap the response in.
-
.set_current_bucket_to(name) ⇒ Object
(also: current_bucket=)
If you plan on always using a specific bucket for certain files, you can skip always having to specify the bucket by creating a subclass of Bucket or S3Object and telling it what bucket to use:.
Instance Method Summary collapse
-
#initialize(attributes = {}) ⇒ Base
constructor
:nodoc:.
Constructor Details
#initialize(attributes = {}) ⇒ Base
:nodoc:
231 232 233 |
# File 'lib/aws/s3/base.rb', line 231 def initialize(attributes = {}) #:nodoc: @attributes = attributes end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &block) ⇒ Object (private)
258 259 260 261 262 263 264 265 266 267 |
# File 'lib/aws/s3/base.rb', line 258 def method_missing(method, *args, &block) case when attributes.has_key?(method.to_s) attributes[method.to_s] when attributes.has_key?(method) attributes[method] else super end end |
Class Method Details
.current_bucket ⇒ Object
128 129 130 |
# File 'lib/aws/s3/base.rb', line 128 def current_bucket connection.subdomain or raise CurrentBucketNotSpecified.new(connection.http.address) end |
.current_host ⇒ Object
Called when a method which requires a bucket name is called without that bucket name specified. It will try to infer the current bucket by looking for it as the subdomain of the current connection’s address. If no subdomain is found, CurrentBucketNotSpecified will be raised.
MusicBucket.establish_connection! :server => 'jukeboxzero.s3.amazonaws.com'
MusicBucket.connection.server
=> 'jukeboxzero.s3.amazonaws.com'
MusicBucket.current_bucket
=> 'jukeboxzero'
Rather than infering the current bucket from the subdomain, the current class’ bucket can be explicitly set with set_current_bucket_to.
120 121 122 |
# File 'lib/aws/s3/base.rb', line 120 def current_host @@current_host end |
.current_host=(host) ⇒ Object
124 125 126 |
# File 'lib/aws/s3/base.rb', line 124 def current_host=(host) @@current_host = host end |
.request(verb, path, options = {}, body = nil, attempts = 0, &block) ⇒ Object
Wraps the current connection’s request method and picks the appropriate response class to wrap the response in. If the response is an error, it will raise that error as an exception. All such exceptions can be caught by rescuing their superclass, the ResponseError exception class.
It is unlikely that you would call this method directly. Subclasses of Base have convenience methods for each http request verb that wrap calls to request.
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 |
# File 'lib/aws/s3/base.rb', line 69 def request(verb, path, = {}, body = nil, attempts = 0, &block) Service.response = nil (, verb) response = response_class.new(connection.request(verb, path, , body, attempts, current_host, &block)) Service.response = response Error::Response.new(response.response).error.raise if response.error? if attempts > 0 && !current_host.match(".#{DEFAULT_HOST}") establish_connection!(:server => DEFAULT_HOST) end response # Once in a while, a request to S3 returns an internal error. A glitch in the matrix I presume. Since these # errors are few and far between the request method will rescue InternalErrors the first three times they encouter them # and will retry the request again. Most of the time the second attempt will work. rescue InternalError, RequestTimeout if attempts == 3 raise else attempts += 1 retry end rescue raise unless response if response.redirect? new_host = response.parsed['endpoint'] establish_connection!(:server => new_host) end attempts == 3 || !response.redirect? ? raise : (attempts += 1; retry) end |
.set_current_bucket_to(name) ⇒ Object Also known as: current_bucket=
If you plan on always using a specific bucket for certain files, you can skip always having to specify the bucket by creating a subclass of Bucket or S3Object and telling it what bucket to use:
class JukeBoxSong < AWS::S3::S3Object
set_current_bucket_to 'jukebox'
end
For all methods that take a bucket name as an argument, the current bucket will be used if the bucket name argument is omitted.
other_song = 'baby-please-come-home.mp3'
JukeBoxSong.store(other_song, open(other_song))
This time we didn’t have to explicitly pass in the bucket name, as the JukeBoxSong class knows that it will always use the ‘jukebox’ bucket.
“Astute readers”, as they say, may have noticed that we used the third parameter to pass in the content type, rather than the fourth parameter as we had the last time we created an object. If the bucket can be inferred, or is explicitly set, as we’ve done in the JukeBoxSong class, then the third argument can be used to pass in options.
Now all operations that would have required a bucket name no longer do.
other_song = JukeBoxSong.find('baby-please-come-home.mp3')
155 156 157 158 159 160 161 162 |
# File 'lib/aws/s3/base.rb', line 155 def set_current_bucket_to(name) raise ArgumentError, "`#{__method__}' must be called on a subclass of #{self.name}" if self == AWS::S3::Base instance_eval(<<-EVAL) def current_bucket '#{name}' end EVAL end |