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

  • Field Details

    • VERSION

      public static final String VERSION
      Current version of the Google API Client Library for Java.
      Since:
      1.8
      See Also:

    • 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:

    • 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:

    • executeInterceptor

      private HttpExecuteInterceptor executeInterceptor
      HTTP request execute interceptor to intercept the start of execute() (before executing the HTTP request) or null for none.

    • headers

      private HttpHeaders headers
      HTTP request headers.

    • responseHeaders

      private HttpHeaders responseHeaders
      HTTP response headers.

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

    • numRetries

      private int numRetries
      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.

    • contentLoggingLimit

      private int contentLoggingLimit
      Determines the limit to the content size that will be logged during execute().

      Content will only be logged if isLoggingEnabled() is true.

      If the content size is greater than this limit then it will not be logged.

      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.

    • loggingEnabled

      private boolean loggingEnabled
      Determines whether logging should be enabled for this request. Defaults to true.

    • curlLoggingEnabled

      private boolean curlLoggingEnabled
      Determines whether logging in form of curl commands should be enabled for this request.

    • content

      private HttpContent content
      HTTP request content or null for none.

    • transport

      private final HttpTransport transport
      HTTP transport.

    • requestMethod

      private String requestMethod
      HTTP request method or null for none.

    • url

      private GenericUrl url
      HTTP request URL.

    • connectTimeout

      private int connectTimeout
      Timeout in milliseconds to establish a connection or 0 for an infinite timeout.

    • readTimeout

      private int readTimeout
      Timeout in milliseconds to read data from an established connection or 0 for an infinite timeout.

    • unsuccessfulResponseHandler

      private HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler
      HTTP unsuccessful (non-2XX) response handler or null for none.

    • ioExceptionHandler

      @Beta private HttpIOExceptionHandler ioExceptionHandler
      HTTP I/O exception handler or null for none.

    • responseInterceptor

      private HttpResponseInterceptor responseInterceptor
      HTTP response interceptor or null for none.

    • objectParser

      private ObjectParser objectParser
      Parser used to parse responses.

    • encoding

      private HttpEncoding encoding
      HTTP content encoding or null for none.

    • backOffPolicy

      @Deprecated @Beta private BackOffPolicy backOffPolicy
      Deprecated.
      The BackOffPolicy to use between retry attempts or null for none.

    • followRedirects

      private boolean followRedirects
      Whether to automatically follow redirects (true by default).

    • throwExceptionOnExecuteError

      private boolean throwExceptionOnExecuteError
      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 (true by default).

    • retryOnExecuteIOException

      @Deprecated @Beta private boolean retryOnExecuteIOException
      Deprecated.
      Whether to retry the request if an IOException is encountered in LowLevelHttpRequest.execute().

    • suppressUserAgentSuffix

      private boolean suppressUserAgentSuffix
      Whether to not add the suffix USER_AGENT_SUFFIX to the User-Agent header.

      It is false by default.

    • sleeper

      private Sleeper sleeper
      Sleeper.

  • Constructor Details

    • HttpRequest

      HttpRequest(HttpTransport transport, String requestMethod)
      Parameters:
      transport - HTTP transport
      requestMethod - HTTP request method or null for none

  • Method Details

    • getTransport

      public HttpTransport getTransport()
      Returns the HTTP transport.
      Since:
      1.5

    • getRequestMethod

      public String getRequestMethod()
      Returns the HTTP request method or null for none.
      Since:
      1.12

    • setRequestMethod

      public HttpRequest setRequestMethod(String requestMethod)
      Sets the HTTP request method or null 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 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

    • getEncoding

      public HttpEncoding getEncoding()
      Returns the HTTP content encoding or null for none.
      Since:
      1.14

    • setEncoding

      public HttpRequest setEncoding(HttpEncoding encoding)
      Sets the HTTP content encoding or null for none.
      Since:
      1.14

    • getBackOffPolicy

      @Deprecated @Beta 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.
      Since:
      1.7

    • setBackOffPolicy

      @Deprecated @Beta 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.
      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.

      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.

      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 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)
      Sets the HTTP unsuccessful (non-2XX) response handler or null for none.
      Since:
      1.5

    • getIOExceptionHandler

      @Beta public HttpIOExceptionHandler getIOExceptionHandler()
      Beta
      Returns the HTTP I/O exception handler or null for none.
      Since:
      1.15

    • setIOExceptionHandler

      @Beta public HttpRequest setIOExceptionHandler(HttpIOExceptionHandler ioExceptionHandler)
      Beta
      Sets the HTTP I/O exception handler or null for none.
      Since:
      1.15

    • getResponseInterceptor

      public HttpResponseInterceptor getResponseInterceptor()
      Returns the HTTP response interceptor or null for none.
      Since:
      1.13

    • setResponseInterceptor

      public HttpRequest setResponseInterceptor(HttpResponseInterceptor responseInterceptor)
      Sets the HTTP response interceptor or null 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 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.
      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 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.

      Since:
      1.5

    • setParser

      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.

      Since:
      1.10

    • 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

      @Deprecated @Beta 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().
      Since:
      1.9

    • setRetryOnExecuteIOException

      @Deprecated @Beta 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.

      Since:
      1.9

    • getSuppressUserAgentSuffix

      public boolean getSuppressUserAgentSuffix()
      Returns whether to not add the suffix USER_AGENT_SUFFIX to the User-Agent header.
      Since:
      1.11

    • setSuppressUserAgentSuffix

      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.

      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 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:

    • 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 using executeAsync(Executor) in a single separate thread using Executors.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 is Sleeper.DEFAULT.
      Since:
      1.15