Module: AWS::S3::Connection::Management::ClassMethods

Defined in:
lib/aws/s3/connection.rb

Overview

Manage the creation and destruction of connections for AWS::S3::Base and its subclasses. Connections are created with establish_connection!.

Instance Method Summary collapse

Instance Method Details

#connected? ⇒ Boolean

Returns true if a connection has been made yet.

Returns:

  • (Boolean) 


224
225
226
227
 
# File 'lib/aws/s3/connection.rb', line 224

def connected?
  Thread.current[:aws_s3_connections] ||= {}
  !Thread.current[:aws_s3_connections].empty?
end

#connection ⇒ Object

Returns the connection for the current class, or Base’s default connection if the current class does not have its own connection.

If not connection has been established yet, NoConnectionEstablished will be raised.



210
211
212
213
214
215
216
 
# File 'lib/aws/s3/connection.rb', line 210

def connection
  if connected?
    connection_called(connection_name) || default_connection
  else
    raise NoConnectionEstablished
  end
end

#connection_called(name) ⇒ Object 



218
219
220
221
 
# File 'lib/aws/s3/connection.rb', line 218

def connection_called(name)
  Thread.current[:aws_s3_connections] ||= {}
  Thread.current[:aws_s3_connections][name]
end

#disconnect(name = connection_name) ⇒ Object

Removes the connection for the current class. If there is no connection for the current class, the default connection will be removed.



231
232
233
234
235
236
237
 
# File 'lib/aws/s3/connection.rb', line 231

def disconnect(name = connection_name)
  name       = default_connection_name unless connections.has_key?(name)
  if connection = connection_called(name)
    connection.http.finish if connection.persistent?
    connections.delete(name)
  end
end

#disconnect! ⇒ Object

Clears all connections, from all classes, for the current thread, with prejudice.



240
241
242
243
 
# File 'lib/aws/s3/connection.rb', line 240

def disconnect!
  Thread.current[:aws_s3_connections] ||= {}
  Thread.current[:aws_s3_connections].each_key {|name| disconnect(name)}
end

#establish_connection!(options = {}) ⇒ Object

Creates a new connection with which to make requests to the S3 servers for the calling class.

AWS::S3::Base.establish_connection!(:access_key_id => '...', :secret_access_key => '...')

You can set connections for every subclass of AWS::S3::Base. Once the initial connection is made on Base, all subsequent connections will inherit whatever values you don’t specify explictly. This allows you to customize details of the connection, such as what server the requests are made to, by just specifying one option. 

AWS::S3::Bucket.established_connection!(:use_ssl => true)

The Bucket connection would inherit the :access_key_id and the :secret_access_key from Base’s connection. Unlike the Base connection, all Bucket requests would be made over SSL.

Required arguments

  • :access_key_id - The access key id for your S3 account. Provided by Amazon.

  • :secret_access_key - The secret access key for your S3 account. Provided by Amazon.

If any of these required arguments is missing, a MissingAccessKey exception will be raised.

Optional arguments

  • :server - The server to make requests to. You can use this to specify your bucket in the subdomain,

or your own domain’s cname if you are using virtual hosted buckets. Defaults to s3.amazonaws.com.

  • :port - The port to the requests should be made on. Defaults to 80 or 443 if the :use_ssl

argument is set.

  • :use_ssl - Whether requests should be made over SSL. If set to true, the :port argument

will be implicitly set to 443, unless specified otherwise. Defaults to false.

  • :persistent - Whether to use a persistent connection to the server. Having this on provides around a two fold

performance increase but for long running processes some firewalls may find the long lived connection suspicious and close the connection. If you run into connection errors, try setting :persistent to false. Defaults to false.

  • :proxy - If you need to connect through a proxy, you can specify your proxy settings by specifying a :host, :port, :user, and :password

with the :proxy option. The :host setting is required if specifying a :proxy. 

AWS::S3::Bucket.established_connection!(:proxy => {
  :host => '...', :port => 8080, :user => 'marcel', :password => 'secret'
})



198
199
200
201
202
203
204
 
# File 'lib/aws/s3/connection.rb', line 198

def establish_connection!(options = {})
  # After you've already established the default connection, just specify 
  # the difference for subsequent connections
  options = default_connection.options.merge(options) if connected?
  Thread.current[:aws_s3_connections] ||= {}
  Thread.current[:aws_s3_connections][connection_name] = Connection.connect(options)
end