View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.client.config;
29  
30  import java.net.InetAddress;
31  import java.util.Collection;
32  
33  import org.apache.http.HttpHost;
34  import org.apache.http.annotation.Immutable;
35  
36  /**
37   *  Immutable class encapsulating request configuration items.
38   *  The default setting for stale connection checking changed
39   *  to false, and the feature was deprecated starting with version 4.4.
40   */
41  @Immutable
42  public class RequestConfig implements Cloneable {
43  
44      public static final RequestConfig DEFAULT = new Builder().build();
45  
46      private final boolean expectContinueEnabled;
47      private final HttpHost proxy;
48      private final InetAddress localAddress;
49      private final boolean staleConnectionCheckEnabled;
50      private final String cookieSpec;
51      private final boolean redirectsEnabled;
52      private final boolean relativeRedirectsAllowed;
53      private final boolean circularRedirectsAllowed;
54      private final int maxRedirects;
55      private final boolean authenticationEnabled;
56      private final Collection<String> targetPreferredAuthSchemes;
57      private final Collection<String> proxyPreferredAuthSchemes;
58      private final int connectionRequestTimeout;
59      private final int connectTimeout;
60      private final int socketTimeout;
61      private final boolean contentCompressionEnabled;
62  
63      /**
64       * Intended for CDI compatibility
65      */
66      protected RequestConfig() {
67          this(false, null, null, false, null, false, false, false, 0, false, null, null, 0, 0, 0, true);
68      }
69  
70      RequestConfig(
71              final boolean expectContinueEnabled,
72              final HttpHost proxy,
73              final InetAddress localAddress,
74              final boolean staleConnectionCheckEnabled,
75              final String cookieSpec,
76              final boolean redirectsEnabled,
77              final boolean relativeRedirectsAllowed,
78              final boolean circularRedirectsAllowed,
79              final int maxRedirects,
80              final boolean authenticationEnabled,
81              final Collection<String> targetPreferredAuthSchemes,
82              final Collection<String> proxyPreferredAuthSchemes,
83              final int connectionRequestTimeout,
84              final int connectTimeout,
85              final int socketTimeout,
86              final boolean contentCompressionEnabled) {
87          super();
88          this.expectContinueEnabled = expectContinueEnabled;
89          this.proxy = proxy;
90          this.localAddress = localAddress;
91          this.staleConnectionCheckEnabled = staleConnectionCheckEnabled;
92          this.cookieSpec = cookieSpec;
93          this.redirectsEnabled = redirectsEnabled;
94          this.relativeRedirectsAllowed = relativeRedirectsAllowed;
95          this.circularRedirectsAllowed = circularRedirectsAllowed;
96          this.maxRedirects = maxRedirects;
97          this.authenticationEnabled = authenticationEnabled;
98          this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
99          this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
100         this.connectionRequestTimeout = connectionRequestTimeout;
101         this.connectTimeout = connectTimeout;
102         this.socketTimeout = socketTimeout;
103         this.contentCompressionEnabled = contentCompressionEnabled;
104     }
105 
106     /**
107      * Determines whether the 'Expect: 100-Continue' handshake is enabled
108      * for entity enclosing methods. The purpose of the 'Expect: 100-Continue'
109      * handshake is to allow a client that is sending a request message with
110      * a request body to determine if the origin server is willing to
111      * accept the request (based on the request headers) before the client
112      * sends the request body.
113      * <p>
114      * The use of the 'Expect: 100-continue' handshake can result in
115      * a noticeable performance improvement for entity enclosing requests
116      * (such as POST and PUT) that require the target server's
117      * authentication.
118      * </p>
119      * <p>
120      * 'Expect: 100-continue' handshake should be used with caution, as it
121      * may cause problems with HTTP servers and proxies that do not support
122      * HTTP/1.1 protocol.
123      * </p>
124      * <p>
125      * Default: {@code false}
126      * </p>
127      */
128     public boolean isExpectContinueEnabled() {
129         return expectContinueEnabled;
130     }
131 
132     /**
133      * Returns HTTP proxy to be used for request execution.
134      * <p>
135      * Default: {@code null}
136      * </p>
137      */
138     public HttpHost getProxy() {
139         return proxy;
140     }
141 
142     /**
143      * Returns local address to be used for request execution.
144      * <p>
145      * On machines with multiple network interfaces, this parameter
146      * can be used to select the network interface from which the
147      * connection originates.
148      * </p>
149      * <p>
150      * Default: {@code null}
151      * </p>
152      */
153     public InetAddress getLocalAddress() {
154         return localAddress;
155     }
156 
157     /**
158      * Determines whether stale connection check is to be used. The stale
159      * connection check can cause up to 30 millisecond overhead per request and
160      * should be used only when appropriate. For performance critical
161      * operations this check should be disabled.
162      * <p>
163      * Default: {@code false} since 4.4
164      * </p>
165      *
166      * @deprecated (4.4) Use {@link
167      *   org.apache.http.impl.conn.PoolingHttpClientConnectionManager#getValidateAfterInactivity()}
168      */
169     @Deprecated
170     public boolean isStaleConnectionCheckEnabled() {
171         return staleConnectionCheckEnabled;
172     }
173 
174     /**
175      * Determines the name of the cookie specification to be used for HTTP state
176      * management.
177      * <p>
178      * Default: {@code null}
179      * </p>
180      */
181     public String getCookieSpec() {
182         return cookieSpec;
183     }
184 
185     /**
186      * Determines whether redirects should be handled automatically.
187      * <p>
188      * Default: {@code true}
189      * </p>
190      */
191     public boolean isRedirectsEnabled() {
192         return redirectsEnabled;
193     }
194 
195     /**
196      * Determines whether relative redirects should be rejected. HTTP specification
197      * requires the location value be an absolute URI.
198      * <p>
199      * Default: {@code true}
200      * </p>
201      */
202     public boolean isRelativeRedirectsAllowed() {
203         return relativeRedirectsAllowed;
204     }
205 
206     /**
207      * Determines whether circular redirects (redirects to the same location) should
208      * be allowed. The HTTP spec is not sufficiently clear whether circular redirects
209      * are permitted, therefore optionally they can be enabled
210      * <p>
211      * Default: {@code false}
212      * </p>
213      */
214     public boolean isCircularRedirectsAllowed() {
215         return circularRedirectsAllowed;
216     }
217 
218     /**
219      * Returns the maximum number of redirects to be followed. The limit on number
220      * of redirects is intended to prevent infinite loops.
221      * <p>
222      * Default: {@code 50}
223      * </p>
224      */
225     public int getMaxRedirects() {
226         return maxRedirects;
227     }
228 
229     /**
230      * Determines whether authentication should be handled automatically.
231      * <p>
232      * Default: {@code true}
233      * </p>
234      */
235     public boolean isAuthenticationEnabled() {
236         return authenticationEnabled;
237     }
238 
239     /**
240      * Determines the order of preference for supported authentication schemes
241      * when authenticating with the target host.
242      * <p>
243      * Default: {@code null}
244      * </p>
245      */
246     public Collection<String> getTargetPreferredAuthSchemes() {
247         return targetPreferredAuthSchemes;
248     }
249 
250     /**
251      * Determines the order of preference for supported authentication schemes
252      * when authenticating with the proxy host.
253      * <p>
254      * Default: {@code null}
255      * </p>
256      */
257     public Collection<String> getProxyPreferredAuthSchemes() {
258         return proxyPreferredAuthSchemes;
259     }
260 
261     /**
262      * Returns the timeout in milliseconds used when requesting a connection
263      * from the connection manager. A timeout value of zero is interpreted
264      * as an infinite timeout.
265      * <p>
266      * A timeout value of zero is interpreted as an infinite timeout.
267      * A negative value is interpreted as undefined (system default).
268      * </p>
269      * <p>
270      * Default: {@code -1}
271      * </p>
272      */
273     public int getConnectionRequestTimeout() {
274         return connectionRequestTimeout;
275     }
276 
277     /**
278      * Determines the timeout in milliseconds until a connection is established.
279      * A timeout value of zero is interpreted as an infinite timeout.
280      * <p>
281      * A timeout value of zero is interpreted as an infinite timeout.
282      * A negative value is interpreted as undefined (system default).
283      * </p>
284      * <p>
285      * Default: {@code -1}
286      * </p>
287      */
288     public int getConnectTimeout() {
289         return connectTimeout;
290     }
291 
292     /**
293      * Defines the socket timeout ({@code SO_TIMEOUT}) in milliseconds,
294      * which is the timeout for waiting for data  or, put differently,
295      * a maximum period inactivity between two consecutive data packets).
296      * <p>
297      * A timeout value of zero is interpreted as an infinite timeout.
298      * A negative value is interpreted as undefined (system default).
299      * </p>
300      * <p>
301      * Default: {@code -1}
302      * </p>
303      */
304     public int getSocketTimeout() {
305         return socketTimeout;
306     }
307 
308     /**
309      * Determines whether compressed entities should be decompressed automatically.
310      * <p>
311      * Default: {@code true}
312      * </p>
313      *
314      * @since 4.4
315      * @deprecated (4.5) Use {@link #isContentCompressionEnabled()}
316      */
317     @Deprecated
318     public boolean isDecompressionEnabled() {
319         return contentCompressionEnabled;
320     }
321 
322     /**
323      * Determines whether the target server is requested to compress content.
324      * <p>
325      * Default: {@code true}
326      * </p>
327      *
328      * @since 4.5
329      */
330     public boolean isContentCompressionEnabled() {
331         return contentCompressionEnabled;
332     }
333 
334     @Override
335     protected RequestConfig clone() throws CloneNotSupportedException {
336         return (RequestConfig) super.clone();
337     }
338 
339     @Override
340     public String toString() {
341         final StringBuilder builder = new StringBuilder();
342         builder.append("[");
343         builder.append("expectContinueEnabled=").append(expectContinueEnabled);
344         builder.append(", proxy=").append(proxy);
345         builder.append(", localAddress=").append(localAddress);
346         builder.append(", cookieSpec=").append(cookieSpec);
347         builder.append(", redirectsEnabled=").append(redirectsEnabled);
348         builder.append(", relativeRedirectsAllowed=").append(relativeRedirectsAllowed);
349         builder.append(", maxRedirects=").append(maxRedirects);
350         builder.append(", circularRedirectsAllowed=").append(circularRedirectsAllowed);
351         builder.append(", authenticationEnabled=").append(authenticationEnabled);
352         builder.append(", targetPreferredAuthSchemes=").append(targetPreferredAuthSchemes);
353         builder.append(", proxyPreferredAuthSchemes=").append(proxyPreferredAuthSchemes);
354         builder.append(", connectionRequestTimeout=").append(connectionRequestTimeout);
355         builder.append(", connectTimeout=").append(connectTimeout);
356         builder.append(", socketTimeout=").append(socketTimeout);
357         builder.append(", contentCompressionEnabled=").append(contentCompressionEnabled);
358         builder.append("]");
359         return builder.toString();
360     }
361 
362     public static RequestConfig.Builder custom() {
363         return new Builder();
364     }
365 
366     @SuppressWarnings("deprecation")
367     public static RequestConfig.Builder copy(final RequestConfig config) {
368         return new Builder()
369             .setExpectContinueEnabled(config.isExpectContinueEnabled())
370             .setProxy(config.getProxy())
371             .setLocalAddress(config.getLocalAddress())
372             .setStaleConnectionCheckEnabled(config.isStaleConnectionCheckEnabled())
373             .setCookieSpec(config.getCookieSpec())
374             .setRedirectsEnabled(config.isRedirectsEnabled())
375             .setRelativeRedirectsAllowed(config.isRelativeRedirectsAllowed())
376             .setCircularRedirectsAllowed(config.isCircularRedirectsAllowed())
377             .setMaxRedirects(config.getMaxRedirects())
378             .setAuthenticationEnabled(config.isAuthenticationEnabled())
379             .setTargetPreferredAuthSchemes(config.getTargetPreferredAuthSchemes())
380             .setProxyPreferredAuthSchemes(config.getProxyPreferredAuthSchemes())
381             .setConnectionRequestTimeout(config.getConnectionRequestTimeout())
382             .setConnectTimeout(config.getConnectTimeout())
383             .setSocketTimeout(config.getSocketTimeout())
384             .setDecompressionEnabled(config.isDecompressionEnabled())
385             .setContentCompressionEnabled(config.isContentCompressionEnabled());
386     }
387 
388     public static class Builder {
389 
390         private boolean expectContinueEnabled;
391         private HttpHost proxy;
392         private InetAddress localAddress;
393         private boolean staleConnectionCheckEnabled;
394         private String cookieSpec;
395         private boolean redirectsEnabled;
396         private boolean relativeRedirectsAllowed;
397         private boolean circularRedirectsAllowed;
398         private int maxRedirects;
399         private boolean authenticationEnabled;
400         private Collection<String> targetPreferredAuthSchemes;
401         private Collection<String> proxyPreferredAuthSchemes;
402         private int connectionRequestTimeout;
403         private int connectTimeout;
404         private int socketTimeout;
405         private boolean contentCompressionEnabled;
406 
407         Builder() {
408             super();
409             this.staleConnectionCheckEnabled = false;
410             this.redirectsEnabled = true;
411             this.maxRedirects = 50;
412             this.relativeRedirectsAllowed = true;
413             this.authenticationEnabled = true;
414             this.connectionRequestTimeout = -1;
415             this.connectTimeout = -1;
416             this.socketTimeout = -1;
417             this.contentCompressionEnabled = true;
418         }
419 
420         public Builder setExpectContinueEnabled(final boolean expectContinueEnabled) {
421             this.expectContinueEnabled = expectContinueEnabled;
422             return this;
423         }
424 
425         public Builder setProxy(final HttpHost proxy) {
426             this.proxy = proxy;
427             return this;
428         }
429 
430         public Builder setLocalAddress(final InetAddress localAddress) {
431             this.localAddress = localAddress;
432             return this;
433         }
434 
435         /**
436          * @deprecated (4.4) Use {@link
437          *   org.apache.http.impl.conn.PoolingHttpClientConnectionManager#setValidateAfterInactivity(int)}
438          */
439         @Deprecated
440         public Builder setStaleConnectionCheckEnabled(final boolean staleConnectionCheckEnabled) {
441             this.staleConnectionCheckEnabled = staleConnectionCheckEnabled;
442             return this;
443         }
444 
445         public Builder setCookieSpec(final String cookieSpec) {
446             this.cookieSpec = cookieSpec;
447             return this;
448         }
449 
450         public Builder setRedirectsEnabled(final boolean redirectsEnabled) {
451             this.redirectsEnabled = redirectsEnabled;
452             return this;
453         }
454 
455         public Builder setRelativeRedirectsAllowed(final boolean relativeRedirectsAllowed) {
456             this.relativeRedirectsAllowed = relativeRedirectsAllowed;
457             return this;
458         }
459 
460         public Builder setCircularRedirectsAllowed(final boolean circularRedirectsAllowed) {
461             this.circularRedirectsAllowed = circularRedirectsAllowed;
462             return this;
463         }
464 
465         public Builder setMaxRedirects(final int maxRedirects) {
466             this.maxRedirects = maxRedirects;
467             return this;
468         }
469 
470         public Builder setAuthenticationEnabled(final boolean authenticationEnabled) {
471             this.authenticationEnabled = authenticationEnabled;
472             return this;
473         }
474 
475         public Builder setTargetPreferredAuthSchemes(final Collection<String> targetPreferredAuthSchemes) {
476             this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
477             return this;
478         }
479 
480         public Builder setProxyPreferredAuthSchemes(final Collection<String> proxyPreferredAuthSchemes) {
481             this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
482             return this;
483         }
484 
485         public Builder setConnectionRequestTimeout(final int connectionRequestTimeout) {
486             this.connectionRequestTimeout = connectionRequestTimeout;
487             return this;
488         }
489 
490         public Builder setConnectTimeout(final int connectTimeout) {
491             this.connectTimeout = connectTimeout;
492             return this;
493         }
494 
495         public Builder setSocketTimeout(final int socketTimeout) {
496             this.socketTimeout = socketTimeout;
497             return this;
498         }
499 
500         /**
501          * @deprecated (4.5) Set {@link #setContentCompressionEnabled(boolean)} to {@code false} and
502          * add the {@code Accept-Encoding} request header.
503          */
504         @Deprecated
505         public Builder setDecompressionEnabled(final boolean decompressionEnabled) {
506             this.contentCompressionEnabled = decompressionEnabled;
507             return this;
508         }
509 
510         public Builder setContentCompressionEnabled(final boolean contentCompressionEnabled) {
511             this.contentCompressionEnabled = contentCompressionEnabled;
512             return this;
513         }
514 
515         public RequestConfig build() {
516             return new RequestConfig(
517                     expectContinueEnabled,
518                     proxy,
519                     localAddress,
520                     staleConnectionCheckEnabled,
521                     cookieSpec,
522                     redirectsEnabled,
523                     relativeRedirectsAllowed,
524                     circularRedirectsAllowed,
525                     maxRedirects,
526                     authenticationEnabled,
527                     targetPreferredAuthSchemes,
528                     proxyPreferredAuthSchemes,
529                     connectionRequestTimeout,
530                     connectTimeout,
531                     socketTimeout,
532                     contentCompressionEnabled);
533         }
534 
535     }
536 
537 }