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