Class HttpRequest (1.45.0)

public final class HttpRequest

HTTP request.

Implementation is not thread-safe.

Inheritance

java.lang.Object > HttpRequest

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

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. See Also: #getNumberOfRetries

Field Value
Type	Description
`int`

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 the User-Agent header to try to detect if the client accepts gzip-encoded responses.

Field Value
Type	Description
`String`

VERSION

public static final String VERSION

Current version of the Google API Client Library for Java.

Field Value
Type	Description
`String`

Methods

execute()

public HttpResponse execute()

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 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(); }

Returns
Type	Description
`HttpResponse`	HTTP response for an HTTP success response (or HTTP error response if #getThrowExceptionOnExecuteError() is `false`)

Exceptions
Type	Description
`IOException`	for an HTTP error response (only if #getThrowExceptionOnExecuteError() is `true`)

executeAsync()

public Future<HttpResponse> executeAsync()

Beta
Executes this request asynchronously using #executeAsync(Executor) in a single separate thread using Executors#newFixedThreadPool(int).

Returns
Type	Description
`Future<HttpResponse>`	A future for accessing the results of the asynchronous request.

executeAsync(Executor executor)

public Future<HttpResponse> executeAsync(Executor executor)

Beta
Executes this request asynchronously in a single separate thread using the supplied executor.

Parameter
Name	Description
`executor`	`Executor` executor to run the asynchronous request

Returns
Type	Description
`Future<HttpResponse>`	future for accessing the HTTP response

getBackOffPolicy() (deprecated)

public BackOffPolicy getBackOffPolicy()

Deprecated. (scheduled to be removed in 1.18). #setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler) with a new HttpBackOffUnsuccessfulResponseHandler instead.

Beta
Returns the BackOffPolicy to use between retry attempts or null for none.

Returns
Type	Description
`BackOffPolicy`

getConnectTimeout()

public int getConnectTimeout()

Returns the timeout in milliseconds to establish a connection or 0 for an infinite timeout.

Returns
Type	Description
`int`

getContent()

public HttpContent getContent()

Returns the HTTP request content or null for none.

Returns
Type	Description
`HttpContent`

getContentLoggingLimit()

public int getContentLoggingLimit()

Returns the limit to the content size that will be logged during #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.

Returns
Type	Description
`int`

getEncoding()

public HttpEncoding getEncoding()

Returns the HTTP content encoding or null for none.

Returns
Type	Description
`HttpEncoding`

getFollowRedirects()

public boolean getFollowRedirects()

Returns whether to follow redirects automatically.

Returns
Type	Description
`boolean`

getHeaders()

public HttpHeaders getHeaders()

Returns the HTTP request headers.

Returns
Type	Description
`HttpHeaders`

getIOExceptionHandler()

public HttpIOExceptionHandler getIOExceptionHandler()

Beta
Returns the HTTP I/O exception handler or null for none.

Returns
Type	Description
`HttpIOExceptionHandler`

getInterceptor()

public HttpExecuteInterceptor getInterceptor()

Returns the HTTP request execute interceptor to intercept the start of #execute() (before executing the HTTP request) or null for none.

Returns
Type	Description
`HttpExecuteInterceptor`

getNumberOfRetries()

public 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. Retries occur as a result of either HttpUnsuccessfulResponseHandler or HttpIOExceptionHandler which handles abnormal HTTP response or the I/O exception.

Returns
Type	Description
`int`

getParser()

public final ObjectParser getParser()

Returns the ObjectParser used to parse the response or null for none.

Returns
Type	Description
`ObjectParser`

getReadTimeout()

public int getReadTimeout()

Returns the timeout in milliseconds to read data from an established connection or 0 for an infinite timeout.

By default it is 20000 (20 seconds).

Returns
Type	Description
`int`

getRequestMethod()

public String getRequestMethod()

Returns the HTTP request method or null for none.

Returns
Type	Description
`String`

getResponseHeaders()

public HttpHeaders getResponseHeaders()

Returns the HTTP response headers.

Returns
Type	Description
`HttpHeaders`

getResponseInterceptor()

public HttpResponseInterceptor getResponseInterceptor()

Returns the HTTP response interceptor or null for none.

Returns
Type	Description
`HttpResponseInterceptor`

getResponseReturnRawInputStream()

public boolean getResponseReturnRawInputStream()

Returns whether HttpResponse#getContent() should return raw input stream for this request.

Returns
Type	Description
`boolean`

getRetryOnExecuteIOException() (deprecated)

public boolean getRetryOnExecuteIOException()

Deprecated. (scheduled to be removed in 1.18) Use #setIOExceptionHandler(HttpIOExceptionHandler) instead.

Beta
Returns whether to retry the request if an IOException is encountered in LowLevelHttpRequest#execute().

Returns
Type	Description
`boolean`

getSleeper()

public Sleeper getSleeper()

Returns the sleeper.

Returns
Type	Description
`Sleeper`

getSuppressUserAgentSuffix()

public boolean getSuppressUserAgentSuffix()

Returns whether to not add the suffix #USER_AGENT_SUFFIX to the User-Agent header.

Returns
Type	Description
`boolean`

getThrowExceptionOnExecuteError()

public 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.

Returns
Type	Description
`boolean`

getTransport()

public HttpTransport getTransport()

Returns the HTTP transport.

Returns
Type	Description
`HttpTransport`

getUnsuccessfulResponseHandler()

public HttpUnsuccessfulResponseHandler getUnsuccessfulResponseHandler()

Returns the HTTP unsuccessful (non-2XX) response handler or null for none.

Returns
Type	Description
`HttpUnsuccessfulResponseHandler`

getUrl()

public GenericUrl getUrl()

Returns the HTTP request URL.

Returns
Type	Description
`GenericUrl`

getUseRawRedirectUrls()

public boolean getUseRawRedirectUrls()

Return whether to use raw redirect URLs.

Returns
Type	Description
`boolean`

getWriteTimeout()

public int getWriteTimeout()

Returns the timeout in milliseconds to send POST/PUT data or 0 for an infinite timeout.

By default it is 0 (infinite).

Returns
Type	Description
`int`

handleRedirect(int statusCode, HttpHeaders responseHeaders)

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.

Parameters
Name	Description
`statusCode`	`int`
`responseHeaders`	`HttpHeaders`

Returns
Type	Description
`boolean`	whether the redirect was successful

isCurlLoggingEnabled()

public boolean isCurlLoggingEnabled()

Returns whether logging in form of curl commands is enabled for this request.

Returns
Type	Description
`boolean`

isLoggingEnabled()

public boolean isLoggingEnabled()

Returns whether logging should be enabled for this request.

Defaults to true.

Returns
Type	Description
`boolean`

setBackOffPolicy(BackOffPolicy backOffPolicy) (deprecated)

public HttpRequest setBackOffPolicy(BackOffPolicy backOffPolicy)

Deprecated. (scheduled to be removed in 1.18). Use #setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler) with a new HttpBackOffUnsuccessfulResponseHandler instead.

Beta
Sets the BackOffPolicy to use between retry attempts or null for none.

Parameter
Name	Description
`backOffPolicy`	`BackOffPolicy`

Returns
Type	Description
`HttpRequest`

setConnectTimeout(int connectTimeout)

public HttpRequest setConnectTimeout(int connectTimeout)

Sets the timeout in milliseconds to establish a connection or 0 for an infinite timeout.

By default it is 20000 (20 seconds).

Parameter
Name	Description
`connectTimeout`	`int`

Returns
Type	Description
`HttpRequest`

setContent(HttpContent content)

public HttpRequest setContent(HttpContent content)

Sets the HTTP request content or null for none.

Parameter
Name	Description
`content`	`HttpContent`

Returns
Type	Description
`HttpRequest`

setContentLoggingLimit(int contentLoggingLimit)

public HttpRequest setContentLoggingLimit(int contentLoggingLimit)

Set the limit to the content size that will be logged during #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.

Parameter
Name	Description
`contentLoggingLimit`	`int`

Returns
Type	Description
`HttpRequest`

setCurlLoggingEnabled(boolean curlLoggingEnabled)

public HttpRequest setCurlLoggingEnabled(boolean curlLoggingEnabled)

Sets whether logging in form of curl commands should be enabled for this request.

Defaults to true.

Parameter
Name	Description
`curlLoggingEnabled`	`boolean`

Returns
Type	Description
`HttpRequest`

setEncoding(HttpEncoding encoding)

public HttpRequest setEncoding(HttpEncoding encoding)

Sets the HTTP content encoding or null for none.

Parameter
Name	Description
`encoding`	`HttpEncoding`

Returns
Type	Description
`HttpRequest`

setFollowRedirects(boolean followRedirects)

public HttpRequest setFollowRedirects(boolean followRedirects)

Sets whether to follow redirects automatically.

The default value is true.

Parameter
Name	Description
`followRedirects`	`boolean`

Returns
Type	Description
`HttpRequest`

setHeaders(HttpHeaders headers)

public HttpRequest setHeaders(HttpHeaders headers)

Sets the HTTP request headers.

By default, this is a new unmodified instance of HttpHeaders.

Parameter
Name	Description
`headers`	`HttpHeaders`

Returns
Type	Description
`HttpRequest`

setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)

public HttpRequest setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)

Beta
Sets the HTTP I/O exception handler or null for none.

Parameter
Name	Description
`ioExceptionHandler`	`HttpIOExceptionHandler`

Returns
Type	Description
`HttpRequest`

setInterceptor(HttpExecuteInterceptor interceptor)

public 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.

Parameter
Name	Description
`interceptor`	`HttpExecuteInterceptor`

Returns
Type	Description
`HttpRequest`

setLoggingEnabled(boolean loggingEnabled)

public HttpRequest setLoggingEnabled(boolean loggingEnabled)

Sets whether logging should be enabled for this request.

Defaults to true.

Parameter
Name	Description
`loggingEnabled`	`boolean`

Returns
Type	Description
`HttpRequest`

setNumberOfRetries(int numRetries)

public 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. 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.

Parameter
Name	Description
`numRetries`	`int`

Returns
Type	Description
`HttpRequest`

setParser(ObjectParser parser)

public HttpRequest setParser(ObjectParser parser)

Sets the ObjectParser used to parse the response to this request or null for none.

This parser will be preferred over any registered HttpParser.

Parameter
Name	Description
`parser`	`ObjectParser`

Returns
Type	Description
`HttpRequest`

setReadTimeout(int readTimeout)

public HttpRequest setReadTimeout(int readTimeout)

Sets the timeout in milliseconds to read data from an established connection or 0 for an infinite timeout.

Parameter
Name	Description
`readTimeout`	`int`

Returns
Type	Description
`HttpRequest`

setRequestMethod(String requestMethod)

public HttpRequest setRequestMethod(String requestMethod)

Sets the HTTP request method or null for none.

Parameter
Name	Description
`requestMethod`	`String`

Returns
Type	Description
`HttpRequest`

setResponseHeaders(HttpHeaders responseHeaders)

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; }

Parameter
Name	Description
`responseHeaders`	`HttpHeaders`

Returns
Type	Description
`HttpRequest`

setResponseInterceptor(HttpResponseInterceptor responseInterceptor)

public HttpRequest setResponseInterceptor(HttpResponseInterceptor responseInterceptor)

Sets the HTTP response interceptor or null for none.

Parameter
Name	Description
`responseInterceptor`	`HttpResponseInterceptor`

Returns
Type	Description
`HttpRequest`

setResponseReturnRawInputStream(boolean responseReturnRawInputStream)

public HttpRequest setResponseReturnRawInputStream(boolean responseReturnRawInputStream)

Sets whether HttpResponse#getContent() should return raw input stream for this request.

The default value is false.

Parameter
Name	Description
`responseReturnRawInputStream`	`boolean`

Returns
Type	Description
`HttpRequest`

setRetryOnExecuteIOException(boolean retryOnExecuteIOException) (deprecated)

public HttpRequest setRetryOnExecuteIOException(boolean retryOnExecuteIOException)

Deprecated. (scheduled to be removed in 1.18) Use #setIOExceptionHandler(HttpIOExceptionHandler) instead.

Beta
Sets whether to retry the request if an IOException is encountered in LowLevelHttpRequest#execute().

The default value is false.

Parameter
Name	Description
`retryOnExecuteIOException`	`boolean`

Returns
Type	Description
`HttpRequest`

setSleeper(Sleeper sleeper)

public HttpRequest setSleeper(Sleeper sleeper)

Sets the sleeper. The default value is Sleeper#DEFAULT.

Parameter
Name	Description
`sleeper`	`Sleeper`

Returns
Type	Description
`HttpRequest`

setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)

public HttpRequest setSuppressUserAgentSuffix(boolean suppressUserAgentSuffix)

Sets whether to not add the suffix #USER_AGENT_SUFFIX to the User-Agent header.

The default value is false.

Parameter
Name	Description
`suppressUserAgentSuffix`	`boolean`

Returns
Type	Description
`HttpRequest`

setThrowExceptionOnExecuteError(boolean throwExceptionOnExecuteError)

public 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.

The default value is true.

Parameter
Name	Description
`throwExceptionOnExecuteError`	`boolean`

Returns
Type	Description
`HttpRequest`

setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)

public HttpRequest setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)

Sets the HTTP unsuccessful (non-2XX) response handler or null for none.

Parameter
Name	Description
`unsuccessfulResponseHandler`	`HttpUnsuccessfulResponseHandler`

Returns
Type	Description
`HttpRequest`

setUrl(GenericUrl url)

public HttpRequest setUrl(GenericUrl url)

Sets the HTTP request URL.

Parameter
Name	Description
`url`	`GenericUrl`

Returns
Type	Description
`HttpRequest`

setUseRawRedirectUrls(boolean useRawRedirectUrls)

public HttpRequest setUseRawRedirectUrls(boolean useRawRedirectUrls)

Sets whether to use raw redirect URLs.

The default value is false.

Parameter
Name	Description
`useRawRedirectUrls`	`boolean`

Returns
Type	Description
`HttpRequest`

setWriteTimeout(int writeTimeout)

public HttpRequest setWriteTimeout(int writeTimeout)

Sets the timeout in milliseconds to send POST/PUT data or 0 for an infinite timeout.

Parameter
Name	Description
`writeTimeout`	`int`

Returns
Type	Description
`HttpRequest`