com.google.api.client.http
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

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

void	addParser(HttpParser parser) Deprecated. (scheduled to be removed in 1.11) Use setParser(ObjectParser) instead.
HttpResponse	execute() Execute the HTTP request and returns the HTTP response.
BackOffPolicy	getBackOffPolicy() Returns the BackOffPolicy to use between retry attempts or null for none.
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().
boolean	getEnableGZipContent() Returns whether to enable gzip compression of HTTP content.
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.
HttpMethod	getMethod() Returns the HTTP request method.
int	getNumberOfRetries() Returns the number of retries that will be allowed to execute as the result of an HttpUnsuccessfulResponseHandler before being terminated or 0 to not retry requests.
ObjectParser	getParser() Returns the ObjectParser used to parse the response or null for none.
HttpParser	getParser(String contentType) Deprecated. (scheduled to be removed in 1.11) Use getParser() instead.
int	getReadTimeout() Returns the timeout in milliseconds to read data from an established connection or 0 for an infinite timeout.
HttpHeaders	getResponseHeaders() Returns the HTTP response headers.
boolean	getRetryOnExecuteIOException() Returns whether to retry the request if an IOException is encountered in LowLevelHttpRequest.execute().
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.
boolean	isAllowEmptyContent() Some servers will fail to process a POST/PUT/PATCH unless Content-Length header >= 1.
boolean	isLoggingEnabled() Returns whether logging should be enabled for this request.
static String	normalizeMediaType(String mediaType) Deprecated. (scheduled to be removed in 1.11) Use HttpMediaType.equalsIgnoreParameters(HttpMediaType) instead
HttpRequest	setAllowEmptyContent(boolean allowEmptyContent) Some servers will fail to process a POST/PUT/PATCH unless Content-Length header >= 1.
HttpRequest	setBackOffPolicy(BackOffPolicy backOffPolicy) Sets the BackOffPolicy to use between retry attempts or null for none.
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	setEnableGZipContent(boolean enableGZipContent) Returns whether to enable gzip compression of HTTP content.
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	setLoggingEnabled(boolean loggingEnabled) Sets whether logging should be enabled for this request.
HttpRequest	setMethod(HttpMethod method) Sets the HTTP request method.
HttpRequest	setNumberOfRetries(int numRetries) Returns the number of retries that will be allowed to execute as the result of an HttpUnsuccessfulResponseHandler before being terminated or 0 to not retry requests.
void	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	setResponseHeaders(HttpHeaders responseHeaders) Sets the HTTP response headers.
HttpRequest	setRetryOnExecuteIOException(boolean retryOnExecuteIOException) Sets whether to retry the request if an IOException is encountered in LowLevelHttpRequest.execute().
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) Returns the HTTP unsuccessful (non-2XX) response handler or null for none.
HttpRequest	setUrl(GenericUrl url) Sets the HTTP request URL.

Methods inherited from class java.lang.Object

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

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

Since:

1.4

See Also:

Constant Field Values

Method Detail

getTransport

public HttpTransport getTransport()

Returns the HTTP transport.

Since:

1.5

getMethod

public HttpMethod getMethod()

Returns the HTTP request method.

Since:

1.5

setMethod

public HttpRequest setMethod(HttpMethod method)

Sets the HTTP request method.

Since:

1.5

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 or null for none.

Since:

1.5

setContent

public HttpRequest setContent(HttpContent content)

Sets the HTTP request content or null for none.

Since:

1.5

getEnableGZipContent

public boolean getEnableGZipContent()

Returns whether to enable gzip compression of HTTP content.

Since:

1.5

setEnableGZipContent

public HttpRequest setEnableGZipContent(boolean enableGZipContent)

Returns whether to enable gzip compression of HTTP content.

By default it is false.

To avoid the overhead of GZip compression for small content, one may want to set this to true only for HttpContent.getLength() above a certain limit. For example:

  public static class MyInterceptor implements HttpExecuteInterceptor {
    public void intercept(HttpRequest request) throws IOException {
      if (request.getContent() != null && request.getContent().getLength() >= 256) {
        request.setEnableGZipContent(true);
      }
    }
  }
 

Since:

1.5

getBackOffPolicy

public BackOffPolicy getBackOffPolicy()

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

Since:

1.7

setBackOffPolicy

public HttpRequest setBackOffPolicy(BackOffPolicy backOffPolicy)

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

Since:

1.7

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.

Upgrade warning: prior to version 1.9, the default was 100,000 bytes, but now it is 16KB.

Since:

1.7

setContentLoggingLimit

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.

Upgrade warning: prior to version 1.9, the default was 100,000 bytes, but now it is 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

getConnectTimeout

public int getConnectTimeout()

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

Since:

1.5

setConnectTimeout

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

Since:

1.5

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

Since:

1.5

setReadTimeout

public HttpRequest setReadTimeout(int readTimeout)

Sets the timeout in milliseconds to read data from an established connection or 0 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 of execute() (before executing the HTTP request) or null for none.

Since:

1.5

setInterceptor

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.

Since:

1.5

getUnsuccessfulResponseHandler

public HttpUnsuccessfulResponseHandler getUnsuccessfulResponseHandler()

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

Since:

1.5

setUnsuccessfulResponseHandler

public HttpRequest setUnsuccessfulResponseHandler(HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler)

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

Since:

1.5

setAllowEmptyContent

public HttpRequest setAllowEmptyContent(boolean allowEmptyContent)

Some servers will fail to process a POST/PUT/PATCH unless Content-Length header >= 1. If this value is set to false then " " is set as the content with Content-Length 1 for empty contents. Defaults to true.

Since:

1.7

isAllowEmptyContent

public boolean isAllowEmptyContent()

Some servers will fail to process a POST/PUT/PATCH unless Content-Length header >= 1. If this value is set to false then " " is set as the content with Content-Length 1 for empty contents. Defaults to true.

Since:

1.7

getNumberOfRetries

public int getNumberOfRetries()

Returns the number of retries that will be allowed to execute as the result of an HttpUnsuccessfulResponseHandler before being terminated or 0 to not retry requests.

Since:

1.5

setNumberOfRetries

public HttpRequest setNumberOfRetries(int numRetries)

Returns the number of retries that will be allowed to execute as the result of an HttpUnsuccessfulResponseHandler before being terminated or 0 to not retry requests.

The default value is 10.

Since:

1.5

addParser

@Deprecated
public void addParser(HttpParser parser)

Deprecated. (scheduled to be removed in 1.11) Use setParser(ObjectParser) instead.

Adds an HTTP response content parser.

If there is already a previous parser defined for this new parser (as defined by getParser(String) then the previous parser will be removed.

Any parser set by calling setParser(ObjectParser) will be preferred over this parser.

Since:

1.4

setParser

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

Since:

1.10

getParser

@Deprecated
public final HttpParser getParser(String contentType)

Deprecated. (scheduled to be removed in 1.11) Use getParser() instead.

Returns the HTTP response content parser to use for the given content type or null if none is defined.

Parameters:

contentType - content type or null for null result

Returns:

HTTP response content parser or null for null input

Since:

1.4

getParser

public final ObjectParser getParser()

Returns the ObjectParser used to parse the response or null 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 of execute() 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 of execute() 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

public boolean getRetryOnExecuteIOException()

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

Since:

1.9

setRetryOnExecuteIOException

public HttpRequest setRetryOnExecuteIOException(boolean retryOnExecuteIOException)

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

The default value is false.

Since:

1.9

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.

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:

HTTP response for an HTTP success response (or HTTP error response if getThrowExceptionOnExecuteError() is false)

Throws:

HttpResponseException - for an HTTP error response (only if getThrowExceptionOnExecuteError() is true)

IOException

See Also:

HttpResponse.isSuccessStatusCode()

normalizeMediaType

@Deprecated
public static String normalizeMediaType(String mediaType)

Deprecated. (scheduled to be removed in 1.11) Use HttpMediaType.equalsIgnoreParameters(HttpMediaType) instead

Returns the normalized media type without parameters of the form type "/" subtype" as specified in Media Types.

Parameters:

mediaType - unnormalized media type with possible parameters or null for null result

Returns:

normalized media type without parameters or null for null input

Since:

1.4