com.amazonaws

Class AmazonWebServiceRequest

java.lang.Object

com.amazonaws.AmazonWebServiceRequest

All Implemented Interfaces:

HandlerContextAware, ReadLimitInfo, Cloneable

Direct Known Subclasses:

PresignerFacade.PresigningRequest

@NotThreadSafe
public abstract class AmazonWebServiceRequest
extends Object
implements Cloneable, ReadLimitInfo, HandlerContextAware

Base class for all user facing web service requests.

Field Summary

Fields

Modifier and Type	Field and Description
static AmazonWebServiceRequest	NOOP

Constructor Summary

Constructors

Constructor and Description
AmazonWebServiceRequest()

Method Summary

Modifier and Type	Method and Description
<X> void	addHandlerContext(HandlerContextKey<X> key, X value) Adds a context to that is visible to all RequestHandler2s.
AmazonWebServiceRequest	clone() Creates a shallow clone of this object for all fields except the handler context.
protected <T extends AmazonWebServiceRequest> T	copyBaseTo(T target) Copies the internal state of this base class to that of the target request.
AmazonWebServiceRequest	getCloneRoot() Returns the root object from which the current object was cloned; or null if there isn't one.
AmazonWebServiceRequest	getCloneSource() Returns the source object from which the current object was cloned; or null if there isn't one.
Map<String,List<String>>	getCustomQueryParameters()
Map<String,String>	getCustomRequestHeaders() Returns an immutable map of custom header names to header values.
ProgressListener	getGeneralProgressListener() Returns the optional progress listener for receiving updates about the progress of the request.
<X> X	getHandlerContext(HandlerContextKey<X> key) Return the context for the given key if present; else return null.
int	getReadLimit() Returns the read limit for mark-and-reset during retries; or -1 if not available.
RequestClientOptions	getRequestClientOptions() Gets the options stored with this request object.
AWSCredentials	getRequestCredentials() Deprecated. by getRequestCredentialsProvider()
AWSCredentialsProvider	getRequestCredentialsProvider() Returns the optional credentials provider to use to sign this request, overriding the default credentials provider at the client level.
RequestMetricCollector	getRequestMetricCollector() Returns a request level metric collector; or null if not specified.
Integer	getSdkClientExecutionTimeout() Returns the amount of time (in milliseconds) to allow the client to complete the execution of an API call.
Integer	getSdkRequestTimeout() Returns the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out.
void	putCustomQueryParameter(String name, String value) Add a custom query parameter for the request.
String	putCustomRequestHeader(String name, String value) Put a new custom header to the map of custom header names to custom header values, and return the previous value if the header has already been set in this map.
void	setGeneralProgressListener(ProgressListener progressListener) Sets the optional progress listener for receiving updates about the progress of the request.
void	setRequestCredentials(AWSCredentials credentials) Deprecated. by setRequestCredentialsProvider(AWSCredentialsProvider). If you must use AWSCredentials you can wrap it with a AWSStaticCredentialsProvider.
void	setRequestCredentialsProvider(AWSCredentialsProvider credentialsProvider) Sets the optional credentials provider to use for this request, overriding the default credentials provider at the client level.
void	setRequestMetricCollector(RequestMetricCollector requestMetricCollector) Sets a request level request metric collector which takes precedence over the ones at the http client level and AWS SDK level.
void	setSdkClientExecutionTimeout(int sdkClientExecutionTimeout) Sets the amount of time (in milliseconds) to allow the client to complete the execution of an API call.
void	setSdkRequestTimeout(int sdkRequestTimeout) Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out.
<T extends AmazonWebServiceRequest> T	withGeneralProgressListener(ProgressListener progressListener) Sets the optional progress listener for receiving updates about the progress of the request, and returns a reference to this object so that method calls can be chained together.
<T extends AmazonWebServiceRequest> T	withRequestCredentialsProvider(AWSCredentialsProvider credentialsProvider) Sets the optional credentials provider to use for this request, overriding the default credentials provider at the client level.
<T extends AmazonWebServiceRequest> T	withRequestMetricCollector(RequestMetricCollector metricCollector) Specifies a request level metric collector which takes precedence over the ones at the http client level and AWS SDK level.
<T extends AmazonWebServiceRequest> T	withSdkClientExecutionTimeout(int sdkClientExecutionTimeout) Sets the amount of time (in milliseconds) to allow the client to complete the execution of an API call.
<T extends AmazonWebServiceRequest> T	withSdkRequestTimeout(int sdkRequestTimeout) Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOOP

public static final AmazonWebServiceRequest NOOP

Constructor Detail

AmazonWebServiceRequest

public AmazonWebServiceRequest()

Method Detail

setRequestCredentials

@Deprecated
public void setRequestCredentials(AWSCredentials credentials)

Deprecated. by setRequestCredentialsProvider(AWSCredentialsProvider). If you must use AWSCredentials you can wrap it with a AWSStaticCredentialsProvider.

Sets the optional credentials to use for this request, overriding the default credentials set at the client level.

Parameters:

credentials - The optional AWS security credentials to use for this request, overriding the default credentials set at the client level.

getRequestCredentials

@Deprecated
public AWSCredentials getRequestCredentials()

Deprecated. by getRequestCredentialsProvider()

Returns the optional credentials to use to sign this request, overriding the default credentials set at the client level.

Returns:

The optional credentials to use to sign this request, overriding the default credentials set at the client level.

setRequestCredentialsProvider

public void setRequestCredentialsProvider(AWSCredentialsProvider credentialsProvider)

Sets the optional credentials provider to use for this request, overriding the default credentials provider at the client level.

Parameters:

credentialsProvider - The optional AWS security credentials provider to use for this request, overriding the default credentials provider at the client level.

getRequestCredentialsProvider

public AWSCredentialsProvider getRequestCredentialsProvider()

Returns the optional credentials provider to use to sign this request, overriding the default credentials provider at the client level.

Returns:

The optional credentials provider to use to sign this request, overriding the default credentials provider at the client level.

withRequestCredentialsProvider

public <T extends AmazonWebServiceRequest> T withRequestCredentialsProvider(AWSCredentialsProvider credentialsProvider)

Sets the optional credentials provider to use for this request, overriding the default credentials provider at the client level.

Parameters:

credentialsProvider - The optional AWS security credentials provider to use for this request, overriding the default credentials provider at the client level.

Returns:

A reference to this updated object so that method calls can be chained together.

getRequestClientOptions

public RequestClientOptions getRequestClientOptions()

Gets the options stored with this request object. Intended for internal use only.

getRequestMetricCollector

public RequestMetricCollector getRequestMetricCollector()

Returns a request level metric collector; or null if not specified.

setRequestMetricCollector

public void setRequestMetricCollector(RequestMetricCollector requestMetricCollector)

Sets a request level request metric collector which takes precedence over the ones at the http client level and AWS SDK level.

withRequestMetricCollector

public <T extends AmazonWebServiceRequest> T withRequestMetricCollector(RequestMetricCollector metricCollector)

Specifies a request level metric collector which takes precedence over the ones at the http client level and AWS SDK level.

setGeneralProgressListener

public void setGeneralProgressListener(ProgressListener progressListener)

Sets the optional progress listener for receiving updates about the progress of the request.

Parameters:

progressListener - The new progress listener.

getGeneralProgressListener

public ProgressListener getGeneralProgressListener()

Returns the optional progress listener for receiving updates about the progress of the request.

Returns:

the optional progress listener for receiving updates about the progress of the request.

withGeneralProgressListener

public <T extends AmazonWebServiceRequest> T withGeneralProgressListener(ProgressListener progressListener)

Sets the optional progress listener for receiving updates about the progress of the request, and returns a reference to this object so that method calls can be chained together.

Parameters:

progressListener - The new progress listener.

Returns:

A reference to this updated object so that method calls can be chained together.

getCustomRequestHeaders

public Map<String,String> getCustomRequestHeaders()

Returns an immutable map of custom header names to header values.

Returns:

The immutable map of custom header names to header values.

putCustomRequestHeader

public String putCustomRequestHeader(String name,
                                     String value)

Put a new custom header to the map of custom header names to custom header values, and return the previous value if the header has already been set in this map.

Any custom headers that are defined are used in the HTTP request to the AWS service. These headers will be silently ignored in the event that AWS does not recognize them.

NOTE: Custom header values set via this method will overwrite any conflicting values coming from the request parameters.

Parameters:

name - The name of the header to add

value - The value of the header to add

Returns:

the previous value for the name if it was set, null otherwise

getCustomQueryParameters

public Map<String,List<String>> getCustomQueryParameters()

Returns:

the immutable map of custom query parameters. The parameter value is modeled as a list of strings because multiple values can be specified for the same parameter name.

putCustomQueryParameter

public void putCustomQueryParameter(String name,
                                    String value)

Add a custom query parameter for the request. Since multiple values are allowed for the same query parameter, this method does NOT overwrite any existing parameter values in the request.

Any custom query parameters that are defined are used in the HTTP request to the AWS service.

Parameters:

name - The name of the query parameter

value - The value of the query parameter. Only the parameter name will be added in the URI if the value is set to null. For example, putCustomQueryParameter("param", null) will be serialized to "?param", while putCustomQueryParameter("param", "") will be serialized to "?param=".

getReadLimit

public final int getReadLimit()

Description copied from interface: ReadLimitInfo

Returns the read limit for mark-and-reset during retries; or -1 if not available.

Specified by:

getReadLimit in interface ReadLimitInfo

copyBaseTo

protected final <T extends AmazonWebServiceRequest> T copyBaseTo(T target)

Copies the internal state of this base class to that of the target request.

Returns:

the target request

getCloneSource

public AmazonWebServiceRequest getCloneSource()

Returns the source object from which the current object was cloned; or null if there isn't one.

getCloneRoot

public AmazonWebServiceRequest getCloneRoot()

Returns the root object from which the current object was cloned; or null if there isn't one.

getSdkRequestTimeout

public Integer getSdkRequestTimeout()

Returns the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables this feature.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The request timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the request timeout feature should not be used when absolute precision is needed.

Note: This feature is not compatible with Java 1.6.

Returns:

The amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables the timeout for this request.

See Also:

AmazonWebServiceRequest#setSdkClientExecutionTimeout(int)} to enforce a timeout across all retries

setSdkRequestTimeout

public void setSdkRequestTimeout(int sdkRequestTimeout)

Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables this feature.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The request timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the request timeout feature should not be used when absolute precision is needed.

Note: This feature is not compatible with Java 1.6.

Parameters:

sdkRequestTimeout - The amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables the timeout for this request.

See Also:

AmazonWebServiceRequest#setSdkClientExecutionTimeout(int)} to enforce a timeout across all retries

withSdkRequestTimeout

public <T extends AmazonWebServiceRequest> T withSdkRequestTimeout(int sdkRequestTimeout)

Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables this feature. Returns the updated AmazonWebServiceRequest object so that additional method calls may be chained together.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The request timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the request timeout feature should not be used when absolute precision is needed.

Note: This feature is not compatible with Java 1.6.

Parameters:

sdkRequestTimeout - The amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A non-positive value disables the timeout for this request.

Returns:

The updated AmazonWebServiceRequest object.

See Also:

AmazonWebServiceRequest#setSdkClientExecutionTimeout(int)} to enforce a timeout across all retries

getSdkClientExecutionTimeout

public Integer getSdkClientExecutionTimeout()

Returns the amount of time (in milliseconds) to allow the client to complete the execution of an API call. This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP request including retries, unmarshalling, etc.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The client execution timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the client execution timeout feature should not be used when absolute precision is needed.

This may be used together with setSdkRequestTimeout(int) to enforce both a timeout on each individual HTTP request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'client execution' time). A non-positive value disables this feature.

Note: This feature is not compatible with Java 1.6.

Returns:

The amount of time (in milliseconds) to allow the client to complete the execution of an API call. A non-positive value disables the timeout for this request.

See Also:

AmazonWebServiceRequest#setSdkRequestTimeout(int)} to enforce a timeout per HTTP request

setSdkClientExecutionTimeout

public void setSdkClientExecutionTimeout(int sdkClientExecutionTimeout)

Sets the amount of time (in milliseconds) to allow the client to complete the execution of an API call. This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP request including retries, unmarshalling, etc.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The client execution timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the client execution timeout feature should not be used when absolute precision is needed.

This may be used together with setSdkRequestTimeout(int) to enforce both a timeout on each individual HTTP request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'client execution' time). A non-positive value disables this feature.

Note: This feature is not compatible with Java 1.6.

Parameters:

sdkClientExecutionTimeout - The amount of time (in milliseconds) to allow the client to complete the execution of an API call. A non-positive value disables the timeout for this request.

See Also:

AmazonWebServiceRequest#setSdkRequestTimeout(int)} to enforce a timeout per HTTP request

withSdkClientExecutionTimeout

public <T extends AmazonWebServiceRequest> T withSdkClientExecutionTimeout(int sdkClientExecutionTimeout)

Sets the amount of time (in milliseconds) to allow the client to complete the execution of an API call. This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP request including retries, unmarshalling, etc.

This feature requires buffering the entire response (for non-streaming APIs) into memory to enforce a hard timeout when reading the response. For APIs that return large responses this could be expensive.

The client execution timeout feature doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The typical case aborts the request within a few milliseconds but there may occasionally be requests that don't get aborted until several seconds after the timer has been breached. Because of this the client execution timeout feature should not be used when absolute precision is needed.

This may be used together with setSdkRequestTimeout(int) to enforce both a timeout on each individual HTTP request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'client execution' time). A non-positive value disables this feature.

Note: This feature is not compatible with Java 1.6.

Parameters:

sdkClientExecutionTimeout - The amount of time (in milliseconds) to allow the client to complete the execution of an API call. A non-positive value disables the timeout for this request.

Returns:

The updated AmazonWebServiceRequest object for method chaining

See Also:

AmazonWebServiceRequest#setSdkRequestTimeout(int)} to enforce a timeout per HTTP request

addHandlerContext

public <X> void addHandlerContext(HandlerContextKey<X> key,
                                  X value)

Description copied from interface: HandlerContextAware

Adds a context to that is visible to all RequestHandler2s. Note that, context added here will available only for the scope of the request execution and will not be marshalled over the wire.

Specified by:

addHandlerContext in interface HandlerContextAware

Parameters:

key - the key for the property being set in the request.

value - the value for the property being set in the request.

getHandlerContext

public <X> X getHandlerContext(HandlerContextKey<X> key)

Description copied from interface: HandlerContextAware

Return the context for the given key if present; else return null.

Specified by:

getHandlerContext in interface HandlerContextAware

Parameters:

key - the key for the context

Returns:

the context if present else null.

clone

public AmazonWebServiceRequest clone()

Creates a shallow clone of this object for all fields except the handler context. Explicitly does not clone the deep structure of the other fields in the message.

Overrides:

clone in class Object

See Also:

Object.clone()