Class HttpRequest
- java.lang.Object
-
- com.google.api.client.http.HttpRequest
-
public final class HttpRequest extends Object
HTTP request.Implementation is not thread-safe.
- Since:
- 1.0
- Author:
- Yaniv Inbar
-
-
Field Summary
Fields Modifier and Type Field 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.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description HttpResponse
execute()
Execute the HTTP request and returns the HTTP response.Future<HttpResponse>
executeAsync()
Beta
Executes this request asynchronously usingexecuteAsync(Executor)
in a single separate thread usingExecutors.newSingleThreadExecutor()
.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).int
getConnectTimeout()
Returns the timeout in milliseconds to establish a connection or0
for an infinite timeout.HttpContent
getContent()
Returns the HTTP request content ornull
for none.int
getContentLoggingLimit()
Returns the limit to the content size that will be logged duringexecute()
.HttpEncoding
getEncoding()
Returns the HTTP content encoding ornull
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 ofexecute()
(before executing the HTTP request) ornull
for none.HttpIOExceptionHandler
getIOExceptionHandler()
int
getNumberOfRetries()
Returns the number of retries that will be allowed to execute before the request will be terminated or0
to not retry requests.ObjectParser
getParser()
Returns theObjectParser
used to parse the response ornull
for none.int
getReadTimeout()
Returns the timeout in milliseconds to read data from an established connection or0
for an infinite timeout.String
getRequestMethod()
Returns the HTTP request method ornull
for none.HttpHeaders
getResponseHeaders()
Returns the HTTP response headers.HttpResponseInterceptor
getResponseInterceptor()
Returns the HTTP response interceptor ornull
for none.boolean
getRetryOnExecuteIOException()
Deprecated.(scheduled to be removed in 1.18) UsesetIOExceptionHandler(HttpIOExceptionHandler)
instead.Sleeper
getSleeper()
Returns the sleeper.boolean
getSuppressUserAgentSuffix()
Returns whether to not add the suffixUSER_AGENT_SUFFIX
to the User-Agent header.boolean
getThrowExceptionOnExecuteError()
Returns whether to throw an exception at the end ofexecute()
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 ornull
for none.GenericUrl
getUrl()
Returns the HTTP request URL.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).HttpRequest
setConnectTimeout(int connectTimeout)
Sets the timeout in milliseconds to establish a connection or0
for an infinite timeout.HttpRequest
setContent(HttpContent content)
Sets the HTTP request content ornull
for none.HttpRequest
setContentLoggingLimit(int contentLoggingLimit)
Set the limit to the content size that will be logged duringexecute()
.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 ornull
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 ofexecute()
(before executing the HTTP request) ornull
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 or0
to not retry requests.HttpRequest
setParser(ObjectParser parser)
Sets theObjectParser
used to parse the response to this request ornull
for none.HttpRequest
setReadTimeout(int readTimeout)
Sets the timeout in milliseconds to read data from an established connection or0
for an infinite timeout.HttpRequest
setRequestMethod(String requestMethod)
Sets the HTTP request method ornull
for none.HttpRequest
setResponseHeaders(HttpHeaders responseHeaders)
Sets the HTTP response headers.HttpRequest
setResponseInterceptor(HttpResponseInterceptor responseInterceptor)
Sets the HTTP response interceptor ornull
for none.HttpRequest
setRetryOnExecuteIOException(boolean retryOnExecuteIOException)
Deprecated.(scheduled to be removed in 1.18) UsesetIOExceptionHandler(HttpIOExceptionHandler)
instead.HttpRequest
setSleeper(Sleeper sleeper)
Sets the sleeper.HttpRequest
setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)
Sets whether to not add the suffixUSER_AGENT_SUFFIX
to the User-Agent header.HttpRequest
setThrowExceptionOnExecuteError(boolean throwExceptionOnExecuteError)
Sets whether to throw an exception at the end ofexecute()
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 ornull
for none.HttpRequest
setUrl(GenericUrl url)
Sets the HTTP request URL.
-
-
-
Field Detail
-
VERSION
public static final String VERSION
Current version of the Google API Client Library for Java.- Since:
- 1.8
- See Also:
- Constant Field Values
-
USER_AGENT_SUFFIX
public static final String USER_AGENT_SUFFIX
User agent suffix for all requests.Includes a
"(gzip)"
suffix in case the server -- as Google's servers may do -- checks theUser-Agent
header to try to detect if the client accepts gzip-encoded responses.- Since:
- 1.4
- See Also:
- Constant Field Values
-
DEFAULT_NUMBER_OF_RETRIES
public static final int DEFAULT_NUMBER_OF_RETRIES
The default number of retries that will be allowed to execute before the request will be terminated.- Since:
- 1.22
- See Also:
getNumberOfRetries()
, Constant Field Values
-
-
Method Detail
-
getTransport
public HttpTransport getTransport()
Returns the HTTP transport.- Since:
- 1.5
-
getRequestMethod
public String getRequestMethod()
Returns the HTTP request method ornull
for none.- Since:
- 1.12
-
setRequestMethod
public HttpRequest setRequestMethod(String requestMethod)
Sets the HTTP request method ornull
for none.- Since:
- 1.12
-
getUrl
public GenericUrl getUrl()
Returns the HTTP request URL.- Since:
- 1.5
-
setUrl
public HttpRequest setUrl(GenericUrl url)
Sets the HTTP request URL.- Since:
- 1.5
-
getContent
public HttpContent getContent()
Returns the HTTP request content ornull
for none.- Since:
- 1.5
-
setContent
public HttpRequest setContent(HttpContent content)
Sets the HTTP request content ornull
for none.- Since:
- 1.5
-
getEncoding
public HttpEncoding getEncoding()
Returns the HTTP content encoding ornull
for none.- Since:
- 1.14
-
setEncoding
public HttpRequest setEncoding(HttpEncoding encoding)
Sets the HTTP content encoding ornull
for none.- Since:
- 1.14
-
getBackOffPolicy
@Deprecated @Beta public BackOffPolicy getBackOffPolicy()
Deprecated.(scheduled to be removed in 1.18).setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler)
with a newHttpBackOffUnsuccessfulResponseHandler
instead.- Since:
- 1.7
-
setBackOffPolicy
@Deprecated @Beta public HttpRequest setBackOffPolicy(BackOffPolicy backOffPolicy)
Deprecated.(scheduled to be removed in 1.18). UsesetUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler)
with a newHttpBackOffUnsuccessfulResponseHandler
instead.- Since:
- 1.7
-
getContentLoggingLimit
public int getContentLoggingLimit()
Returns the limit to the content size that will be logged duringexecute()
.If the content size is greater than this limit then it will not be logged.
Content will only be logged if
isLoggingEnabled()
istrue
.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.
- Since:
- 1.7
-
setContentLoggingLimit
public HttpRequest setContentLoggingLimit(int contentLoggingLimit)
Set the limit to the content size that will be logged duringexecute()
.If the content size is greater than this limit then it will not be logged.
Content will only be logged if
isLoggingEnabled()
istrue
.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.
- Since:
- 1.7
-
isLoggingEnabled
public boolean isLoggingEnabled()
Returns whether logging should be enabled for this request.Defaults to
true
.- Since:
- 1.9
-
setLoggingEnabled
public HttpRequest setLoggingEnabled(boolean loggingEnabled)
Sets whether logging should be enabled for this request.Defaults to
true
.- Since:
- 1.9
-
isCurlLoggingEnabled
public boolean isCurlLoggingEnabled()
Returns whether logging in form of curl commands is enabled for this request.- Since:
- 1.11
-
setCurlLoggingEnabled
public HttpRequest setCurlLoggingEnabled(boolean curlLoggingEnabled)
Sets whether logging in form of curl commands should be enabled for this request.Defaults to
true
.- Since:
- 1.11
-
getConnectTimeout
public int getConnectTimeout()
Returns the timeout in milliseconds to establish a connection or0
for an infinite timeout.- Since:
- 1.5
-
setConnectTimeout
public HttpRequest setConnectTimeout(int connectTimeout)
Sets the timeout in milliseconds to establish a connection or0
for an infinite timeout.By default it is 20000 (20 seconds).
- Since:
- 1.5
-
getReadTimeout
public int getReadTimeout()
Returns the timeout in milliseconds to read data from an established connection or0
for an infinite timeout.By default it is 20000 (20 seconds).
- Since:
- 1.5
-
setReadTimeout
public HttpRequest setReadTimeout(int readTimeout)
Sets the timeout in milliseconds to read data from an established connection or0
for an infinite timeout.- Since:
- 1.5
-
getHeaders
public HttpHeaders getHeaders()
Returns the HTTP request headers.- Since:
- 1.5
-
setHeaders
public HttpRequest setHeaders(HttpHeaders headers)
Sets the HTTP request headers.By default, this is a new unmodified instance of
HttpHeaders
.- Since:
- 1.5
-
getResponseHeaders
public HttpHeaders getResponseHeaders()
Returns the HTTP response headers.- Since:
- 1.5
-
setResponseHeaders
public HttpRequest setResponseHeaders(HttpHeaders responseHeaders)
Sets the HTTP response headers.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; }
- Since:
- 1.5
-
getInterceptor
public HttpExecuteInterceptor getInterceptor()
Returns the HTTP request execute interceptor to intercept the start ofexecute()
(before executing the HTTP request) ornull
for none.- Since:
- 1.5
-
setInterceptor
public HttpRequest setInterceptor(HttpExecuteInterceptor interceptor)
Sets the HTTP request execute interceptor to intercept the start ofexecute()
(before executing the HTTP request) ornull
for none.- Since:
- 1.5
-
getUnsuccessfulResponseHandler
public HttpUnsuccessfulResponseHandler getUnsuccessfulResponseHandler()
Returns the HTTP unsuccessful (non-2XX) response handler ornull
for none.- Since:
- 1.5
-
setUnsuccessfulResponseHandler
public HttpRequest setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)
Sets the HTTP unsuccessful (non-2XX) response handler ornull
for none.- Since:
- 1.5
-
getIOExceptionHandler
@Beta public HttpIOExceptionHandler getIOExceptionHandler()
- Since:
- 1.15
-
setIOExceptionHandler
@Beta public HttpRequest setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)
- Since:
- 1.15
-
getResponseInterceptor
public HttpResponseInterceptor getResponseInterceptor()
Returns the HTTP response interceptor ornull
for none.- Since:
- 1.13
-
setResponseInterceptor
public HttpRequest setResponseInterceptor(HttpResponseInterceptor responseInterceptor)
Sets the HTTP response interceptor ornull
for none.- Since:
- 1.13
-
getNumberOfRetries
public int getNumberOfRetries()
Returns the number of retries that will be allowed to execute before the request will be terminated or0
to not retry requests. Retries occur as a result of eitherHttpUnsuccessfulResponseHandler
orHttpIOExceptionHandler
which handles abnormal HTTP response or the I/O exception.- Since:
- 1.5
-
setNumberOfRetries
public HttpRequest setNumberOfRetries(int numRetries)
Sets the number of retries that will be allowed to execute before the request will be terminated or0
to not retry requests. Retries occur as a result of eitherHttpUnsuccessfulResponseHandler
orHttpIOExceptionHandler
which handles abnormal HTTP response or the I/O exception.The default value is
DEFAULT_NUMBER_OF_RETRIES
.- Since:
- 1.5
-
setParser
public HttpRequest setParser(ObjectParser parser)
Sets theObjectParser
used to parse the response to this request ornull
for none.This parser will be preferred over any registered HttpParser.
- Since:
- 1.10
-
getParser
public final ObjectParser getParser()
Returns theObjectParser
used to parse the response ornull
for none.- Since:
- 1.10
-
getFollowRedirects
public boolean getFollowRedirects()
Returns whether to follow redirects automatically.- Since:
- 1.6
-
setFollowRedirects
public HttpRequest setFollowRedirects(boolean followRedirects)
Sets whether to follow redirects automatically.The default value is
true
.- Since:
- 1.6
-
getThrowExceptionOnExecuteError
public boolean getThrowExceptionOnExecuteError()
Returns whether to throw an exception at the end ofexecute()
on an HTTP error code (non-2XX) after all retries and response handlers have been exhausted.- Since:
- 1.7
-
setThrowExceptionOnExecuteError
public HttpRequest setThrowExceptionOnExecuteError(boolean throwExceptionOnExecuteError)
Sets whether to throw an exception at the end ofexecute()
on a HTTP error code (non-2XX) after all retries and response handlers have been exhausted.The default value is
true
.- Since:
- 1.7
-
getRetryOnExecuteIOException
@Deprecated @Beta public boolean getRetryOnExecuteIOException()
Deprecated.(scheduled to be removed in 1.18) UsesetIOExceptionHandler(HttpIOExceptionHandler)
instead.Beta
Returns whether to retry the request if anIOException
is encountered inLowLevelHttpRequest.execute()
.- Since:
- 1.9
-
setRetryOnExecuteIOException
@Deprecated @Beta public HttpRequest setRetryOnExecuteIOException(boolean retryOnExecuteIOException)
Deprecated.(scheduled to be removed in 1.18) UsesetIOExceptionHandler(HttpIOExceptionHandler)
instead.Beta
Sets whether to retry the request if anIOException
is encountered inLowLevelHttpRequest.execute()
.The default value is
false
.- Since:
- 1.9
-
getSuppressUserAgentSuffix
public boolean getSuppressUserAgentSuffix()
Returns whether to not add the suffixUSER_AGENT_SUFFIX
to the User-Agent header.- Since:
- 1.11
-
setSuppressUserAgentSuffix
public HttpRequest setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)
Sets whether to not add the suffixUSER_AGENT_SUFFIX
to the User-Agent header.The default value is
false
.- Since:
- 1.11
-
execute
public HttpResponse execute() throws IOException
Execute the HTTP request and returns the HTTP response.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 theAuthorization
header which is only logged ifLevel.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(); }
- Returns:
- HTTP response for an HTTP success response (or HTTP error response if
getThrowExceptionOnExecuteError()
isfalse
) - Throws:
HttpResponseException
- for an HTTP error response (only ifgetThrowExceptionOnExecuteError()
istrue
)IOException
- See Also:
HttpResponse.isSuccessStatusCode()
-
executeAsync
@Beta public Future<HttpResponse> executeAsync(Executor executor)
Beta
Executes this request asynchronously in a single separate thread using the supplied executor.- Parameters:
executor
- executor to run the asynchronous request- Returns:
- future for accessing the HTTP response
- Since:
- 1.13
-
executeAsync
@Beta public Future<HttpResponse> executeAsync()
Beta
Executes this request asynchronously usingexecuteAsync(Executor)
in a single separate thread usingExecutors.newSingleThreadExecutor()
.- Returns:
- A future for accessing the results of the asynchronous request.
- Since:
- 1.13
-
handleRedirect
public 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.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.- Returns:
- whether the redirect was successful
- Since:
- 1.11
-
getSleeper
public Sleeper getSleeper()
Returns the sleeper.- Since:
- 1.15
-
setSleeper
public HttpRequest setSleeper(Sleeper sleeper)
Sets the sleeper. The default value isSleeper.DEFAULT
.- Since:
- 1.15
-
-