public final class HttpRequest extends Object
Implementation is not thread-safe.
Modifier and Type | Field and Description |
---|---|
static int |
DEFAULT_NUMBER_OF_RETRIES
The default number of retries that will be allowed to execute before the request will be
terminated.
|
static String |
USER_AGENT_SUFFIX
User agent suffix for all requests.
|
static String |
VERSION
Current version of the Google API Client Library for Java.
|
Modifier and Type | Method and Description |
---|---|
HttpResponse |
execute()
Execute the HTTP request and returns the HTTP response.
|
Future<HttpResponse> |
executeAsync()
Beta Executes this request asynchronously using executeAsync(Executor) in a single separate
thread using Executors#newFixedThreadPool(1) . |
Future<HttpResponse> |
executeAsync(Executor executor)
Beta Executes this request asynchronously in a single separate thread using the supplied executor. |
BackOffPolicy |
getBackOffPolicy()
Deprecated.
(scheduled to be removed in 1.18).
setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler) with a new HttpBackOffUnsuccessfulResponseHandler instead. |
int |
getConnectTimeout()
Returns the timeout in milliseconds to establish a connection or
0 for an infinite
timeout. |
HttpContent |
getContent()
Returns the HTTP request content or
null for none. |
int |
getContentLoggingLimit()
Returns the limit to the content size that will be logged during
execute() . |
HttpEncoding |
getEncoding()
Returns the HTTP content encoding or
null for none. |
boolean |
getFollowRedirects()
Returns whether to follow redirects automatically.
|
HttpHeaders |
getHeaders()
Returns the HTTP request headers.
|
HttpExecuteInterceptor |
getInterceptor()
Returns the HTTP request execute interceptor to intercept the start of
execute()
(before executing the HTTP request) or null for none. |
HttpIOExceptionHandler |
getIOExceptionHandler()
|
int |
getNumberOfRetries()
Returns the number of retries that will be allowed to execute before the request will be
terminated or
0 to not retry requests. |
ObjectParser |
getParser()
Returns the
ObjectParser used to parse the response or null for none. |
int |
getReadTimeout()
Returns the timeout in milliseconds to read data from an established connection or
0
for an infinite timeout. |
String |
getRequestMethod()
Returns the HTTP request method or
null for none. |
HttpHeaders |
getResponseHeaders()
Returns the HTTP response headers.
|
HttpResponseInterceptor |
getResponseInterceptor()
Returns the HTTP response interceptor or
null for none. |
boolean |
getResponseReturnRawInputStream()
Returns whether
HttpResponse.getContent() should return raw input stream for this
request. |
boolean |
getRetryOnExecuteIOException()
Deprecated.
(scheduled to be removed in 1.18) Use
setIOExceptionHandler(HttpIOExceptionHandler) instead. |
Sleeper |
getSleeper()
Returns the sleeper.
|
boolean |
getSuppressUserAgentSuffix()
Returns whether to not add the suffix
USER_AGENT_SUFFIX to the User-Agent header. |
boolean |
getThrowExceptionOnExecuteError()
Returns whether to throw an exception at the end of
execute() on an HTTP error code
(non-2XX) after all retries and response handlers have been exhausted. |
HttpTransport |
getTransport()
Returns the HTTP transport.
|
HttpUnsuccessfulResponseHandler |
getUnsuccessfulResponseHandler()
Returns the HTTP unsuccessful (non-2XX) response handler or
null for none. |
GenericUrl |
getUrl()
Returns the HTTP request URL.
|
int |
getWriteTimeout()
Returns the timeout in milliseconds to send POST/PUT data or
0 for an infinite timeout. |
boolean |
handleRedirect(int statusCode,
HttpHeaders responseHeaders)
Sets up this request object to handle the necessary redirect if redirects are turned on, it is
a redirect status code and the header has a location.
|
boolean |
isCurlLoggingEnabled()
Returns whether logging in form of curl commands is enabled for this request.
|
boolean |
isLoggingEnabled()
Returns whether logging should be enabled for this request.
|
HttpRequest |
setBackOffPolicy(BackOffPolicy backOffPolicy)
Deprecated.
(scheduled to be removed in 1.18). Use
setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler) with a new HttpBackOffUnsuccessfulResponseHandler instead. |
HttpRequest |
setConnectTimeout(int connectTimeout)
Sets the timeout in milliseconds to establish a connection or
0 for an infinite
timeout. |
HttpRequest |
setContent(HttpContent content)
Sets the HTTP request content or
null for none. |
HttpRequest |
setContentLoggingLimit(int contentLoggingLimit)
Set the limit to the content size that will be logged during
execute() . |
HttpRequest |
setCurlLoggingEnabled(boolean curlLoggingEnabled)
Sets whether logging in form of curl commands should be enabled for this request.
|
HttpRequest |
setEncoding(HttpEncoding encoding)
Sets the HTTP content encoding or
null for none. |
HttpRequest |
setFollowRedirects(boolean followRedirects)
Sets whether to follow redirects automatically.
|
HttpRequest |
setHeaders(HttpHeaders headers)
Sets the HTTP request headers.
|
HttpRequest |
setInterceptor(HttpExecuteInterceptor interceptor)
Sets the HTTP request execute interceptor to intercept the start of
execute() (before
executing the HTTP request) or null for none. |
HttpRequest |
setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)
|
HttpRequest |
setLoggingEnabled(boolean loggingEnabled)
Sets whether logging should be enabled for this request.
|
HttpRequest |
setNumberOfRetries(int numRetries)
Sets the number of retries that will be allowed to execute before the request will be
terminated or
0 to not retry requests. |
HttpRequest |
setParser(ObjectParser parser)
Sets the
ObjectParser used to parse the response to this request or null for
none. |
HttpRequest |
setReadTimeout(int readTimeout)
Sets the timeout in milliseconds to read data from an established connection or
0 for
an infinite timeout. |
HttpRequest |
setRequestMethod(String requestMethod)
Sets the HTTP request method or
null for none. |
HttpRequest |
setResponseHeaders(HttpHeaders responseHeaders)
Sets the HTTP response headers.
|
HttpRequest |
setResponseInterceptor(HttpResponseInterceptor responseInterceptor)
Sets the HTTP response interceptor or
null for none. |
HttpRequest |
setResponseReturnRawInputStream(boolean responseReturnRawInputStream)
Sets whether
HttpResponse.getContent() should return raw input stream for this request. |
HttpRequest |
setRetryOnExecuteIOException(boolean retryOnExecuteIOException)
Deprecated.
(scheduled to be removed in 1.18) Use
setIOExceptionHandler(HttpIOExceptionHandler) instead. |
HttpRequest |
setSleeper(Sleeper sleeper)
Sets the sleeper.
|
HttpRequest |
setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)
Sets whether to not add the suffix
USER_AGENT_SUFFIX to the User-Agent header. |
HttpRequest |
setThrowExceptionOnExecuteError(boolean throwExceptionOnExecuteError)
Sets whether to throw an exception at the end of
execute() on a HTTP error code
(non-2XX) after all retries and response handlers have been exhausted. |
HttpRequest |
setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)
Sets the HTTP unsuccessful (non-2XX) response handler or
null for none. |
HttpRequest |
setUrl(GenericUrl url)
Sets the HTTP request URL.
|
HttpRequest |
setWriteTimeout(int writeTimeout)
Sets the timeout in milliseconds to send POST/PUT data or
0 for an infinite timeout. |
public static final String VERSION
public static final String USER_AGENT_SUFFIX
Includes a "(gzip)"
suffix in case the server -- as Google's servers may do --
checks the User-Agent
header to try to detect if the client accepts gzip-encoded
responses.
public static final int DEFAULT_NUMBER_OF_RETRIES
getNumberOfRetries()
,
Constant Field Valuespublic HttpTransport getTransport()
public String getRequestMethod()
null
for none.public HttpRequest setRequestMethod(String requestMethod)
null
for none.public GenericUrl getUrl()
public HttpRequest setUrl(GenericUrl url)
public HttpContent getContent()
null
for none.public HttpRequest setContent(HttpContent content)
null
for none.public HttpEncoding getEncoding()
null
for none.public HttpRequest setEncoding(HttpEncoding encoding)
null
for none.@Deprecated @Beta public BackOffPolicy getBackOffPolicy()
setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler)
with a new HttpBackOffUnsuccessfulResponseHandler
instead.@Deprecated @Beta public HttpRequest setBackOffPolicy(BackOffPolicy backOffPolicy)
setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler)
with a new HttpBackOffUnsuccessfulResponseHandler
instead.public int getContentLoggingLimit()
execute()
.
If the content size is greater than this limit then it will not be logged.
Content will only be logged if isLoggingEnabled()
is true
.
Can be set to 0
to disable content logging. This is useful for example if content
has sensitive data such as authentication information.
Defaults to 16KB.
public HttpRequest setContentLoggingLimit(int contentLoggingLimit)
execute()
.
If the content size is greater than this limit then it will not be logged.
Content will only be logged if isLoggingEnabled()
is true
.
Can be set to 0
to disable content logging. This is useful for example if content
has sensitive data such as authentication information.
Defaults to 16KB.
public boolean isLoggingEnabled()
Defaults to true
.
public HttpRequest setLoggingEnabled(boolean loggingEnabled)
Defaults to true
.
public boolean isCurlLoggingEnabled()
public HttpRequest setCurlLoggingEnabled(boolean curlLoggingEnabled)
Defaults to true
.
public int getConnectTimeout()
0
for an infinite
timeout.public HttpRequest setConnectTimeout(int connectTimeout)
0
for an infinite
timeout.
By default it is 20000 (20 seconds).
public int getReadTimeout()
0
for an infinite timeout.
By default it is 20000 (20 seconds).
public HttpRequest setReadTimeout(int readTimeout)
0
for
an infinite timeout.public int getWriteTimeout()
0
for an infinite timeout.
By default it is 0 (infinite).
public HttpRequest setWriteTimeout(int writeTimeout)
0
for an infinite timeout.public HttpHeaders getHeaders()
public HttpRequest setHeaders(HttpHeaders headers)
By default, this is a new unmodified instance of HttpHeaders
.
public HttpHeaders getResponseHeaders()
public HttpRequest setResponseHeaders(HttpHeaders responseHeaders)
By default, this is a new unmodified instance of HttpHeaders
.
For example, this can be used if you want to use a subclass of HttpHeaders
called
MyHeaders to process the response:
static String executeAndGetValueOfSomeCustomHeader(HttpRequest request) { MyHeaders responseHeaders = new MyHeaders(); request.responseHeaders = responseHeaders; HttpResponse response = request.execute(); return responseHeaders.someCustomHeader; }
public HttpExecuteInterceptor getInterceptor()
execute()
(before executing the HTTP request) or null
for none.public HttpRequest setInterceptor(HttpExecuteInterceptor interceptor)
execute()
(before
executing the HTTP request) or null
for none.public HttpUnsuccessfulResponseHandler getUnsuccessfulResponseHandler()
null
for none.public HttpRequest setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)
null
for none.@Beta public HttpIOExceptionHandler getIOExceptionHandler()
@Beta public HttpRequest setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)
public HttpResponseInterceptor getResponseInterceptor()
null
for none.public HttpRequest setResponseInterceptor(HttpResponseInterceptor responseInterceptor)
null
for none.public int getNumberOfRetries()
0
to not retry requests. Retries occur as a result of either HttpUnsuccessfulResponseHandler
or HttpIOExceptionHandler
which handles abnormal HTTP
response or the I/O exception.public HttpRequest setNumberOfRetries(int numRetries)
0
to not retry requests. Retries occur as a result of either HttpUnsuccessfulResponseHandler
or HttpIOExceptionHandler
which handles abnormal HTTP
response or the I/O exception.
The default value is DEFAULT_NUMBER_OF_RETRIES
.
public HttpRequest setParser(ObjectParser parser)
ObjectParser
used to parse the response to this request or null
for
none.
This parser will be preferred over any registered HttpParser.
public final ObjectParser getParser()
ObjectParser
used to parse the response or null
for none.public boolean getFollowRedirects()
public HttpRequest setFollowRedirects(boolean followRedirects)
The default value is true
.
public boolean getThrowExceptionOnExecuteError()
execute()
on an HTTP error code
(non-2XX) after all retries and response handlers have been exhausted.public HttpRequest setThrowExceptionOnExecuteError(boolean throwExceptionOnExecuteError)
execute()
on a HTTP error code
(non-2XX) after all retries and response handlers have been exhausted.
The default value is true
.
@Deprecated @Beta public boolean getRetryOnExecuteIOException()
setIOExceptionHandler(HttpIOExceptionHandler)
instead.Beta
IOException
is encountered in LowLevelHttpRequest.execute()
.@Deprecated @Beta public HttpRequest setRetryOnExecuteIOException(boolean retryOnExecuteIOException)
setIOExceptionHandler(HttpIOExceptionHandler)
instead.Beta
IOException
is encountered in LowLevelHttpRequest.execute()
.
The default value is false
.
public boolean getSuppressUserAgentSuffix()
USER_AGENT_SUFFIX
to the User-Agent header.public HttpRequest setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)
USER_AGENT_SUFFIX
to the User-Agent header.
The default value is false
.
public boolean getResponseReturnRawInputStream()
HttpResponse.getContent()
should return raw input stream for this
request.public HttpRequest setResponseReturnRawInputStream(boolean responseReturnRawInputStream)
HttpResponse.getContent()
should return raw input stream for this request.
The default value is false
.
public HttpResponse execute() throws IOException
Note that regardless of the returned status code, the HTTP response content has not been parsed yet, and must be parsed by the calling code.
Note that when calling to this method twice or more, the state of this HTTP request object
isn't cleared, so the request will continue where it was left. For example, the state of the
HttpUnsuccessfulResponseHandler
attached to this HTTP request will remain the same as
it was left after last execute.
Almost all details of the request and response are logged if Level.CONFIG
is
loggable. The only exception is the value of the Authorization
header which is only
logged if Level.ALL
is loggable.
Callers should call HttpResponse.disconnect()
when the returned HTTP response object
is no longer needed. However, HttpResponse.disconnect()
does not have to be called if the
response stream is properly closed. Example usage:
HttpResponse response = request.execute(); try { // process the HTTP response object } finally { response.disconnect(); }
getThrowExceptionOnExecuteError()
is false
)HttpResponseException
- for an HTTP error response (only if getThrowExceptionOnExecuteError()
is true
)IOException
HttpResponse.isSuccessStatusCode()
@Beta public Future<HttpResponse> executeAsync(Executor executor)
Beta
executor
- executor to run the asynchronous request@Beta public Future<HttpResponse> executeAsync()
Beta
executeAsync(Executor)
in a single separate
thread using Executors#newFixedThreadPool(1)
.public boolean handleRedirect(int statusCode, HttpHeaders responseHeaders)
When the status code is 303
the method on the request is changed to a GET as per the
RFC2616 specification. On a redirect, it also removes the "Authorization"
and all
"If-*"
request headers.
Upgrade warning: When handling a status code of 303, handleRedirect(int,
HttpHeaders)
now correctly removes any content from the body of the new request, as GET
requests should not have content. It did not do this in prior version 1.16.
public Sleeper getSleeper()
public HttpRequest setSleeper(Sleeper sleeper)
Sleeper.DEFAULT
.Copyright © 2011–2019 Google. All rights reserved.