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 decompressionEnabled;
62  
63      RequestConfig(
64              final boolean expectContinueEnabled,
65              final HttpHost proxy,
66              final InetAddress localAddress,
67              final boolean staleConnectionCheckEnabled,
68              final String cookieSpec,
69              final boolean redirectsEnabled,
70              final boolean relativeRedirectsAllowed,
71              final boolean circularRedirectsAllowed,
72              final int maxRedirects,
73              final boolean authenticationEnabled,
74              final Collection<String> targetPreferredAuthSchemes,
75              final Collection<String> proxyPreferredAuthSchemes,
76              final int connectionRequestTimeout,
77              final int connectTimeout,
78              final int socketTimeout,
79              final boolean decompressionEnabled) {
80          super();
81          this.expectContinueEnabled = expectContinueEnabled;
82          this.proxy = proxy;
83          this.localAddress = localAddress;
84          this.staleConnectionCheckEnabled = staleConnectionCheckEnabled;
85          this.cookieSpec = cookieSpec;
86          this.redirectsEnabled = redirectsEnabled;
87          this.relativeRedirectsAllowed = relativeRedirectsAllowed;
88          this.circularRedirectsAllowed = circularRedirectsAllowed;
89          this.maxRedirects = maxRedirects;
90          this.authenticationEnabled = authenticationEnabled;
91          this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
92          this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
93          this.connectionRequestTimeout = connectionRequestTimeout;
94          this.connectTimeout = connectTimeout;
95          this.socketTimeout = socketTimeout;
96          this.decompressionEnabled = decompressionEnabled;
97      }
98  
99      /**
100      * Determines whether the 'Expect: 100-Continue' handshake is enabled
101      * for entity enclosing methods. The purpose of the 'Expect: 100-Continue'
102      * handshake is to allow a client that is sending a request message with
103      * a request body to determine if the origin server is willing to
104      * accept the request (based on the request headers) before the client
105      * sends the request body.
106      * <p>
107      * The use of the 'Expect: 100-continue' handshake can result in
108      * a noticeable performance improvement for entity enclosing requests
109      * (such as POST and PUT) that require the target server's
110      * authentication.
111      * </p>
112      * <p>
113      * 'Expect: 100-continue' handshake should be used with caution, as it
114      * may cause problems with HTTP servers and proxies that do not support
115      * HTTP/1.1 protocol.
116      * </p>
117      * <p>
118      * Default: {@code false}
119      * </p>
120      */
121     public boolean isExpectContinueEnabled() {
122         return expectContinueEnabled;
123     }
124 
125     /**
126      * Returns HTTP proxy to be used for request execution.
127      * <p>
128      * Default: {@code null}
129      * </p>
130      */
131     public HttpHost getProxy() {
132         return proxy;
133     }
134 
135     /**
136      * Returns local address to be used for request execution.
137      * <p>
138      * On machines with multiple network interfaces, this parameter
139      * can be used to select the network interface from which the
140      * connection originates.
141      * </p>
142      * <p>
143      * Default: {@code null}
144      * </p>
145      */
146     public InetAddress getLocalAddress() {
147         return localAddress;
148     }
149 
150     /**
151      * Determines whether stale connection check is to be used. The stale
152      * connection check can cause up to 30 millisecond overhead per request and
153      * should be used only when appropriate. For performance critical
154      * operations this check should be disabled.
155      * <p>
156      * Default: {@code false} since 4.4
157      * </p>
158      *
159      * @deprecated (4.4) Use {@link
160      *   org.apache.http.impl.conn.PoolingHttpClientConnectionManager#getValidateAfterInactivity()}
161      */
162     @Deprecated
163     public boolean isStaleConnectionCheckEnabled() {
164         return staleConnectionCheckEnabled;
165     }
166 
167     /**
168      * Determines the name of the cookie specification to be used for HTTP state
169      * management.
170      * <p>
171      * Default: {@code null}
172      * </p>
173      */
174     public String getCookieSpec() {
175         return cookieSpec;
176     }
177 
178     /**
179      * Determines whether redirects should be handled automatically.
180      * <p>
181      * Default: {@code true}
182      * </p>
183      */
184     public boolean isRedirectsEnabled() {
185         return redirectsEnabled;
186     }
187 
188     /**
189      * Determines whether relative redirects should be rejected. HTTP specification
190      * requires the location value be an absolute URI.
191      * <p>
192      * Default: {@code true}
193      * </p>
194      */
195     public boolean isRelativeRedirectsAllowed() {
196         return relativeRedirectsAllowed;
197     }
198 
199     /**
200      * Determines whether circular redirects (redirects to the same location) should
201      * be allowed. The HTTP spec is not sufficiently clear whether circular redirects
202      * are permitted, therefore optionally they can be enabled
203      * <p>
204      * Default: {@code false}
205      * </p>
206      */
207     public boolean isCircularRedirectsAllowed() {
208         return circularRedirectsAllowed;
209     }
210 
211     /**
212      * Returns the maximum number of redirects to be followed. The limit on number
213      * of redirects is intended to prevent infinite loops.
214      * <p>
215      * Default: {@code 50}
216      * </p>
217      */
218     public int getMaxRedirects() {
219         return maxRedirects;
220     }
221 
222     /**
223      * Determines whether authentication should be handled automatically.
224      * <p>
225      * Default: {@code true}
226      * </p>
227      */
228     public boolean isAuthenticationEnabled() {
229         return authenticationEnabled;
230     }
231 
232     /**
233      * Determines the order of preference for supported authentication schemes
234      * when authenticating with the target host.
235      * <p>
236      * Default: {@code null}
237      * </p>
238      */
239     public Collection<String> getTargetPreferredAuthSchemes() {
240         return targetPreferredAuthSchemes;
241     }
242 
243     /**
244      * Determines the order of preference for supported authentication schemes
245      * when authenticating with the proxy host.
246      * <p>
247      * Default: {@code null}
248      * </p>
249      */
250     public Collection<String> getProxyPreferredAuthSchemes() {
251         return proxyPreferredAuthSchemes;
252     }
253 
254     /**
255      * Returns the timeout in milliseconds used when requesting a connection
256      * from the connection manager. A timeout value of zero is interpreted
257      * as an infinite timeout.
258      * <p>
259      * A timeout value of zero is interpreted as an infinite timeout.
260      * A negative value is interpreted as undefined (system default).
261      * </p>
262      * <p>
263      * Default: {@code -1}
264      * </p>
265      */
266     public int getConnectionRequestTimeout() {
267         return connectionRequestTimeout;
268     }
269 
270     /**
271      * Determines the timeout in milliseconds until a connection is established.
272      * A timeout value of zero is interpreted as an infinite timeout.
273      * <p>
274      * A timeout value of zero is interpreted as an infinite timeout.
275      * A negative value is interpreted as undefined (system default).
276      * </p>
277      * <p>
278      * Default: {@code -1}
279      * </p>
280      */
281     public int getConnectTimeout() {
282         return connectTimeout;
283     }
284 
285     /**
286      * Defines the socket timeout ({@code SO_TIMEOUT}) in milliseconds,
287      * which is the timeout for waiting for data  or, put differently,
288      * a maximum period inactivity between two consecutive data packets).
289      * <p>
290      * A timeout value of zero is interpreted as an infinite timeout.
291      * A negative value is interpreted as undefined (system default).
292      * </p>
293      * <p>
294      * Default: {@code -1}
295      * </p>
296      */
297     public int getSocketTimeout() {
298         return socketTimeout;
299     }
300 
301     /**
302      * Determines whether compressed entities should be decompressed automatically.
303      * <p>
304      * Default: {@code true}
305      * </p>
306      *
307      * @since 4.4
308      */
309     public boolean isDecompressionEnabled() {
310         return decompressionEnabled;
311     }
312 
313     @Override
314     protected RequestConfig clone() throws CloneNotSupportedException {
315         return (RequestConfig) super.clone();
316     }
317 
318     @Override
319     public String toString() {
320         final StringBuilder builder = new StringBuilder();
321         builder.append("[");
322         builder.append("expectContinueEnabled=").append(expectContinueEnabled);
323         builder.append(", proxy=").append(proxy);
324         builder.append(", localAddress=").append(localAddress);
325         builder.append(", cookieSpec=").append(cookieSpec);
326         builder.append(", redirectsEnabled=").append(redirectsEnabled);
327         builder.append(", relativeRedirectsAllowed=").append(relativeRedirectsAllowed);
328         builder.append(", maxRedirects=").append(maxRedirects);
329         builder.append(", circularRedirectsAllowed=").append(circularRedirectsAllowed);
330         builder.append(", authenticationEnabled=").append(authenticationEnabled);
331         builder.append(", targetPreferredAuthSchemes=").append(targetPreferredAuthSchemes);
332         builder.append(", proxyPreferredAuthSchemes=").append(proxyPreferredAuthSchemes);
333         builder.append(", connectionRequestTimeout=").append(connectionRequestTimeout);
334         builder.append(", connectTimeout=").append(connectTimeout);
335         builder.append(", socketTimeout=").append(socketTimeout);
336         builder.append(", decompressionEnabled=").append(decompressionEnabled);
337         builder.append("]");
338         return builder.toString();
339     }
340 
341     public static RequestConfig.Builder custom() {
342         return new Builder();
343     }
344 
345     @SuppressWarnings("deprecation")
346     public static RequestConfig.Builder copy(final RequestConfig config) {
347         return new Builder()
348             .setExpectContinueEnabled(config.isExpectContinueEnabled())
349             .setProxy(config.getProxy())
350             .setLocalAddress(config.getLocalAddress())
351             .setStaleConnectionCheckEnabled(config.isStaleConnectionCheckEnabled())
352             .setCookieSpec(config.getCookieSpec())
353             .setRedirectsEnabled(config.isRedirectsEnabled())
354             .setRelativeRedirectsAllowed(config.isRelativeRedirectsAllowed())
355             .setCircularRedirectsAllowed(config.isCircularRedirectsAllowed())
356             .setMaxRedirects(config.getMaxRedirects())
357             .setAuthenticationEnabled(config.isAuthenticationEnabled())
358             .setTargetPreferredAuthSchemes(config.getTargetPreferredAuthSchemes())
359             .setProxyPreferredAuthSchemes(config.getProxyPreferredAuthSchemes())
360             .setConnectionRequestTimeout(config.getConnectionRequestTimeout())
361             .setConnectTimeout(config.getConnectTimeout())
362             .setSocketTimeout(config.getSocketTimeout())
363             .setDecompressionEnabled(config.isDecompressionEnabled());
364     }
365 
366     public static class Builder {
367 
368         private boolean expectContinueEnabled;
369         private HttpHost proxy;
370         private InetAddress localAddress;
371         private boolean staleConnectionCheckEnabled;
372         private String cookieSpec;
373         private boolean redirectsEnabled;
374         private boolean relativeRedirectsAllowed;
375         private boolean circularRedirectsAllowed;
376         private int maxRedirects;
377         private boolean authenticationEnabled;
378         private Collection<String> targetPreferredAuthSchemes;
379         private Collection<String> proxyPreferredAuthSchemes;
380         private int connectionRequestTimeout;
381         private int connectTimeout;
382         private int socketTimeout;
383         private boolean decompressionEnabled;
384 
385         Builder() {
386             super();
387             this.staleConnectionCheckEnabled = false;
388             this.redirectsEnabled = true;
389             this.maxRedirects = 50;
390             this.relativeRedirectsAllowed = true;
391             this.authenticationEnabled = true;
392             this.connectionRequestTimeout = -1;
393             this.connectTimeout = -1;
394             this.socketTimeout = -1;
395             this.decompressionEnabled = true;
396         }
397 
398         public Builder setExpectContinueEnabled(final boolean expectContinueEnabled) {
399             this.expectContinueEnabled = expectContinueEnabled;
400             return this;
401         }
402 
403         public Builder setProxy(final HttpHost proxy) {
404             this.proxy = proxy;
405             return this;
406         }
407 
408         public Builder setLocalAddress(final InetAddress localAddress) {
409             this.localAddress = localAddress;
410             return this;
411         }
412 
413         /**
414          * @deprecated (4.4) Use {@link
415          *   org.apache.http.impl.conn.PoolingHttpClientConnectionManager#setValidateAfterInactivity(int)}
416          */
417         @Deprecated
418         public Builder setStaleConnectionCheckEnabled(final boolean staleConnectionCheckEnabled) {
419             this.staleConnectionCheckEnabled = staleConnectionCheckEnabled;
420             return this;
421         }
422 
423         public Builder setCookieSpec(final String cookieSpec) {
424             this.cookieSpec = cookieSpec;
425             return this;
426         }
427 
428         public Builder setRedirectsEnabled(final boolean redirectsEnabled) {
429             this.redirectsEnabled = redirectsEnabled;
430             return this;
431         }
432 
433         public Builder setRelativeRedirectsAllowed(final boolean relativeRedirectsAllowed) {
434             this.relativeRedirectsAllowed = relativeRedirectsAllowed;
435             return this;
436         }
437 
438         public Builder setCircularRedirectsAllowed(final boolean circularRedirectsAllowed) {
439             this.circularRedirectsAllowed = circularRedirectsAllowed;
440             return this;
441         }
442 
443         public Builder setMaxRedirects(final int maxRedirects) {
444             this.maxRedirects = maxRedirects;
445             return this;
446         }
447 
448         public Builder setAuthenticationEnabled(final boolean authenticationEnabled) {
449             this.authenticationEnabled = authenticationEnabled;
450             return this;
451         }
452 
453         public Builder setTargetPreferredAuthSchemes(final Collection<String> targetPreferredAuthSchemes) {
454             this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
455             return this;
456         }
457 
458         public Builder setProxyPreferredAuthSchemes(final Collection<String> proxyPreferredAuthSchemes) {
459             this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
460             return this;
461         }
462 
463         public Builder setConnectionRequestTimeout(final int connectionRequestTimeout) {
464             this.connectionRequestTimeout = connectionRequestTimeout;
465             return this;
466         }
467 
468         public Builder setConnectTimeout(final int connectTimeout) {
469             this.connectTimeout = connectTimeout;
470             return this;
471         }
472 
473         public Builder setSocketTimeout(final int socketTimeout) {
474             this.socketTimeout = socketTimeout;
475             return this;
476         }
477 
478         public Builder setDecompressionEnabled(final boolean decompressionEnabled) {
479             this.decompressionEnabled = decompressionEnabled;
480             return this;
481         }
482 
483         public RequestConfig build() {
484             return new RequestConfig(
485                     expectContinueEnabled,
486                     proxy,
487                     localAddress,
488                     staleConnectionCheckEnabled,
489                     cookieSpec,
490                     redirectsEnabled,
491                     relativeRedirectsAllowed,
492                     circularRedirectsAllowed,
493                     maxRedirects,
494                     authenticationEnabled,
495                     targetPreferredAuthSchemes,
496                     proxyPreferredAuthSchemes,
497                     connectionRequestTimeout,
498                     connectTimeout,
499                     socketTimeout,
500                     decompressionEnabled);
501         }
502 
503     }
504 
505 }