View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.vfs2.provider.http4;
18  
19  import java.security.KeyStore;
20  import java.time.Duration;
21  
22  import org.apache.commons.vfs2.FileSystem;
23  import org.apache.commons.vfs2.FileSystemConfigBuilder;
24  import org.apache.commons.vfs2.FileSystemOptions;
25  import org.apache.commons.vfs2.UserAuthenticator;
26  import org.apache.http.HttpHost;
27  import org.apache.http.cookie.Cookie;
28  
29  /**
30   * Configuration options builder utility for http4 provider.
31   *
32   * @since 2.3
33   * @deprecated Use {@link org.apache.commons.vfs2.provider.http5}.
34   */
35  @Deprecated
36  public class Http4FileSystemConfigBuilder extends FileSystemConfigBuilder {
37  
38      /**
39       * Defines whether the HttpClient should follow redirections from the responses.
40       * <p>
41       * This parameter expects a value of type {@link Boolean}.
42       * </p>
43       */
44      protected static final String KEY_FOLLOW_REDIRECT = "followRedirect";
45  
46      private static final Http4FileSystemConfigBuilder BUILDER = new Http4FileSystemConfigBuilder();
47  
48      /**
49       * Defines the maximum number of connections allowed overall. This value only applies
50       * to the number of connections from a particular instance of HTTP connection manager.
51       * <p>
52       * This parameter expects a value of type {@link Integer}.
53       * </p>
54       */
55      private static final String MAX_TOTAL_CONNECTIONS = "http.connection-manager.max-total";
56  
57      /**
58       * Defines the maximum number of connections allowed per host configuration.
59       * These values only apply to the number of connections from a particular instance
60       * of HTTP connection manager.
61       */
62      private static final String MAX_HOST_CONNECTIONS = "http.connection-manager.max-per-host";
63  
64      /**
65       * Defines the connection timeout of an HTTP request.
66       * <p>
67       * This parameter expects a value of type {@link Integer}.
68       * </p>
69       */
70      private static final String CONNECTION_TIMEOUT = "http.connection.timeout";
71  
72      /**
73       * Defines the socket timeout of an HTTP request.
74       * <p>
75       * This parameter expects a value of type {@link Integer}.
76       * </p>
77       */
78      private static final String SO_TIMEOUT = "http.socket.timeout";
79  
80      /**
81       * Defines whether Keep-Alive option is used or not.
82       * <p>
83       * This parameter expects a value of type {@link Boolean}.
84       * </p>
85       */
86      private static final String KEEP_ALIVE = "http.keepAlive";
87  
88      /**
89       * Defines the keystore file path for SSL connections.
90       * <p>
91       * This parameter expects a value of type {@link String}.
92       * </p>
93       */
94      private static final String KEYSTORE_FILE = "http.keystoreFile";
95  
96      /**
97       * Defines the keystore pass phrase for SSL connections.
98       * <p>
99       * This parameter expects a value of type {@link String}.
100      * </p>
101      */
102     private static final String KEYSTORE_PASS = "http.keystorePass";
103 
104     /**
105      * Defines the keystore type for the underlying HttpClient.
106      */
107     private static final String KEYSTORE_TYPE = "http.keyStoreType";
108 
109     /**
110      * Defines whether the host name should be verified or not in SSL connections.
111      * <p>
112      * This parameter expects a value of type {@link Boolean}.
113      * </p>
114      */
115     private static final String HOSTNAME_VERIFICATION_ENABLED = "http.hostname-verification.enabled";
116 
117     /**
118      * Defines the User-Agent request header string of the underlying HttpClient.
119      * <p>
120      * This parameter expects a value of type {@link String}.
121      * </p>
122      */
123     private static final String KEY_USER_AGENT = "userAgent";
124 
125     /**
126      * Defines whether the preemptive authentication should be enabled or not.
127      * <p>
128      * This parameter expects a value of type {@link Boolean}.
129      * </p>
130      */
131     private static final String KEY_PREEMPTIVE_AUTHENTICATION = "preemptiveAuth";
132 
133     /**
134      * The default value for {@link #MAX_TOTAL_CONNECTIONS} configuration.
135      */
136     private static final int DEFAULT_MAX_CONNECTIONS = 50;
137 
138     /**
139      * The default value for {@link #MAX_HOST_CONNECTIONS} configuration.
140      */
141     private static final int DEFAULT_MAX_HOST_CONNECTIONS = 5;
142 
143     /**
144      * The default value for {@link #CONNECTION_TIMEOUT} configuration.
145      */
146     private static final Duration DEFAULT_CONNECTION_TIMEOUT = Duration.ZERO;
147 
148     /**
149      * The default value for {@link #SO_TIMEOUT} configuration.
150      */
151     private static final Duration DEFAULT_SO_TIMEOUT = Duration.ZERO;
152 
153     /**
154      * The default value for {@link #KEEP_ALIVE} configuration.
155      */
156     private static final boolean DEFAULT_KEEP_ALIVE = true;
157 
158     /**
159      * The default value for {@link #KEY_FOLLOW_REDIRECT} configuration.
160      */
161     private static final boolean DEFAULT_FOLLOW_REDIRECT = true;
162 
163     /**
164      * The default value for {@link #KEY_USER_AGENT} configuration.
165      */
166     private static final String DEFAULT_USER_AGENT = "Jakarta-Commons-VFS";
167 
168     /**
169      * The default value for {@link #HOSTNAME_VERIFICATION_ENABLED} configuration.
170      */
171     private static final boolean DEFAULT_HOSTNAME_VERIFICATION_ENABLED = true;
172 
173     /**
174      * Defines http scheme for proxy host
175      *<p>
176      *This parameter expects a value of type {@link String}.
177      *</p>
178      */
179     private static final String PROXY_SCHEME = "proxyScheme";
180 
181     /**
182      * Gets the singleton builder.
183      *
184      * @return the singleton builder.
185      */
186     public static Http4FileSystemConfigBuilder getInstance() {
187         return BUILDER;
188     }
189 
190     private Http4FileSystemConfigBuilder() {
191         super("http.");
192     }
193 
194     /**
195      * Constructs an {@code Http4FileSystemConfigBuilder}.
196      *
197      * @param prefix String for properties of this file system.
198      */
199     protected Http4FileSystemConfigBuilder(final String prefix) {
200         super(prefix);
201     }
202 
203     @Override
204     protected Class<? extends FileSystem> getConfigClass() {
205         return Http4FileSystem.class;
206     }
207 
208     /**
209      * Gets the connection timeout.
210      *
211      * @param opts The FileSystem options.
212      * @return The connection timeout.
213      * @deprecated Use {@link #getConnectionTimeoutDuration(FileSystemOptions)}.
214      */
215     @Deprecated
216     public int getConnectionTimeout(final FileSystemOptions opts) {
217         return getDurationInteger(opts, CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
218     }
219 
220     /**
221     /**
222      * Gets the connection timeout.
223      *
224      * @param opts The FileSystem options.
225      * @return The connection timeout.
226      * @since 2.8.0
227      */
228     public Duration getConnectionTimeoutDuration(final FileSystemOptions opts) {
229         return getDuration(opts, CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
230     }
231 
232     /**
233      * Gets the cookies to add to the request.
234      *
235      * @param opts The FileSystem options.
236      * @return the Cookie array.
237      */
238     public Cookie[] getCookies(final FileSystemOptions opts) {
239         return getParam(opts, "cookies");
240     }
241 
242     /**
243      * Gets whether to follow redirects for the connection.
244      *
245      * @param opts The FileSystem options.
246      * @return {@code true} to follow redirects, {@code false} not to.
247      * @see #setFollowRedirect
248      */
249     public boolean getFollowRedirect(final FileSystemOptions opts) {
250         return getBoolean(opts, KEY_FOLLOW_REDIRECT, DEFAULT_FOLLOW_REDIRECT);
251     }
252 
253     /**
254      * Gets keystore file path to be used in SSL connections.
255      * @param opts the file system options to modify
256      * @return keystore file path to be used in SSL connections
257      */
258     public String getKeyStoreFile(final FileSystemOptions opts) {
259         return getParam(opts, KEYSTORE_FILE);
260     }
261     /**
262      * Gets keystore pass phrase for SSL connections.
263      * @param opts the file system options to modify
264      * @return keystore pass phrase for SSL connections
265      */
266     String getKeyStorePass(final FileSystemOptions opts) {
267         return getParam(opts, KEYSTORE_PASS);
268     }
269 
270     /**
271      * Gets keystore type for SSL connections.
272      * @param opts the file system options to modify
273      * @return keystore type for SSL connections
274      * @since 2.7.0
275      */
276     public String getKeyStoreType(final FileSystemOptions opts) {
277         return getString(opts, KEYSTORE_TYPE, KeyStore.getDefaultType());
278     }
279 
280     /**
281      * Gets the maximum number of connections allowed per host.
282      *
283      * @param opts The FileSystemOptions.
284      * @return The maximum number of connections allowed per host.
285      */
286     public int getMaxConnectionsPerHost(final FileSystemOptions opts) {
287         return getInteger(opts, MAX_HOST_CONNECTIONS, DEFAULT_MAX_HOST_CONNECTIONS);
288     }
289     /**
290      * Gets the maximum number of connections allowed.
291      *
292      * @param opts The FileSystemOptions.
293      * @return The maximum number of connections allowed.
294      */
295     public int getMaxTotalConnections(final FileSystemOptions opts) {
296         return getInteger(opts, MAX_TOTAL_CONNECTIONS, DEFAULT_MAX_CONNECTIONS);
297     }
298 
299     /**
300      * Gets the proxy authenticator where the system should get the credentials from.
301      *
302      * @param opts The FileSystem options.
303      * @return The UserAuthenticator.
304      */
305     public UserAuthenticator getProxyAuthenticator(final FileSystemOptions opts) {
306         return getParam(opts, "proxyAuthenticator");
307     }
308 
309     /**
310      * Gets the proxy to use for http connection. You have to set the ProxyPort too if you would like to have the proxy
311      * really used.
312      *
313      * @param opts The FileSystem options.
314      * @return proxyHost
315      * @see #setProxyPort
316      */
317     public String getProxyHost(final FileSystemOptions opts) {
318         return getString(opts, "proxyHost");
319     }
320 
321     /**
322      * Gets the proxy-port to use for http the connection. You have to set the ProxyHost too if you would like to have
323      * the proxy really used.
324      *
325      * @param opts The FileSystem options.
326      * @return proxyPort: the port number or 0 if it is not set
327      * @see #setProxyHost
328      */
329     public int getProxyPort(final FileSystemOptions opts) {
330         return getInteger(opts, "proxyPort", 0);
331     }
332 
333     /**
334      * Gets the proxy-scheme to use for http the connection. You have to set the ProxyHost too if you would like to have
335      * the proxy really used.
336      *
337      * @param opts The FileSystem options.
338      * @return proxyScheme: the http/https scheme of proxy server
339      * @see #setProxyHost
340      * @since 2.7.0
341      */
342     public String getProxyScheme(final FileSystemOptions opts) {
343         return getString(opts, PROXY_SCHEME, HttpHost.DEFAULT_SCHEME_NAME);
344     }
345 
346     /**
347      * Gets the socket timeout.
348      *
349      * @param opts The FileSystemOptions.
350      * @return The socket timeout.
351      * @deprecated Use {@link #getSoTimeoutDuration(FileSystemOptions)}.
352      */
353     @Deprecated
354     public int getSoTimeout(final FileSystemOptions opts) {
355         return getDurationInteger(opts, SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
356     }
357 
358     /**
359      * Gets the socket timeout.
360      *
361      * @param opts The FileSystemOptions.
362      * @return The socket timeout.
363      * @since 2.8.0
364      */
365     public Duration getSoTimeoutDuration(final FileSystemOptions opts) {
366         return getDuration(opts, SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
367     }
368 
369     /**
370      * Sets the charset used for url encoding.
371      *
372      * @param opts The FileSystem options.
373      * @return the charset name.
374      */
375     public String getUrlCharset(final FileSystemOptions opts) {
376         return getString(opts, "urlCharset");
377     }
378 
379     /**
380      * Gets the user agent string.
381      *
382      * @param opts the file system options to modify
383      * @return User provided User-Agent string, otherwise default of: Commons-VFS
384      */
385     public String getUserAgent(final FileSystemOptions opts) {
386         final String userAgent = getParam(opts, KEY_USER_AGENT);
387         return userAgent != null ? userAgent : DEFAULT_USER_AGENT;
388     }
389 
390     /**
391      * Determines if the hostname should be verified in SSL context.
392      *
393      * @param opts The FileSystemOptions.
394      * @return true if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
395      */
396     public boolean isHostnameVerificationEnabled(final FileSystemOptions opts) {
397         return getBoolean(opts, HOSTNAME_VERIFICATION_ENABLED, DEFAULT_HOSTNAME_VERIFICATION_ENABLED);
398     }
399 
400     /**
401      * Determines if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
402      *
403      * @param opts The FileSystemOptions.
404      * @return true if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
405      */
406     public boolean isKeepAlive(final FileSystemOptions opts) {
407         return getBoolean(opts, KEEP_ALIVE, DEFAULT_KEEP_ALIVE);
408     }
409 
410     /**
411      * Determines if the FileSystemOptions indicate that preemptive authentication is requested.
412      *
413      * @param opts The FileSystemOptions.
414      * @return true if preemptiveAuth is requested.
415      */
416     public boolean isPreemptiveAuth(final FileSystemOptions opts) {
417         return getBoolean(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.FALSE).booleanValue();
418     }
419 
420     /**
421      * Sets the connection timeout.
422      *
423      * @param opts The FileSystem options.
424      * @param connectionTimeout The connection timeout.
425      * @since 2.8.0
426      */
427     public void setConnectionTimeout(final FileSystemOptions opts, final Duration connectionTimeout) {
428         setParam(opts, CONNECTION_TIMEOUT, connectionTimeout);
429     }
430 
431     /**
432      * Sets the connection timeout.
433      *
434      * @param opts The FileSystem options.
435      * @param connectionTimeout The connection timeout.
436      * @deprecated Use {@link #setConnectionTimeout(FileSystemOptions, Duration)}.
437      */
438     @Deprecated
439     public void setConnectionTimeout(final FileSystemOptions opts, final int connectionTimeout) {
440         setConnectionTimeout(opts, Duration.ofMillis(connectionTimeout));
441     }
442 
443     /**
444      * The cookies to add to the request.
445      *
446      * @param opts The FileSystem options.
447      * @param cookies An array of Cookies.
448      */
449     public void setCookies(final FileSystemOptions opts, final Cookie[] cookies) {
450         setParam(opts, "cookies", cookies);
451     }
452 
453     /**
454      * Sets whether to follow redirects for the connection.
455      *
456      * @param opts The FileSystem options.
457      * @param redirect {@code true} to follow redirects, {@code false} not to.
458      * @see #setFollowRedirect
459      */
460     public void setFollowRedirect(final FileSystemOptions opts, final boolean redirect) {
461         setParam(opts, KEY_FOLLOW_REDIRECT, redirect);
462     }
463 
464     /**
465      * Sets if the hostname should be verified in SSL context.
466      *
467      * @param opts The FileSystemOptions.
468      * @param hostnameVerificationEnabled whether hostname should be verified
469      */
470     public void setHostnameVerificationEnabled(final FileSystemOptions opts, final boolean hostnameVerificationEnabled) {
471         setParam(opts, HOSTNAME_VERIFICATION_ENABLED, Boolean.valueOf(hostnameVerificationEnabled));
472     }
473 
474     /**
475      * Sets if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
476      *
477      * @param opts The FileSystemOptions.
478      * @param keepAlive whether the FileSystemOptions indicate that HTTP Keep-Alive is respected or not.
479      */
480     public void setKeepAlive(final FileSystemOptions opts, final boolean keepAlive) {
481         setParam(opts, KEEP_ALIVE, Boolean.valueOf(keepAlive));
482     }
483 
484     /**
485      * Sets keystore file path for SSL connections.
486      * @param opts the file system options to modify
487      * @param keyStoreFile keystore file path
488      */
489     public void setKeyStoreFile(final FileSystemOptions opts, final String keyStoreFile) {
490         setParam(opts, KEYSTORE_FILE, keyStoreFile);
491     }
492 
493     /**
494      * Sets keystore pass phrase for SSL connections.
495      * @param opts the file system options to modify
496      * @param keyStorePass keystore pass phrase for SSL connections
497      */
498     public void setKeyStorePass(final FileSystemOptions opts, final String keyStorePass) {
499         setParam(opts, KEYSTORE_PASS, keyStorePass);
500     }
501 
502     /**
503      * Sets keystore type for SSL connections.
504      * @param opts the file system options to modify
505      * @param keyStoreType keystore type for SSL connections
506      * @since 2.7.0
507      */
508     public void setKeyStoreType(final FileSystemOptions opts, final String keyStoreType) {
509         setParam(opts, KEYSTORE_TYPE, keyStoreType);
510     }
511 
512     /**
513      * Sets the maximum number of connections allowed to any host.
514      *
515      * @param opts The FileSystem options.
516      * @param maxHostConnections The maximum number of connections to a host.
517      */
518     public void setMaxConnectionsPerHost(final FileSystemOptions opts, final int maxHostConnections) {
519         setParam(opts, MAX_HOST_CONNECTIONS, Integer.valueOf(maxHostConnections));
520     }
521 
522     /**
523      * Sets the maximum number of connections allowed.
524      *
525      * @param opts The FileSystem options.
526      * @param maxTotalConnections The maximum number of connections.
527      */
528     public void setMaxTotalConnections(final FileSystemOptions opts, final int maxTotalConnections) {
529         setParam(opts, MAX_TOTAL_CONNECTIONS, Integer.valueOf(maxTotalConnections));
530     }
531 
532     /**
533      * Sets the given value for preemptive HTTP authentication (using BASIC) on the given FileSystemOptions object.
534      * Defaults to false if not set. It may be appropriate to set to true in cases when the resulting chattiness of the
535      * conversation outweighs any architectural desire to use a stronger authentication scheme than basic/preemptive.
536      *
537      * @param opts The FileSystemOptions.
538      * @param preemptiveAuth the desired setting; true=enabled and false=disabled.
539      */
540     public void setPreemptiveAuth(final FileSystemOptions opts, final boolean preemptiveAuth) {
541         setParam(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.valueOf(preemptiveAuth));
542     }
543 
544     /**
545      * Sets the proxy authenticator where the system should get the credentials from.
546      *
547      * @param opts The FileSystem options.
548      * @param authenticator The UserAuthenticator.
549      */
550     public void setProxyAuthenticator(final FileSystemOptions opts, final UserAuthenticator authenticator) {
551         setParam(opts, "proxyAuthenticator", authenticator);
552     }
553 
554     /**
555      * Sets the proxy to use for http connection.
556      * <p>
557      * You have to set the ProxyPort too if you would like to have the proxy really used.
558      * </p>
559      *
560      * @param opts The FileSystem options.
561      * @param proxyHost the host
562      * @see #setProxyPort
563      */
564     public void setProxyHost(final FileSystemOptions opts, final String proxyHost) {
565         setParam(opts, "proxyHost", proxyHost);
566     }
567 
568     /**
569      * Sets the proxy-port to use for http connection. You have to set the ProxyHost too if you would like to have the
570      * proxy really used.
571      *
572      * @param opts The FileSystem options.
573      * @param proxyPort the port
574      * @see #setProxyHost
575      */
576     public void setProxyPort(final FileSystemOptions opts, final int proxyPort) {
577         setParam(opts, "proxyPort", Integer.valueOf(proxyPort));
578     }
579 
580     /**
581      * Sets the proxy-scheme to use for http connection. You have to set the ProxyHost too if you would like to have the
582      * proxy really used.
583      *
584      * @param opts The FileSystem options.
585      * @param proxyScheme the protocol scheme
586      * @see #setProxyHost
587      * @since 2.7.0
588      */
589     public void setProxyScheme(final FileSystemOptions opts, final String proxyScheme) {
590         setParam(opts, PROXY_SCHEME, proxyScheme);
591     }
592 
593     /**
594      * Sets the socket timeout.
595      *
596      * @param opts The FileSystem options.
597      * @param soTimeout socket timeout.
598      */
599     public void setSoTimeout(final FileSystemOptions opts, final Duration soTimeout) {
600         setParam(opts, SO_TIMEOUT, soTimeout);
601     }
602 
603     /**
604      * Sets the socket timeout.
605      *
606      * @param opts The FileSystem options.
607      * @param soTimeout socket timeout.
608      * @deprecated Use {@link #setSoTimeout(FileSystemOptions, Duration)}.
609      */
610     @Deprecated
611     public void setSoTimeout(final FileSystemOptions opts, final int soTimeout) {
612         setSoTimeout(opts, Duration.ofMillis(soTimeout));
613     }
614 
615     /**
616      * Sets the charset used for URL encoding.
617      *
618      * @param opts The FileSystem options.
619      * @param charset the charset name.
620      */
621     public void setUrlCharset(final FileSystemOptions opts, final String charset) {
622         setParam(opts, "urlCharset", charset);
623     }
624 
625     /**
626      * Sets the user agent to attach to the outgoing http methods.
627      *
628      * @param opts the file system options to modify
629      * @param userAgent User Agent String
630      */
631     public void setUserAgent(final FileSystemOptions opts, final String userAgent) {
632         setParam(opts, "userAgent", userAgent);
633     }
634 }