java/src/main/com/google/appengine/api/urlfetch/URLFetchService.java

   1 // Copyright 2007 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.urlfetch;
   4
   5 import java.io.IOException;
   6 import java.net.MalformedURLException;
   7 import java.net.SocketTimeoutException;
   8 import java.net.URL;
   9 import java.util.concurrent.Future;
  10
  11 /**
  12  * The {@code URLFetchService} provides a way for user code to execute
  13  * HTTP requests to external URLs.
  14  *
  15  * <p>Chunked and hanging requests are not supported, and all content
  16  * will be returned in a single block.
  17  *
  18  */
  19 public interface URLFetchService {
  20   /**
  21    * System property for defining a global default URLFetch deadline.
  22    */
  23   final String DEFAULT_DEADLINE_PROPERTY = "appengine.api.urlfetch.defaultDeadline";
  24
  25   /**
  26    * Convenience method for retrieving a specific URL via a HTTP GET
  27    * request with no custom headers and default values for all
  28    * {@link FetchOptions} attributes.  For more complex requests, use
  29    * {@link #fetch(HTTPRequest)}.
  30    *
  31    * @param url The url to fetch.
  32    *
  33    * @return The result of the fetch.
  34    *
  35    * @throws MalformedURLException If the provided URL is malformed.
  36    * @throws RequestPayloadTooLargeException If the provided payload exceeds the limit.
  37    * @throws IOException If the remote service could not be contacted or the
  38    * URL could not be fetched.
  39    * @throws SocketTimeoutException If the request takes too long to respond.
  40    * @throws ResponseTooLargeException If the response is too large.
  41    * @throws javax.net.ssl.SSLHandshakeException If the server's SSL
  42    * certificate could not be validated and validation was requested.
  43    */
  44   HTTPResponse fetch(URL url) throws IOException;
  45
  46   /**
  47    * Execute the specified request and return its response.
  48    *
  49    * @param request The http request.
  50    *
  51    * @return The result of the fetch.
  52    *
  53    * @throws IllegalArgumentException If {@code request.getMethod} is not
  54    * supported by the {@code URLFetchService}.
  55    * @throws MalformedURLException If the provided URL is malformed.
  56    * @throws RequestPayloadTooLargeException If the provided payload exceeds the limit.
  57    * @throws IOException If the remote service could not be contacted or the
  58    * URL could not be fetched.
  59    * @throws SocketTimeoutException If the request takes too long to respond.
  60    * @throws ResponseTooLargeException If response truncation has been disabled
  61    * via the {@link FetchOptions} object on {@code request} and the response is
  62    * too large.  Some responses are too large to even retrieve from the remote
  63    * server, and in these cases the exception is thrown even if response
  64    * truncation is enabled.
  65    * @throws javax.net.ssl.SSLHandshakeException If the server's SSL
  66    * certificate could not be validated and validation was requested.
  67    */
  68   HTTPResponse fetch(HTTPRequest request) throws IOException;
  69
  70   /**
  71    * Convenience method for asynchronously retrieving a specific URL
  72    * via a HTTP GET request with no custom headers and default values
  73    * for all {@link FetchOptions} attributes.  For more complex
  74    * requests, use {@link #fetchAsync(HTTPRequest)}.
  75    *
  76    * @param url The url to fetch.
  77    *
  78    * @return A future containing the result of the fetch, or one of
  79    * the exceptions documented for {@link #fetch(URL)}.
  80    */
  81   Future<HTTPResponse> fetchAsync(URL url);
  82
  83   /**
  84    * Asynchronously execute the specified request and return its response.
  85    *
  86    * @param request The http request.
  87    *
  88    * @return A future containing the result of the fetch, or one of
  89    * the exceptions documented for {@link #fetch(HTTPRequest)}.
  90    */
  91   Future<HTTPResponse> fetchAsync(HTTPRequest request);
  92 }