public abstract class AmazonWebServiceClient
extends java.lang.Object
Responsible for basic client capabilities that are the same across all AWS SDK Java clients (ex: setting the client endpoint).
Modifier and Type | Field and Description |
---|---|
private static java.lang.String |
AMAZON |
private static java.lang.String |
AWS |
protected AmazonHttpClient |
client
Low level client for sending requests to AWS services.
|
protected ClientConfiguration |
clientConfiguration
The client configuration
|
protected java.net.URI |
endpoint
The service endpoint to which this client will send requests.
|
private java.lang.String |
endpointPrefix
The service name in region metadata, i.e.
|
private static org.apache.commons.logging.Log |
log |
static boolean |
LOGGING_AWS_REQUEST_METRIC |
protected java.util.List<RequestHandler2> |
requestHandler2s
Optional request handlers for additional request processing.
|
private java.lang.String |
serviceName
The cached service abbreviation for this service, used for identifying
service endpoints by region, identifying the necessary signer, etc.
|
private Signer |
signer
AWS signer for authenticating requests.
|
private java.lang.String |
signerRegionOverride
Used to explicitly override the internal signer region computed by the
default implementation.
|
protected int |
timeOffset
Optional offset (in seconds) to use when signing requests
|
Modifier | Constructor and Description |
---|---|
|
AmazonWebServiceClient(ClientConfiguration clientConfiguration)
Constructs a new AmazonWebServiceClient object using the specified
configuration.
|
|
AmazonWebServiceClient(ClientConfiguration clientConfiguration,
RequestMetricCollector requestMetricCollector)
Constructs a new AmazonWebServiceClient object using the specified
configuration and request metric collector.
|
protected |
AmazonWebServiceClient(ClientConfiguration clientConfiguration,
RequestMetricCollector requestMetricCollector,
boolean disableStrictHostNameVerification) |
Modifier and Type | Method and Description |
---|---|
void |
addRequestHandler(RequestHandler requestHandler)
Deprecated.
by
addRequestHandler(RequestHandler2) .
Appends a request handler to the list of registered handlers that are run
as part of a request's lifecycle. |
void |
addRequestHandler(RequestHandler2 requestHandler2)
Appends a request handler to the list of registered handlers that are run
as part of a request's lifecycle.
|
protected <T extends AmazonWebServiceRequest> |
beforeMarshalling(T request)
Runs the
beforeMarshalling method of any
RequestHandler2 s associated with this client. |
private java.lang.String |
computeServiceName()
Returns the service name of this AWS http client by first looking it up
from the SDK internal configuration, and if not found, derive it from the
class name of the immediate subclass of
AmazonWebServiceClient . |
private Signer |
computeSignerByServiceRegion(java.lang.String serviceName,
java.lang.String regionId,
java.lang.String signerRegionOverride,
boolean isRegionIdAsSignerParam)
Returns the signer for the given service name, region id, and the current
client configuration.
|
private Signer |
computeSignerByURI(java.net.URI uri,
java.lang.String signerRegionOverride,
boolean isRegionIdAsSignerParam)
Returns the signer for the given uri and the current client
configuration.
|
void |
configureRegion(Regions region)
Convenient method for setting region.
|
protected ExecutionContext |
createExecutionContext()
Deprecated.
by
createExecutionContext(AmazonWebServiceRequest) .
This method exists only for backward compatiblity reason, so
that clients compiled against the older version of this class
won't get NoSuchMethodError at runtime. However,
calling this methods would effectively ignore and disable the
request metric collector, if any, specified at the request
level. Request metric collector specified at the service
client or AWS SDK level will still be honored. |
protected ExecutionContext |
createExecutionContext(AmazonWebServiceRequest req) |
protected ExecutionContext |
createExecutionContext(Request<?> req) |
protected void |
endClientExecution(AWSRequestMetrics awsRequestMetrics,
Request<?> request,
Response<?> response)
Convenient method to end the client execution without logging the
awsRequestMetrics.
|
protected void |
endClientExecution(AWSRequestMetrics awsRequestMetrics,
Request<?> request,
Response<?> response,
boolean loggingAwsRequestMetrics)
Common routine to end a client AWS request/response execution and collect
the request metrics.
|
protected RequestMetricCollector |
findRequestMetricCollector(Request<?> req)
Returns the most specific request metric collector, starting from the
request level, then client level, then finally the AWS SDK level.
|
java.lang.String |
getEndpointPrefix() |
private java.lang.String |
getHttpClientName() |
RequestMetricCollector |
getRequestMetricsCollector()
Returns the client specific
RequestMetricCollector ; or null if
there is none. |
protected java.lang.String |
getServiceAbbreviation()
Deprecated.
by
getServiceName() . |
java.lang.String |
getServiceName()
Returns the service abbreviation for this service, used for identifying
service endpoints by region, identifying the necessary signer, etc.
|
protected java.lang.String |
getServiceNameIntern()
Internal method for implementing
getServiceName() . |
protected Signer |
getSigner()
Returns the signer.
|
Signer |
getSignerByURI(java.net.URI uri)
Returns the signer based on the given URI and the current AWS client
configuration.
|
java.lang.String |
getSignerRegionOverride()
Returns the signer region override.
|
int |
getTimeOffset()
Returns the optional value for time offset for this client.
|
protected static boolean |
isProfilingEnabled() |
protected boolean |
isRequestMetricsEnabled(AmazonWebServiceRequest req)
Returns true if request metric collection is applicable to the given
request; false otherwise.
|
private boolean |
isRMCEnabledAtClientOrSdkLevel()
Returns true if request metric collection is enabled at the service
client or AWS SDK level request; false otherwise.
|
void |
removeRequestHandler(RequestHandler requestHandler)
Removes a request handler from the list of registered handlers that are run
as part of a request's lifecycle.
|
void |
removeRequestHandler(RequestHandler2 requestHandler2) |
protected RequestMetricCollector |
requestMetricCollector()
Returns the client specific request metric collector if there is one; or
the one at the AWS SDK level otherwise.
|
void |
setEndpoint(java.lang.String endpoint)
Overrides the default endpoint for this client.
|
protected void |
setEndpointPrefix(java.lang.String endpointPrefix)
An internal method used to explicitly override the service name for region metadata.
|
void |
setRegion(Region region)
An alternative to
setEndpoint(String) , sets the regional
endpoint for this client's service calls. |
void |
setServiceNameIntern(java.lang.String serviceName)
An internal method used to explicitly override the service name
computed by the default implementation.
|
void |
setSignerRegionOverride(java.lang.String signerRegionOverride)
An internal method used to explicitly override the internal signer region
computed by the default implementation.
|
void |
setTimeOffset(int timeOffset)
Sets the optional value for time offset for this client.
|
void |
shutdown()
Shuts down this client object, releasing any resources that might be held
open.
|
private java.net.URI |
toURI(java.lang.String endpoint)
Returns the endpoint as a URI.
|
<T extends AmazonWebServiceClient> |
withEndpoint(java.lang.String endpoint)
Fluent method for
setEndpoint(String) . |
<T extends AmazonWebServiceClient> |
withRegion(Region region)
Fluent method for
setRegion(Region) . |
<T extends AmazonWebServiceClient> |
withRegion(Regions region)
Convenient fluent method for setting region.
|
AmazonWebServiceClient |
withTimeOffset(int timeOffset)
Sets the optional value for time offset for this client.
|
private static final java.lang.String AMAZON
private static final java.lang.String AWS
public static final boolean LOGGING_AWS_REQUEST_METRIC
private static final org.apache.commons.logging.Log log
protected volatile java.net.URI endpoint
Subclass should only read but not assign to this field, at least not without synchronization on the enclosing object for thread-safety reason.
private volatile java.lang.String signerRegionOverride
protected ClientConfiguration clientConfiguration
protected AmazonHttpClient client
protected final java.util.List<RequestHandler2> requestHandler2s
protected int timeOffset
private volatile Signer signer
private volatile java.lang.String serviceName
private volatile java.lang.String endpointPrefix
public AmazonWebServiceClient(ClientConfiguration clientConfiguration)
clientConfiguration
- The client configuration for this client.public AmazonWebServiceClient(ClientConfiguration clientConfiguration, RequestMetricCollector requestMetricCollector)
clientConfiguration
- The client configuration for this client.requestMetricCollector
- optional request metric collector to be used at the http
client level; can be null.protected AmazonWebServiceClient(ClientConfiguration clientConfiguration, RequestMetricCollector requestMetricCollector, boolean disableStrictHostNameVerification)
protected Signer getSigner()
Note, however, the signer configured for S3 is incomplete at this stage as the information on the S3 bucket and key is not yet known.
public void setEndpoint(java.lang.String endpoint) throws java.lang.IllegalArgumentException
This method is not threadsafe. Endpoints should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit.
Callers can pass in just the endpoint (ex: "ec2.amazonaws.com") or a full
URL, including the protocol (ex: "https://ec2.amazonaws.com"). If the
protocol is not specified here, the default protocol from this client's
ClientConfiguration
will be used, which by default is HTTPS.
For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID=3912
endpoint
- The endpoint (ex: "ec2.amazonaws.com") or a full URL,
including the protocol (ex: "https://ec2.amazonaws.com") of
the region specific AWS endpoint this client will communicate
with.java.lang.IllegalArgumentException
- If any problems are detected with the specified endpoint.private java.net.URI toURI(java.lang.String endpoint) throws java.lang.IllegalArgumentException
java.lang.IllegalArgumentException
public Signer getSignerByURI(java.net.URI uri)
Note, however, the signer returned for S3 is incomplete at this stage as the information on the S3 bucket and key is not yet known.
private Signer computeSignerByURI(java.net.URI uri, java.lang.String signerRegionOverride, boolean isRegionIdAsSignerParam)
Note, however, the signer returned for S3 is incomplete at this stage as the information on the S3 bucket and key is not yet known.
signerRegionOverride
- the overriding signer region; or null if there is none.isRegionIdAsSignerParam
- true if the "regionId" is used to configure the signer if
applicable; false if this method is called for the purpose of
purely setting the communication end point of this AWS client,
and therefore the "regionId" parameter will not be used
directly for configuring the signer.private Signer computeSignerByServiceRegion(java.lang.String serviceName, java.lang.String regionId, java.lang.String signerRegionOverride, boolean isRegionIdAsSignerParam)
Note, however, the signer returned for S3 is incomplete at this stage as the information on the S3 bucket and key is not yet known.
regionId
- the region for sending AWS requestssignerRegionOverride
- the overriding signer region; or null if there is none.isRegionIdAsSignerParam
- true if the "regionId" is used to configure the signer if
applicable; false if this method is called for the purpose of
purely setting the communication end point of this AWS client,
and therefore the "regionId" parameter will not be used
directly for configuring the signer.public void setRegion(Region region) throws java.lang.IllegalArgumentException
setEndpoint(String)
, sets the regional
endpoint for this client's service calls. Callers can use this method to control which AWS
region they want to work with.
This method is not threadsafe. A region should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
By default, all service endpoints in all regions use the https protocol. To use http instead,
specify it in the ClientConfiguration
supplied at construction.
region
- The region this client will communicate with. See
Region.getRegion(com.amazonaws.regions.Regions)
for accessing a given
region.java.lang.IllegalArgumentException
- If the given region is null, or if this service isn't available in the given
region. See Region.isServiceSupported(String)
Region.getRegion(com.amazonaws.regions.Regions)
,
Region.createClient(Class, com.amazonaws.auth.AWSCredentialsProvider,
ClientConfiguration)
public final void configureRegion(Regions region)
region
- region to set to; must not be null.setRegion(Region)
public void shutdown()
@Deprecated public void addRequestHandler(RequestHandler requestHandler)
addRequestHandler(RequestHandler2)
.
Appends a request handler to the list of registered handlers that are run
as part of a request's lifecycle.requestHandler
- The new handler to add to the current list of request
handlers.public void addRequestHandler(RequestHandler2 requestHandler2)
requestHandler2
- The new handler to add to the current list of request
handlers.public void removeRequestHandler(RequestHandler requestHandler)
requestHandler
- The handler to remove from the current list of request
handlers.public void removeRequestHandler(RequestHandler2 requestHandler2)
protected final <T extends AmazonWebServiceRequest> T beforeMarshalling(T request)
beforeMarshalling
method of any
RequestHandler2
s associated with this client.request
- the request passed in from the userprotected ExecutionContext createExecutionContext(AmazonWebServiceRequest req)
protected final ExecutionContext createExecutionContext(Request<?> req)
@Deprecated protected final ExecutionContext createExecutionContext()
createExecutionContext(AmazonWebServiceRequest)
.
This method exists only for backward compatiblity reason, so
that clients compiled against the older version of this class
won't get NoSuchMethodError
at runtime. However,
calling this methods would effectively ignore and disable the
request metric collector, if any, specified at the request
level. Request metric collector specified at the service
client or AWS SDK level will still be honored.protected static boolean isProfilingEnabled()
protected final boolean isRequestMetricsEnabled(AmazonWebServiceRequest req)
private boolean isRMCEnabledAtClientOrSdkLevel()
public void setTimeOffset(int timeOffset)
timeOffset
- The optional value for time offset (in seconds) for this client.public AmazonWebServiceClient withTimeOffset(int timeOffset)
timeOffset
- The optional value for time offset (in seconds) for this client.public int getTimeOffset()
public RequestMetricCollector getRequestMetricsCollector()
RequestMetricCollector
; or null if
there is none.protected RequestMetricCollector requestMetricCollector()
protected final RequestMetricCollector findRequestMetricCollector(Request<?> req)
protected final void endClientExecution(AWSRequestMetrics awsRequestMetrics, Request<?> request, Response<?> response)
protected final void endClientExecution(AWSRequestMetrics awsRequestMetrics, Request<?> request, Response<?> response, @Deprecated boolean loggingAwsRequestMetrics)
AWSRequestMetrics.Field.ClientExecuteTime
and call this method
in a try-finally block.loggingAwsRequestMetrics
- deprecated and ignored@Deprecated protected java.lang.String getServiceAbbreviation()
getServiceName()
.public java.lang.String getServiceName()
public java.lang.String getEndpointPrefix()
protected void setEndpointPrefix(java.lang.String endpointPrefix)
protected java.lang.String getServiceNameIntern()
getServiceName()
. Method is
protected by intent so peculiar subclass that don't follow the class
naming convention can choose to return whatever service name as needed.public final void setServiceNameIntern(java.lang.String serviceName)
private java.lang.String computeServiceName()
AmazonWebServiceClient
.
No configuration is necessary if the simple class name of the http client
follows the convention of (Amazon|AWS).*(JavaClient|Client)
.private java.lang.String getHttpClientName()
public final java.lang.String getSignerRegionOverride()
setSignerRegionOverride(String).
public final void setSignerRegionOverride(java.lang.String signerRegionOverride)
public <T extends AmazonWebServiceClient> T withRegion(Region region)
setRegion(Region)
.
Example: AmazonDynamoDBClient client = new AmazonDynamoDBClient(...).withRegion(...);
setRegion(Region)
public <T extends AmazonWebServiceClient> T withRegion(Regions region)
region
- region to set to; must not be null.withRegion(Region)
public <T extends AmazonWebServiceClient> T withEndpoint(java.lang.String endpoint)
setEndpoint(String)
.
Example: AmazonDynamoDBClient client = new AmazonDynamoDBClient(...).withEndPoint(...);
setEndpoint(String)