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