com.google.api.client.http
Class HttpRequest

java.lang.Object
  extended by 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.
 
Method Summary
 void addParser(HttpParser parser)
          Adds an HTTP response content parser.
 HttpResponse execute()
          Execute the HTTP request and returns the HTTP response.
 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.
 boolean getDisableContentLogging()
          Returns whether to disable request content logging during execute() (unless Level.ALL is loggable which forces all logging).
 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.
 HttpParser getParser(String contentType)
          Returns the HTTP response content parser to use for the given content type or null if none is defined.
 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.
 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.
static String normalizeMediaType(String mediaType)
          Returns the normalized media type without parameters of the form type "/" subtype" as specified in Media Types.
 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 setDisableContentLogging(boolean disableContentLogging)
          Returns whether to disable request content logging during execute() (unless Level.ALL is loggable which forces all logging).
 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 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.
 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 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

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

getDisableContentLogging

public boolean getDisableContentLogging()
Returns whether to disable request content logging during execute() (unless Level.ALL is loggable which forces all logging).

Since:
1.5

setDisableContentLogging

public HttpRequest setDisableContentLogging(boolean disableContentLogging)
Returns whether to disable request content logging during execute() (unless Level.ALL is loggable which forces all logging).

Useful for example if content has sensitive data such as an authentication information. Defaults to false.

Since:
1.5

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

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

public void addParser(HttpParser parser)
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.

Since:
1.4

getParser

public final HttpParser getParser(String contentType)
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

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

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.

Returns:
HTTP response for an HTTP success code
Throws:
HttpResponseException - for an HTTP error code
IOException
See Also:
HttpResponse.isSuccessStatusCode()

normalizeMediaType

public static String normalizeMediaType(String mediaType)
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


Copyright © 2011 Google. All Rights Reserved.