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

   1 // Copyright 2008 Google Inc. All Rights Reserved.
   2 package com.google.appengine.api.urlfetch;
   3
   4 import java.io.Serializable;
   5
   6 /**
   7  * Allows users to customize the behavior of {@link URLFetchService}
   8  * operations.
   9  * <p>
  10  * If {@link #allowTruncate()} is called, {@link URLFetchService}
  11  * will truncate large responses and return them without error.
  12  * <p>
  13  * If {@link #disallowTruncate} is called,
  14  * {@link ResponseTooLargeException} will be thrown if the response is too
  15  * large.
  16  * <p>
  17  * If {@link #followRedirects()} is called the {@link URLFetchService}
  18  * operation will follow redirects.
  19  * <p>
  20  * If {@link #doNotFollowRedirects()} is called the {@link URLFetchService}
  21  * operation will not follow redirects.
  22  * <p>
  23  * If {@link #validateCertificate()} is called the {@link URLFetchService}
  24  * operation will, if using an HTTPS connection, instruct the application to
  25  * send a request to the server only if the certificate is valid and signed by a
  26  * trusted certificate authority (CA), and also includes a hostname that matches
  27  * the certificate.
  28  * If the certificate validation fails, a {@link
  29  * javax.net.ssl.SSLHandshakeException} exception is thrown.
  30  * HTTP connections are unaffected by this option.
  31  * <p>
  32  * If {@link #doNotValidateCertificate()} is called the
  33  * {@link URLFetchService} will not validate the server's SSL certificate
  34  * in any fashion. This is the default behavior. Note, however, that validation
  35  * will be turned on by default in the near future. If you rely upon making
  36  * requests to a site with an invalid or untrusted certificate, you should
  37  * explicitly call {@link #doNotValidateCertificate()} to avoid errors in future
  38  * versions.
  39  * <p>
  40  * Notes on usage:<br>
  41  * The recommended way to instantiate a {@code FetchOptions} object is to
  42  * statically import {@link Builder}.* and invoke a static
  43  * creation method followed by an instance mutator (if needed):
  44  *
  45  * <pre>
  46  * import static com.google.appengine.api.urlfetch.FetchOptions.Builder.*;
  47  *
  48  * ...
  49  * URL url = getURLToFetch();
  50  * urlFetchService.fetch(new HTTPRequest(url, HTTPMethod.GET,
  51  *     allowTruncate()));
  52  *
  53  * urlFetchService.fetch(new HTTPRequest(url, HTTPMethod.GET,
  54  *     allowTruncate().doNotFollowRedirects()));
  55  * </pre>
  56  *
  57  */
  58 public final class FetchOptions implements Serializable {
  59   static final long serialVersionUID = 3904557385413253999L;
  60
  61   public static final boolean DEFAULT_ALLOW_TRUNCATE = false;
  62   public static final boolean DEFAULT_FOLLOW_REDIRECTS = true;
  63
  64   /**
  65    * The default deadline is 5 seconds.
  66    */
  67   public static final Double DEFAULT_DEADLINE = null;
  68
  69   private boolean allowTruncate = DEFAULT_ALLOW_TRUNCATE;
  70   private boolean followRedirects = DEFAULT_FOLLOW_REDIRECTS;
  71   private Double deadline = DEFAULT_DEADLINE;
  72
  73   enum CertificateValidationBehavior {
  74     DEFAULT,
  75     VALIDATE,
  76     DO_NOT_VALIDATE
  77   }
  78
  79   private CertificateValidationBehavior certificateValidationBehavior =
  80       CertificateValidationBehavior.DEFAULT;
  81
  82   private FetchOptions() {
  83   }
  84
  85   /**
  86    * Enables response truncation.  Please read
  87    * the class javadoc for an explanation of how allowTruncate is used.
  88    * @return {@code this} (for chaining)
  89    */
  90   public FetchOptions allowTruncate() {
  91     this.allowTruncate = true;
  92     return this;
  93   }
  94
  95   /**
  96    * Disables response truncation.  Please read
  97    * the class javadoc for an explanation of how allowTruncate is used.
  98    * @return {@code this} (for chaining)
  99    */
 100   public FetchOptions disallowTruncate() {
 101     this.allowTruncate = false;
 102     return this;
 103   }
 104
 105   /**
 106    * Enables following of redirects.  Please read
 107    * the class javadoc for an explanation of how followRedirects is used.
 108    * @return {@code this} (for chaining)
 109    */
 110   public FetchOptions followRedirects() {
 111     this.followRedirects = true;
 112     return this;
 113   }
 114
 115   /**
 116    * Enables certificate validation on HTTPS connections via the normal
 117    * CA-based mechanism. Please read the class javadoc for an explanation of
 118    * how this option affects certificate validation behavior.
 119    * @return {@code this} (for chaining)
 120    */
 121   public FetchOptions validateCertificate() {
 122     this.certificateValidationBehavior = CertificateValidationBehavior.VALIDATE;
 123     return this;
 124   }
 125
 126   /**
 127    * Disables certificate validation on HTTPS connections. Please read the
 128    * class javadoc for an explanation of how this option affects certificate
 129    * validation behavior.
 130    * @return {@code this} (for chaining)
 131    */
 132   public FetchOptions doNotValidateCertificate() {
 133     this.certificateValidationBehavior = CertificateValidationBehavior.DO_NOT_VALIDATE;
 134     return this;
 135   }
 136
 137   /**
 138    * Sets the deadline, in seconds, for the fetch request.
 139    * @throws IllegalArgumentException if deadline is not positive
 140    * @return {@code this} (for chaining)
 141    */
 142   public FetchOptions setDeadline(Double deadline) {
 143     if (deadline != null && deadline <= 0.0) {
 144       throw new IllegalArgumentException("Deadline must be > 0, got " + deadline);
 145     }
 146     this.deadline = deadline;
 147     return this;
 148   }
 149
 150   /**
 151    * Disables following of redirects.  Please read
 152    * the class javadoc for an explanation of how doNotFollowRedirects is used.
 153    * @return {@code this} (for chaining)
 154    */
 155   public FetchOptions doNotFollowRedirects() {
 156     this.followRedirects = false;
 157     return this;
 158   }
 159
 160   boolean getAllowTruncate() {
 161     return allowTruncate;
 162   }
 163
 164   boolean getFollowRedirects() {
 165     return followRedirects;
 166   }
 167
 168   CertificateValidationBehavior getCertificateValidationBehavior() {
 169     return certificateValidationBehavior;
 170   }
 171
 172   Double getDeadline() {
 173     return deadline;
 174   }
 175
 176   /**
 177    * Contains static creation methods for {@link FetchOptions}.
 178    */
 179   public static final class Builder {
 180
 181     /**
 182      * Create a {@link FetchOptions} that allows truncation of the response.
 183      * Shorthand for <code>FetchOptions.withDefaults().allowTruncate();</code>.
 184      * Please read the {@link FetchOptions} class javadoc for an explanation of
 185      * how response truncating works.
 186      * @return The newly created FetchOptions instance.
 187      */
 188     public static FetchOptions allowTruncate() {
 189       return withDefaults().allowTruncate();
 190     }
 191
 192     /**
 193      * Create a {@link FetchOptions} that disallows truncation of the response.
 194      * Shorthand for
 195      * <code>FetchOptions.withDefaults().disallowTruncate();</code>.
 196      * Please read the {@link FetchOptions} class javadoc for an explanation of
 197      * how esponse truncating works.
 198      * @return The newly created FetchOptions instance.
 199      */
 200     public static FetchOptions disallowTruncate() {
 201       return withDefaults().disallowTruncate();
 202     }
 203
 204     /**
 205      * Create a {@link FetchOptions} that follows redirects.
 206      * Shorthand for
 207      * <code>FetchOptions.withDefaults().followRedirects();</code>.
 208      * Please read the {@link FetchOptions} class javadoc for an explanation of
 209      * how redirection following works.
 210      * @return The newly created FetchOptions instance.
 211      */
 212     public static FetchOptions followRedirects() {
 213       return withDefaults().followRedirects();
 214     }
 215
 216     /**
 217      * Create a {@link FetchOptions} that does not follow redirects.
 218      * Shorthand for
 219      * <code>FetchOptions.withDefaults().doNotFollowRedirects();</code>.
 220      * Please read the {@link FetchOptions} class javadoc for an explanation of
 221      * how redirection following works.
 222      * @return The newly created FetchOptions instance.
 223      */
 224     public static FetchOptions doNotFollowRedirects() {
 225       return withDefaults().doNotFollowRedirects();
 226     }
 227
 228     /**
 229      * Create a {@link FetchOptions} that performs SSL certificate validation.
 230      *
 231      * Shorthand for
 232      * <code>FetchOptions.withDefaults().validateCertificate();</code>.
 233      * Please read the {@link FetchOptions} class javadoc for an explanation of
 234      * how certificate validation works.
 235      * @return The newly created FetchOptions instance.
 236      */
 237     public static FetchOptions validateCertificate() {
 238       return withDefaults().validateCertificate();
 239     }
 240
 241     /**
 242      * Create a {@link FetchOptions} that does not perform SSL certificate
 243      * validation.
 244      *
 245      * Shorthand for
 246      * <code>FetchOptions.withDefaults().doNotValidateCertificate();</code>.
 247      * Please read the {@link FetchOptions} class javadoc for an explanation of
 248      * how certificate validation works.
 249      * @return The newly created FetchOptions instance.
 250      */
 251     public static FetchOptions doNotValidateCertificate() {
 252       return withDefaults().doNotValidateCertificate();
 253     }
 254
 255     /**
 256      * Create a {@link FetchOptions} with the specified deadline.
 257      * Shorthand for
 258      * <code>FetchOptions.withDefaults().setDeadline(deadline);</code>.
 259      * @return The newly created FetchOptions instance.
 260      */
 261     public static FetchOptions withDeadline(double deadline) {
 262       return withDefaults().setDeadline(deadline);
 263     }
 264
 265     /**
 266      * Helper method for creating a {@link FetchOptions}
 267      * instance with default values.
 268      *
 269      * @see FetchOptions#DEFAULT_ALLOW_TRUNCATE
 270      * @see FetchOptions#DEFAULT_FOLLOW_REDIRECTS
 271      * @see FetchOptions#DEFAULT_DEADLINE
 272      */
 273     public static FetchOptions withDefaults() {
 274       return new FetchOptions();
 275     }
 276
 277     private Builder() {}
 278   }
 279 }