Package com.google.api.client.http

Class HttpRequest

  • public final class HttpRequest
extends java.lang.Object
    HTTP request.

    Implementation is not thread-safe.

    Since:
    1.0

    • Field Detail

      • VERSION

        public static final java.lang.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 java.lang.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

      • 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

      • 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 java.lang.String requestMethod
        HTTP request method or null for none.

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

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

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

      • HttpRequest

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

    • Method Detail

      • getTransport

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

      • getRequestMethod

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

      • setRequestMethod

        public HttpRequest setRequestMethod​(java.lang.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

      • 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

      • 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

      • 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

      • 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

      • 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 java.io.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)
        java.io.IOException
        See Also:
        HttpResponse.isSuccessStatusCode()

      • executeAsync

        @Beta
public java.util.concurrent.Future<HttpResponse> executeAsync​(java.util.concurrent.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 java.util.concurrent.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