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