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(", expectContinueEnabled=").append(expectContinueEnabled);
322         builder.append(", proxy=").append(proxy);
323         builder.append(", localAddress=").append(localAddress);
324         builder.append(", cookieSpec=").append(cookieSpec);
325         builder.append(", redirectsEnabled=").append(redirectsEnabled);
326         builder.append(", relativeRedirectsAllowed=").append(relativeRedirectsAllowed);
327         builder.append(", maxRedirects=").append(maxRedirects);
328         builder.append(", circularRedirectsAllowed=").append(circularRedirectsAllowed);
329         builder.append(", authenticationEnabled=").append(authenticationEnabled);
330         builder.append(", targetPreferredAuthSchemes=").append(targetPreferredAuthSchemes);
331         builder.append(", proxyPreferredAuthSchemes=").append(proxyPreferredAuthSchemes);
332         builder.append(", connectionRequestTimeout=").append(connectionRequestTimeout);
333         builder.append(", connectTimeout=").append(connectTimeout);
334         builder.append(", socketTimeout=").append(socketTimeout);
335         builder.append(", decompressionEnabled=").append(decompressionEnabled);
336         builder.append("]");
337         return builder.toString();
338     }
339 
340     public static RequestConfig.Builder custom() {
341         return new Builder();
342     }
343 
344     @SuppressWarnings("deprecation")
345     public static RequestConfig.Builder copy(final RequestConfig config) {
346         return new Builder()
347             .setExpectContinueEnabled(config.isExpectContinueEnabled())
348             .setProxy(config.getProxy())
349             .setLocalAddress(config.getLocalAddress())
350             .setStaleConnectionCheckEnabled(config.isStaleConnectionCheckEnabled())
351             .setCookieSpec(config.getCookieSpec())
352             .setRedirectsEnabled(config.isRedirectsEnabled())
353             .setRelativeRedirectsAllowed(config.isRelativeRedirectsAllowed())
354             .setCircularRedirectsAllowed(config.isCircularRedirectsAllowed())
355             .setMaxRedirects(config.getMaxRedirects())
356             .setAuthenticationEnabled(config.isAuthenticationEnabled())
357             .setTargetPreferredAuthSchemes(config.getTargetPreferredAuthSchemes())
358             .setProxyPreferredAuthSchemes(config.getProxyPreferredAuthSchemes())
359             .setConnectionRequestTimeout(config.getConnectionRequestTimeout())
360             .setConnectTimeout(config.getConnectTimeout())
361             .setSocketTimeout(config.getSocketTimeout())
362             .setDecompressionEnabled(config.isDecompressionEnabled());
363     }
364 
365     public static class Builder {
366 
367         private boolean expectContinueEnabled;
368         private HttpHost proxy;
369         private InetAddress localAddress;
370         private boolean staleConnectionCheckEnabled;
371         private String cookieSpec;
372         private boolean redirectsEnabled;
373         private boolean relativeRedirectsAllowed;
374         private boolean circularRedirectsAllowed;
375         private int maxRedirects;
376         private boolean authenticationEnabled;
377         private Collection<String> targetPreferredAuthSchemes;
378         private Collection<String> proxyPreferredAuthSchemes;
379         private int connectionRequestTimeout;
380         private int connectTimeout;
381         private int socketTimeout;
382         private boolean decompressionEnabled;
383 
384         Builder() {
385             super();
386             this.staleConnectionCheckEnabled = false;
387             this.redirectsEnabled = true;
388             this.maxRedirects = 50;
389             this.relativeRedirectsAllowed = true;
390             this.authenticationEnabled = true;
391             this.connectionRequestTimeout = -1;
392             this.connectTimeout = -1;
393             this.socketTimeout = -1;
394             this.decompressionEnabled = true;
395         }
396 
397         public Builder setExpectContinueEnabled(final boolean expectContinueEnabled) {
398             this.expectContinueEnabled = expectContinueEnabled;
399             return this;
400         }
401 
402         public Builder setProxy(final HttpHost proxy) {
403             this.proxy = proxy;
404             return this;
405         }
406 
407         public Builder setLocalAddress(final InetAddress localAddress) {
408             this.localAddress = localAddress;
409             return this;
410         }
411 
412         /**
413          * @deprecated (4.4) Use {@link
414          *   org.apache.http.impl.conn.PoolingHttpClientConnectionManager#setValidateAfterInactivity(int)}
415          */
416         @Deprecated
417         public Builder setStaleConnectionCheckEnabled(final boolean staleConnectionCheckEnabled) {
418             this.staleConnectionCheckEnabled = staleConnectionCheckEnabled;
419             return this;
420         }
421 
422         public Builder setCookieSpec(final String cookieSpec) {
423             this.cookieSpec = cookieSpec;
424             return this;
425         }
426 
427         public Builder setRedirectsEnabled(final boolean redirectsEnabled) {
428             this.redirectsEnabled = redirectsEnabled;
429             return this;
430         }
431 
432         public Builder setRelativeRedirectsAllowed(final boolean relativeRedirectsAllowed) {
433             this.relativeRedirectsAllowed = relativeRedirectsAllowed;
434             return this;
435         }
436 
437         public Builder setCircularRedirectsAllowed(final boolean circularRedirectsAllowed) {
438             this.circularRedirectsAllowed = circularRedirectsAllowed;
439             return this;
440         }
441 
442         public Builder setMaxRedirects(final int maxRedirects) {
443             this.maxRedirects = maxRedirects;
444             return this;
445         }
446 
447         public Builder setAuthenticationEnabled(final boolean authenticationEnabled) {
448             this.authenticationEnabled = authenticationEnabled;
449             return this;
450         }
451 
452         public Builder setTargetPreferredAuthSchemes(final Collection<String> targetPreferredAuthSchemes) {
453             this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
454             return this;
455         }
456 
457         public Builder setProxyPreferredAuthSchemes(final Collection<String> proxyPreferredAuthSchemes) {
458             this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
459             return this;
460         }
461 
462         public Builder setConnectionRequestTimeout(final int connectionRequestTimeout) {
463             this.connectionRequestTimeout = connectionRequestTimeout;
464             return this;
465         }
466 
467         public Builder setConnectTimeout(final int connectTimeout) {
468             this.connectTimeout = connectTimeout;
469             return this;
470         }
471 
472         public Builder setSocketTimeout(final int socketTimeout) {
473             this.socketTimeout = socketTimeout;
474             return this;
475         }
476 
477         public Builder setDecompressionEnabled(final boolean decompressionEnabled) {
478             this.decompressionEnabled = decompressionEnabled;
479             return this;
480         }
481 
482         public RequestConfig build() {
483             return new RequestConfig(
484                     expectContinueEnabled,
485                     proxy,
486                     localAddress,
487                     staleConnectionCheckEnabled,
488                     cookieSpec,
489                     redirectsEnabled,
490                     relativeRedirectsAllowed,
491                     circularRedirectsAllowed,
492                     maxRedirects,
493                     authenticationEnabled,
494                     targetPreferredAuthSchemes,
495                     proxyPreferredAuthSchemes,
496                     connectionRequestTimeout,
497                     connectTimeout,
498                     socketTimeout,
499                     decompressionEnabled);
500         }
501 
502     }
503 
504 }