class AWS::Core::Client

Base class for all of the Amazon AWS service clients. @private

Constants

CACHEABLE_REQUESTS

Attributes

config[R]

@return [Configuration] This clients configuration.

signer[R]

@return [DefaultSigner,Object] Returns the signer for this client.

This is normally a DefaultSigner, but it can be configured to
an other object.

Public Class Methods

new(options = {}) click to toggle source

Creates a new low-level client.

Required Options

To create a client you must provide access to AWS credentials. There are two options:

:signer – An object that responds to access_key_id (to return the AWS Access Key ID) and to sign(string_to_sign) (to return a signature for a given string). An example implementation is AWS::Core::DefaultSigner. This option is useful if you want to more tightly control access to your secret access key (for example by moving the signature computation into a different process).
:access_key_id and :secret_access_key – You can use these options to provide the AWS Access Key ID and AWS Secret Access Key directly to the client.

Optional

:http_handler – Any object that implements a handle(request, response) method; an example is BuiltinHttpHandler. This method is used to perform the HTTP requests that this client constructs.

# File lib/aws/core/client.rb, line 56
def initialize options = {}
  
  if options[:endpoint]
    options[:"#{self.class.service_ruby_name}_endpoint"] = 
      options.delete(:endpoint)
  end
  
  options_without_config = options.dup
  @config = options_without_config.delete(:config)
  @config ||= AWS.config
  @config = @config.with(options_without_config)
  @signer = @config.signer
  @http_handler = @config.http_handler
  @stubs = {}
  
end

Protected Class Methods

configure_client() click to toggle source

# File lib/aws/core/client.rb, line 437
def self.configure_client
  
  module_eval('module Options; end')
  module_eval('module XML; end')
  
end

Public Instance Methods

endpoint() click to toggle source

@return [String] the configured endpoint for this client.

# File lib/aws/core/client.rb, line 82
def endpoint
  config.send(:"#{self.class.service_ruby_name}_endpoint")
end

new_stub_for(method_name) click to toggle source

Primarily used for testing, this method returns an empty psuedo service response without making a request. Its used primarily for testing the ligher level service interfaces. @private

# File lib/aws/core/client.rb, line 135
def new_stub_for method_name
  response = Response.new(Http::Request.new, Http::Response.new)
  response.request_type = method_name
  response.request_options = {}
  send("simulate_#{method_name}_response", response)
  response.signal_success
  response
end

stub_for(method_name) click to toggle source

The stub returned is memoized. @see #new_stub_for @private

# File lib/aws/core/client.rb, line 127
def stub_for method_name
  @stubs[method_name] ||= new_stub_for(method_name)
end

with_config(config) click to toggle source

@param [Configuration] The configuration object to use. @return [Core::Client] Returns a new client object with the given

configuration.

# File lib/aws/core/client.rb, line 120
def with_config config
  self.class.new(:config => config)
end

with_http_handler(handler = nil, &blk) click to toggle source

Returns a copy of the client with a different HTTP handler. You can pass an object like BuiltinHttpHandler or you can use a block; for example:

s3_with_logging = s3.with_http_handler do |request, response|
  $stderr.puts request.inspect
  super
end

The block executes in the context of an HttpHandler instance, and super delegates to the HTTP handler used by this client. This provides an easy way to spy on requests and responses. See HttpHandler, HttpRequest, and HttpResponse for more details on how to implement a fully functional HTTP handler using a different HTTP library than the one that ships with Ruby. @param handler (nil) A new http handler. Leave blank and pass a

block to wrap the current handler with the block.

@return [Core::Client] Returns a new instance of the client class with

the modified or wrapped http handler.

# File lib/aws/core/client.rb, line 106
def with_http_handler(handler = nil, &blk)
  handler ||= Http::Handler.new(@http_handler, &blk)
  with_options(:http_handler => handler)
end

with_options(options) click to toggle source

@param [Hash] options @see AWS.config detailed list of accepted options.

# File lib/aws/core/client.rb, line 113
def with_options options
  with_config(config.with(options))
end

Protected Instance Methods

extract_error_code(response) click to toggle source

# File lib/aws/core/client.rb, line 295
def extract_error_code response
  if response.http_response.status >= 300 and
      body = response.http_response.body and
      parse = xml_error_grammar.parse(body) and
      parse.respond_to?(:code)
    parse.code
  end
end

new_request() click to toggle source

# File lib/aws/core/client.rb, line 145
def new_request
  req = self.class::REQUEST_CLASS.new
  req.http_method = 'POST'
  req.headers['Content-Type'] = 'application/x-www-form-urlencoded; charset=utf-8'
  req.add_param 'Timestamp', Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
  req.add_param 'Version', self.class::API_VERSION
  req
end

new_response(*args, &block) click to toggle source

# File lib/aws/core/client.rb, line 155
def new_response(*args, &block)
  Response.new(*args, &block)
end

populate_error(response) click to toggle source

# File lib/aws/core/client.rb, line 267
def populate_error response
  
  # clear out a previous error
  response.error = nil
  status = response.http_response.status
  code = nil
  code = extract_error_code(response)

  case
  when response.timeout?
    response.error = Timeout::Error.new
  
  when code
    response.error =
      service_module::Errors.error_class(code).new(response.http_request,
                                                   response.http_response)
  when status >= 500
    response.error =
      Errors::ServerError.new(response.http_request, response.http_response)
  
  when status >= 300
    response.error =
      Errors::ClientError.new(response.http_request, response.http_response)
  end
  
end

service_module() click to toggle source

# File lib/aws/core/client.rb, line 315
def service_module
  AWS.const_get(self.class.to_s[%r(\w+)::Client/, 1])
end

xml_error_grammar() click to toggle source

# File lib/aws/core/client.rb, line 305
def xml_error_grammar
  if service_module::const_defined?(:Errors) and
      service_module::Errors::const_defined?(:BASE_ERROR_GRAMMAR)
    service_module::Errors::BASE_ERROR_GRAMMAR
  else
    XmlGrammar
  end
end