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   public boolean getAllowTruncate() {
 161     return allowTruncate;
 162   }
 163
 164   public boolean getFollowRedirects() {
 165     return followRedirects;
 166   }
 167
 168   CertificateValidationBehavior getCertificateValidationBehavior() {
 169     return certificateValidationBehavior;
 170   }
 171
 172   public Double getDeadline() {
 173     return deadline;
 174   }
 175
 176   public boolean getValidateCertificate() {
 177     return certificateValidationBehavior == CertificateValidationBehavior.VALIDATE;
 178   }
 179
 180   /**
 181    * Contains static creation methods for {@link FetchOptions}.
 182    */
 183   public static final class Builder {
 184
 185     /**
 186      * Create a {@link FetchOptions} that allows truncation of the response.
 187      * Shorthand for <code>FetchOptions.withDefaults().allowTruncate();</code>.
 188      * Please read the {@link FetchOptions} class javadoc for an explanation of
 189      * how response truncating works.
 190      * @return The newly created FetchOptions instance.
 191      */
 192     public static FetchOptions allowTruncate() {
 193       return withDefaults().allowTruncate();
 194     }
 195
 196     /**
 197      * Create a {@link FetchOptions} that disallows truncation of the response.
 198      * Shorthand for
 199      * <code>FetchOptions.withDefaults().disallowTruncate();</code>.
 200      * Please read the {@link FetchOptions} class javadoc for an explanation of
 201      * how esponse truncating works.
 202      * @return The newly created FetchOptions instance.
 203      */
 204     public static FetchOptions disallowTruncate() {
 205       return withDefaults().disallowTruncate();
 206     }
 207
 208     /**
 209      * Create a {@link FetchOptions} that follows redirects.
 210      * Shorthand for
 211      * <code>FetchOptions.withDefaults().followRedirects();</code>.
 212      * Please read the {@link FetchOptions} class javadoc for an explanation of
 213      * how redirection following works.
 214      * @return The newly created FetchOptions instance.
 215      */
 216     public static FetchOptions followRedirects() {
 217       return withDefaults().followRedirects();
 218     }
 219
 220     /**
 221      * Create a {@link FetchOptions} that does not follow redirects.
 222      * Shorthand for
 223      * <code>FetchOptions.withDefaults().doNotFollowRedirects();</code>.
 224      * Please read the {@link FetchOptions} class javadoc for an explanation of
 225      * how redirection following works.
 226      * @return The newly created FetchOptions instance.
 227      */
 228     public static FetchOptions doNotFollowRedirects() {
 229       return withDefaults().doNotFollowRedirects();
 230     }
 231
 232     /**
 233      * Create a {@link FetchOptions} that performs SSL certificate validation.
 234      *
 235      * Shorthand for
 236      * <code>FetchOptions.withDefaults().validateCertificate();</code>.
 237      * Please read the {@link FetchOptions} class javadoc for an explanation of
 238      * how certificate validation works.
 239      * @return The newly created FetchOptions instance.
 240      */
 241     public static FetchOptions validateCertificate() {
 242       return withDefaults().validateCertificate();
 243     }
 244
 245     /**
 246      * Create a {@link FetchOptions} that does not perform SSL certificate
 247      * validation.
 248      *
 249      * Shorthand for
 250      * <code>FetchOptions.withDefaults().doNotValidateCertificate();</code>.
 251      * Please read the {@link FetchOptions} class javadoc for an explanation of
 252      * how certificate validation works.
 253      * @return The newly created FetchOptions instance.
 254      */
 255     public static FetchOptions doNotValidateCertificate() {
 256       return withDefaults().doNotValidateCertificate();
 257     }
 258
 259     /**
 260      * Create a {@link FetchOptions} with the specified deadline.
 261      * Shorthand for
 262      * <code>FetchOptions.withDefaults().setDeadline(deadline);</code>.
 263      * @return The newly created FetchOptions instance.
 264      */
 265     public static FetchOptions withDeadline(double deadline) {
 266       return withDefaults().setDeadline(deadline);
 267     }
 268
 269     /**
 270      * Helper method for creating a {@link FetchOptions}
 271      * instance with default values.
 272      *
 273      * @see FetchOptions#DEFAULT_ALLOW_TRUNCATE
 274      * @see FetchOptions#DEFAULT_FOLLOW_REDIRECTS
 275      * @see FetchOptions#DEFAULT_DEADLINE
 276      */
 277     public static FetchOptions withDefaults() {
 278       return new FetchOptions();
 279     }
 280
 281     private Builder() {}
 282   }
 283 }