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

   1 // Copyright 2007 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.urlfetch;
   4
   5 import java.io.Serializable;
   6 import java.net.URL;
   7 import java.util.ArrayList;
   8 import java.util.Collections;
   9 import java.util.LinkedHashMap;
  10 import java.util.List;
  11
  12 /**
  13  * {@code HTTPRequest} encapsulates a single HTTP request that is made
  14  * via the {@code URLFetchService}.
  15  *
  16  */
  17 public class HTTPRequest implements Serializable {
  18   private final HTTPMethod method;
  19   private final URL url;
  20   private final LinkedHashMap<String, HTTPHeader> headers;
  21   private final FetchOptions fetchOptions;
  22
  23   /**
  24    * The payload of this request, or null if there is no payload
  25    * present.
  26    */
  27   private byte[] payload = null;
  28
  29   /**
  30    * Creates a {@code HTTPRequest} that represents a GET request to
  31    * the specified URL.
  32    */
  33   public HTTPRequest(URL url) {
  34     this(url, HTTPMethod.GET);
  35   }
  36
  37   /**
  38    * Creates a {@code HTTPRequest} that represents an HTTP request to
  39    * the specified URL with the specified HTTP method (GET, POST, etc).
  40    */
  41   public HTTPRequest(URL url, HTTPMethod method) {
  42     this(url, method, FetchOptions.Builder.withDefaults());
  43   }
  44
  45   /**
  46    * Creates a {@code HTTPRequest} that represents an HTTP request to
  47    * the specified URL with the specified HTTP method (GET, POST, etc)
  48    * and the specified {@link FetchOptions}.
  49    */
  50   public HTTPRequest(URL url, HTTPMethod method, FetchOptions fetchOptions) {
  51     this.url = url;
  52     this.method = method;
  53     this.fetchOptions = fetchOptions;
  54     this.headers = new LinkedHashMap<String, HTTPHeader>();
  55   }
  56
  57   /**
  58    * Gets the HTTP method for this request (GET, POST, etc).
  59    */
  60   public HTTPMethod getMethod() {
  61     return method;
  62   }
  63
  64   /**
  65    * Gets the URL for this request.
  66    */
  67   public URL getURL() {
  68     return url;
  69   }
  70
  71   /**
  72    * Gets the payload (such as POST body) for this request.  Certain HTTP
  73    * methods (e.g. GET) will not have any payload, and this method
  74    * will return null.
  75    */
  76   public byte[] getPayload() {
  77     return payload;
  78   }
  79
  80   /**
  81    * Sets the payload for this request.  This method should not be
  82    * called for certain HTTP methods (e.g. GET).
  83    */
  84   public void setPayload(byte[] payload) {
  85     this.payload = payload;
  86   }
  87
  88   /**
  89    * Adds {@code header} to this request. If an {@code HTTPHeader} with
  90    * the same {@code name} already exists for this request, it's values
  91    * are merged with {@code header}.
  92    *
  93    * @param header a not {@code null} {@code HTTPHeader}
  94    */
  95   public void addHeader(HTTPHeader header) {
  96     String name = header.getName();
  97     HTTPHeader newHeader = headers.get(name);
  98     if (newHeader == null) {
  99       headers.put(name, new HTTPHeader(name, header.getValue()));
 100     } else {
 101       headers.put(name, new HTTPHeader(name, newHeader.getValue() + ", " + header.getValue()));
 102     }
 103   }
 104
 105   /**
 106    * Sets an {@code HTTPHeader} for this request. If an
 107    * {@link HTTPHeader} with the same {@code name}
 108    * already exists, its value is replaced.
 109    */
 110   public void setHeader(HTTPHeader header) {
 111     headers.put(header.getName(), header);
 112   }
 113
 114   /**
 115    * Returns an immutable {@code List} of {@code HTTPHeader} objects
 116    * that have been added to this request.
 117    */
 118   public List<HTTPHeader> getHeaders() {
 119     return Collections.unmodifiableList(new ArrayList<HTTPHeader>(headers.values()));
 120   }
 121
 122   /**
 123    * Get the fetch options for this request.
 124    */
 125   public FetchOptions getFetchOptions() {
 126     return fetchOptions;
 127   }
 128 }