1 // Copyright 2008 Google Inc. All Rights Reserved.
2 package com
.google
.appengine
.api
.urlfetch
;
4 import java
.io
.Serializable
;
7 * Allows users to customize the behavior of {@link URLFetchService}
10 * If {@link #allowTruncate()} is called, {@link URLFetchService}
11 * will truncate large responses and return them without error.
13 * If {@link #disallowTruncate} is called,
14 * {@link ResponseTooLargeException} will be thrown if the response is too
17 * If {@link #followRedirects()} is called the {@link URLFetchService}
18 * operation will follow redirects.
20 * If {@link #doNotFollowRedirects()} is called the {@link URLFetchService}
21 * operation will not follow redirects.
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.
28 * If {@link #doNotValidateCertificate()} is called the
29 * {@link URLFetchService} will not validate the server's SSL certificate
32 * If neither {@link #validateCertificate()} nor
33 * {@link #doNotValidateCertificate()} is called, then the underlying
34 * {@code URLFetchService} implementation determines what type of validation
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):
43 * import static com.google.appengine.api.urlfetch.FetchOptions.Builder.*;
46 * URL url = getURLToFetch();
47 * urlFetchService.fetch(new HTTPRequest(url, HTTPMethod.GET,
50 * urlFetchService.fetch(new HTTPRequest(url, HTTPMethod.GET,
51 * allowTruncate().doNotFollowRedirects()));
55 public final class FetchOptions
implements Serializable
{
56 static final long serialVersionUID
= 3904557385413253999L;
58 public static final boolean DEFAULT_ALLOW_TRUNCATE
= false;
59 public static final boolean DEFAULT_FOLLOW_REDIRECTS
= true;
62 * The default deadline is defined externally.
64 public static final Double DEFAULT_DEADLINE
= null;
66 private boolean allowTruncate
= DEFAULT_ALLOW_TRUNCATE
;
67 private boolean followRedirects
= DEFAULT_FOLLOW_REDIRECTS
;
68 private Double deadline
= DEFAULT_DEADLINE
;
70 enum CertificateValidationBehavior
{
76 private CertificateValidationBehavior certificateValidationBehavior
=
77 CertificateValidationBehavior
.DEFAULT
;
79 private FetchOptions() {
83 * Enables response truncation. Please read
84 * the class javadoc for an explanation of how allowTruncate is used.
85 * @return {@code this} (for chaining)
87 public FetchOptions
allowTruncate() {
88 this.allowTruncate
= true;
93 * Disables response truncation. Please read
94 * the class javadoc for an explanation of how allowTruncate is used.
95 * @return {@code this} (for chaining)
97 public FetchOptions
disallowTruncate() {
98 this.allowTruncate
= false;
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)
107 public FetchOptions
followRedirects() {
108 this.followRedirects
= true;
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)
118 public FetchOptions
validateCertificate() {
119 this.certificateValidationBehavior
= CertificateValidationBehavior
.VALIDATE
;
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)
129 public FetchOptions
doNotValidateCertificate() {
130 this.certificateValidationBehavior
= CertificateValidationBehavior
.DO_NOT_VALIDATE
;
135 * Sets the deadline, in seconds, for the fetch request.
136 * @throws IllegalArgumentException if deadline is not positive
137 * @return {@code this} (for chaining)
139 public FetchOptions
setDeadline(Double deadline
) {
140 if (deadline
!= null && deadline
<= 0.0) {
141 throw new IllegalArgumentException("Deadline must be > 0, got " + deadline
);
143 this.deadline
= deadline
;
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)
152 public FetchOptions
doNotFollowRedirects() {
153 this.followRedirects
= false;
157 boolean getAllowTruncate() {
158 return allowTruncate
;
161 boolean getFollowRedirects() {
162 return followRedirects
;
165 CertificateValidationBehavior
getCertificateValidationBehavior() {
166 return certificateValidationBehavior
;
169 Double
getDeadline() {
174 * Contains static creation methods for {@link FetchOptions}.
176 public static final class Builder
{
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.
185 public static FetchOptions
allowTruncate() {
186 return withDefaults().allowTruncate();
190 * Create a {@link FetchOptions} that disallows truncation of the response.
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.
197 public static FetchOptions
disallowTruncate() {
198 return withDefaults().disallowTruncate();
202 * Create a {@link FetchOptions} that follows redirects.
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.
209 public static FetchOptions
followRedirects() {
210 return withDefaults().followRedirects();
214 * Create a {@link FetchOptions} that does not follow redirects.
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.
221 public static FetchOptions
doNotFollowRedirects() {
222 return withDefaults().doNotFollowRedirects();
226 * Create a {@link FetchOptions} that performs SSL certificate validation.
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.
234 public static FetchOptions
validateCertificate() {
235 return withDefaults().validateCertificate();
239 * Create a {@link FetchOptions} that does not perform SSL certificate
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.
248 public static FetchOptions
doNotValidateCertificate() {
249 return withDefaults().doNotValidateCertificate();
253 * Create a {@link FetchOptions} with the specified deadline.
255 * <code>FetchOptions.withDefaults().setDeadline(deadline);</code>.
256 * @return The newly created FetchOptions instance.
258 public static FetchOptions
withDeadline(double deadline
) {
259 return withDefaults().setDeadline(deadline
);
263 * Helper method for creating a {@link FetchOptions}
264 * instance with default values.
266 * @see FetchOptions#DEFAULT_ALLOW_TRUNCATE
267 * @see FetchOptions#DEFAULT_FOLLOW_REDIRECTS
268 * @see FetchOptions#DEFAULT_DEADLINE
270 public static FetchOptions
withDefaults() {
271 return new FetchOptions();