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 org.apache.commons.vfs2.FileSystem;
20  import org.apache.commons.vfs2.FileSystemConfigBuilder;
21  import org.apache.commons.vfs2.FileSystemOptions;
22  import org.apache.commons.vfs2.UserAuthenticator;
23  import org.apache.http.cookie.Cookie;
24  
25  /**
26   * Configuration options builder utility for http4 provider.
27   *
28   * @since 2.3
29   */
30  public class Http4FileSystemConfigBuilder extends FileSystemConfigBuilder {
31  
32      private static final Http4FileSystemConfigBuilderileSystemConfigBuilder.html#Http4FileSystemConfigBuilder">Http4FileSystemConfigBuilder BUILDER = new Http4FileSystemConfigBuilder();
33  
34      /**
35       * Defines the maximum number of connections allowed overall. This value only applies
36       * to the number of connections from a particular instance of HTTP connection manager.
37       * <p>
38       * This parameter expects a value of type {@link Integer}.
39       * </p>
40       */
41      private static final String MAX_TOTAL_CONNECTIONS = "http.connection-manager.max-total";
42  
43      /**
44       * Defines the maximum number of connections allowed per host configuration.
45       * These values only apply to the number of connections from a particular instance
46       * of HTTP connection manager.
47       */
48      private static final String MAX_HOST_CONNECTIONS = "http.connection-manager.max-per-host";
49  
50      /**
51       * Defines the connection timeout of an HTTP request.
52       * <p>
53       * This parameter expects a value of type {@link Integer}.
54       * </p>
55       */
56      private static final String CONNECTION_TIMEOUT = "http.connection.timeout";
57  
58      /**
59       * Defines the socket timeout of an HTTP request.
60       * <p>
61       * This parameter expects a value of type {@link Integer}.
62       * </p>
63       */
64      private static final String SO_TIMEOUT = "http.socket.timeout";
65  
66      /**
67       * Defines whether Keep-Alive option is used or not.
68       * <p>
69       * This parameter expects a value of type {@link Boolean}.
70       * </p>
71       */
72      private static final String KEEP_ALIVE = "http.keepAlive";
73  
74      /**
75       * Defines the keystore file path for SSL connections.
76       * <p>
77       * This parameter expects a value of type {@link String}.
78       * </p>
79       */
80      private static final String KEYSTORE_FILE = "http.keystoreFile";
81  
82      /**
83       * Defines the keystore pass phrase for SSL connections.
84       * <p>
85       * This parameter expects a value of type {@link String}.
86       * </p>
87       */
88      private static final String KEYSTORE_PASS = "http.keystorePass";
89  
90      /**
91       * Defines whether the host name should be verified or not in SSL connections.
92       * <p>
93       * This parameter expects a value of type {@link Boolean}.
94       * </p>
95       */
96      private static final String HOSTNAME_VERIFICATION_ENABLED = "http.hostname-verification.enabled";
97  
98      /**
99       * Defines whether the HttpClient should follow redirections from the responses.
100      * <p>
101      * This parameter expects a value of type {@link Boolean}.
102      * </p>
103      */
104     protected static final String KEY_FOLLOW_REDIRECT = "followRedirect";
105 
106     /**
107      * Defines the User-Agent request header string of the underlying HttpClient.
108      * <p>
109      * This parameter expects a value of type {@link String}.
110      * </p>
111      */
112     private static final String KEY_USER_AGENT = "userAgent";
113 
114     /**
115      * Defines whether the preemptive authentication should be enabled or not.
116      * <p>
117      * This parameter expects a value of type {@link Boolean}.
118      * </p>
119      */
120     private static final String KEY_PREEMPTIVE_AUTHENTICATION = "preemptiveAuth";
121 
122     /**
123      * The default value for {@link #MAX_TOTAL_CONNECTIONS} configuration.
124      */
125     private static final int DEFAULT_MAX_CONNECTIONS = 50;
126 
127     /**
128      * The default value for {@link #MAX_HOST_CONNECTIONS} configuration.
129      */
130     private static final int DEFAULT_MAX_HOST_CONNECTIONS = 5;
131 
132     /**
133      * The default value for {@link #CONNECTION_TIMEOUT} configuration.
134      */
135     private static final int DEFAULT_CONNECTION_TIMEOUT = 0;
136 
137     /**
138      * The default value for {@link #SO_TIMEOUT} configuration.
139      */
140     private static final int DEFAULT_SO_TIMEOUT = 0;
141 
142     /**
143      * The default value for {@link #KEEP_ALIVE} configuration.
144      */
145     private static final boolean DEFAULT_KEEP_ALIVE = true;
146 
147     /**
148      * The default value for {@link #KEY_FOLLOW_REDIRECT} configuration.
149      */
150     private static final boolean DEFAULT_FOLLOW_REDIRECT = true;
151 
152     /**
153      * The default value for {@link #KEY_USER_AGENT} configuration.
154      */
155     private static final String DEFAULT_USER_AGENT = "Jakarta-Commons-VFS";
156 
157     /**
158      * The default value for {@link #HOSTNAME_VERIFICATION_ENABLED} configuration.
159      */
160     private static final boolean DEFAULT_HOSTNAME_VERIFICATION_ENABLED = true;
161 
162     /**
163      * Construct an {@code Http4FileSystemConfigBuilder}.
164      *
165      * @param prefix String for properties of this file system.
166      */
167     protected Http4FileSystemConfigBuilder(final String prefix) {
168         super(prefix);
169     }
170 
171     private Http4FileSystemConfigBuilder() {
172         super("http.");
173     }
174 
175     /**
176      * Gets the singleton builder.
177      *
178      * @return the singleton builder.
179      */
180     public static Http4FileSystemConfigBuilder getInstance() {
181         return BUILDER;
182     }
183 
184     /**
185      * Sets the charset used for url encoding.
186      *
187      * @param opts The FileSystem options.
188      * @param chaset the chaset
189      */
190     public void setUrlCharset(final FileSystemOptions opts, final String chaset) {
191         setParam(opts, "urlCharset", chaset);
192     }
193 
194     /**
195      * Sets the charset used for url encoding.
196      *
197      * @param opts The FileSystem options.
198      * @return the chaset
199      */
200     public String getUrlCharset(final FileSystemOptions opts) {
201         return getString(opts, "urlCharset");
202     }
203 
204     /**
205      * Sets the proxy to use for http connection.
206      * <p>
207      * You have to set the ProxyPort too if you would like to have the proxy really used.
208      * </p>
209      *
210      * @param opts The FileSystem options.
211      * @param proxyHost the host
212      * @see #setProxyPort
213      */
214     public void setProxyHost(final FileSystemOptions opts, final String proxyHost) {
215         setParam(opts, "proxyHost", proxyHost);
216     }
217 
218     /**
219      * Sets the proxy-port to use for http connection. You have to set the ProxyHost too if you would like to have the
220      * proxy really used.
221      *
222      * @param opts The FileSystem options.
223      * @param proxyPort the port
224      * @see #setProxyHost
225      */
226     public void setProxyPort(final FileSystemOptions opts, final int proxyPort) {
227         setParam(opts, "proxyPort", Integer.valueOf(proxyPort));
228     }
229 
230     /**
231      * Gets the proxy to use for http connection. You have to set the ProxyPort too if you would like to have the proxy
232      * really used.
233      *
234      * @param opts The FileSystem options.
235      * @return proxyHost
236      * @see #setProxyPort
237      */
238     public String getProxyHost(final FileSystemOptions opts) {
239         return getString(opts, "proxyHost");
240     }
241 
242     /**
243      * Gets the proxy-port to use for http the connection. You have to set the ProxyHost too if you would like to have
244      * the proxy really used.
245      *
246      * @param opts The FileSystem options.
247      * @return proxyPort: the port number or 0 if it is not set
248      * @see #setProxyHost
249      */
250     public int getProxyPort(final FileSystemOptions opts) {
251         return getInteger(opts, "proxyPort", 0);
252     }
253 
254     /**
255      * Sets the proxy authenticator where the system should get the credentials from.
256      *
257      * @param opts The FileSystem options.
258      * @param authenticator The UserAuthenticator.
259      */
260     public void setProxyAuthenticator(final FileSystemOptions opts, final UserAuthenticator authenticator) {
261         setParam(opts, "proxyAuthenticator", authenticator);
262     }
263 
264     /**
265      * Gets the proxy authenticator where the system should get the credentials from.
266      *
267      * @param opts The FileSystem options.
268      * @return The UserAuthenticator.
269      */
270     public UserAuthenticator getProxyAuthenticator(final FileSystemOptions opts) {
271         return (UserAuthenticator) getParam(opts, "proxyAuthenticator");
272     }
273 
274     /**
275      * The cookies to add to the request.
276      *
277      * @param opts The FileSystem options.
278      * @param cookies An array of Cookies.
279      */
280     public void setCookies(final FileSystemOptions opts, final Cookie[] cookies) {
281         setParam(opts, "cookies", cookies);
282     }
283 
284     /**
285      * Sets whether to follow redirects for the connection.
286      *
287      * @param opts The FileSystem options.
288      * @param redirect {@code true} to follow redirects, {@code false} not to.
289      * @see #setFollowRedirect
290      */
291     public void setFollowRedirect(final FileSystemOptions opts, final boolean redirect) {
292         setParam(opts, KEY_FOLLOW_REDIRECT, redirect);
293     }
294 
295     /**
296      * Gets the cookies to add to the request.
297      *
298      * @param opts The FileSystem options.
299      * @return the Cookie array.
300      */
301     public Cookie[] getCookies(final FileSystemOptions opts) {
302         return (Cookie[]) getParam(opts, "cookies");
303     }
304 
305     /**
306      * Gets whether to follow redirects for the connection.
307      *
308      * @param opts The FileSystem options.
309      * @return {@code true} to follow redirects, {@code false} not to.
310      * @see #setFollowRedirect
311      */
312     public boolean getFollowRedirect(final FileSystemOptions opts) {
313         return getBoolean(opts, KEY_FOLLOW_REDIRECT, DEFAULT_FOLLOW_REDIRECT);
314     }
315 
316     /**
317      * Sets the maximum number of connections allowed.
318      *
319      * @param opts The FileSystem options.
320      * @param maxTotalConnections The maximum number of connections.
321      */
322     public void setMaxTotalConnections(final FileSystemOptions opts, final int maxTotalConnections) {
323         setParam(opts, MAX_TOTAL_CONNECTIONS, Integer.valueOf(maxTotalConnections));
324     }
325 
326     /**
327      * Gets the maximum number of connections allowed.
328      *
329      * @param opts The FileSystemOptions.
330      * @return The maximum number of connections allowed.
331      */
332     public int getMaxTotalConnections(final FileSystemOptions opts) {
333         return getInteger(opts, MAX_TOTAL_CONNECTIONS, DEFAULT_MAX_CONNECTIONS);
334     }
335 
336     /**
337      * Sets the maximum number of connections allowed to any host.
338      *
339      * @param opts The FileSystem options.
340      * @param maxHostConnections The maximum number of connections to a host.
341      */
342     public void setMaxConnectionsPerHost(final FileSystemOptions opts, final int maxHostConnections) {
343         setParam(opts, MAX_HOST_CONNECTIONS, Integer.valueOf(maxHostConnections));
344     }
345 
346     /**
347      * Gets the maximum number of connections allowed per host.
348      *
349      * @param opts The FileSystemOptions.
350      * @return The maximum number of connections allowed per host.
351      */
352     public int getMaxConnectionsPerHost(final FileSystemOptions opts) {
353         return getInteger(opts, MAX_HOST_CONNECTIONS, DEFAULT_MAX_HOST_CONNECTIONS);
354     }
355 
356     /**
357      * Determines if the FileSystemOptions indicate that preemptive authentication is requested.
358      *
359      * @param opts The FileSystemOptions.
360      * @return true if preemptiveAuth is requested.
361      */
362     public boolean isPreemptiveAuth(final FileSystemOptions opts) {
363         return getBoolean(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.FALSE).booleanValue();
364     }
365 
366     /**
367      * Sets the given value for preemptive HTTP authentication (using BASIC) on the given FileSystemOptions object.
368      * Defaults to false if not set. It may be appropriate to set to true in cases when the resulting chattiness of the
369      * conversation outweighs any architectural desire to use a stronger authentication scheme than basic/preemptive.
370      *
371      * @param opts The FileSystemOptions.
372      * @param preemptiveAuth the desired setting; true=enabled and false=disabled.
373      */
374     public void setPreemptiveAuth(final FileSystemOptions opts, final boolean preemptiveAuth) {
375         setParam(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.valueOf(preemptiveAuth));
376     }
377 
378     /**
379      * The connection timeout.
380      *
381      * @param opts The FileSystem options.
382      * @param connectionTimeout The connection timeout.
383      */
384     public void setConnectionTimeout(final FileSystemOptions opts, final int connectionTimeout) {
385         setParam(opts, CONNECTION_TIMEOUT, Integer.valueOf(connectionTimeout));
386     }
387 
388     /**
389      * Gets the connection timeout.
390      *
391      * @param opts The FileSystem options.
392      * @return The connection timeout.
393      */
394     public int getConnectionTimeout(final FileSystemOptions opts) {
395         return getInteger(opts, CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
396     }
397 
398     /**
399      * The socket timeout.
400      *
401      * @param opts The FileSystem options.
402      * @param soTimeout socket timeout.
403      */
404     public void setSoTimeout(final FileSystemOptions opts, final int soTimeout) {
405         setParam(opts, SO_TIMEOUT, Integer.valueOf(soTimeout));
406     }
407 
408     /**
409      * Gets the socket timeout.
410      *
411      * @param opts The FileSystemOptions.
412      * @return The socket timeout.
413      */
414     public int getSoTimeout(final FileSystemOptions opts) {
415         return getInteger(opts, SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
416     }
417 
418     /**
419      * Sets if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
420      *
421      * @param opts The FileSystemOptions.
422      * @param keepAlive whether the FileSystemOptions indicate that HTTP Keep-Alive is respected or not.
423      */
424     public void setKeepAlive(final FileSystemOptions opts, final boolean keepAlive) {
425         setParam(opts, KEEP_ALIVE, Boolean.valueOf(keepAlive));
426     }
427 
428     /**
429      * Determines if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
430      *
431      * @param opts The FileSystemOptions.
432      * @return true if if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
433      */
434     public boolean isKeepAlive(final FileSystemOptions opts) {
435         return getBoolean(opts, KEEP_ALIVE, DEFAULT_KEEP_ALIVE);
436     }
437 
438     /**
439      * Sets the user agent to attach to the outgoing http methods
440      *
441      * @param opts the file system options to modify
442      * @param userAgent User Agent String
443      */
444     public void setUserAgent(final FileSystemOptions opts, final String userAgent) {
445         setParam(opts, "userAgent", userAgent);
446     }
447 
448     /**
449      * Gets the user agent string
450      *
451      * @param opts the file system options to modify
452      * @return User provided User-Agent string, otherwise default of: Commons-VFS
453      */
454     public String getUserAgent(final FileSystemOptions opts) {
455         final String userAgent = (String) getParam(opts, KEY_USER_AGENT);
456         return userAgent != null ? userAgent : DEFAULT_USER_AGENT;
457     }
458 
459     /**
460      * Set keystore file path for SSL connections.
461      * @param opts the file system options to modify
462      * @param keyStoreFile keystore file path
463      */
464     public void setKeyStoreFile(final FileSystemOptions opts, final String keyStoreFile) {
465         setParam(opts, KEYSTORE_FILE, keyStoreFile);
466     }
467 
468     /**
469      * Return keystore file path to be used in SSL connections.
470      * @param opts the file system options to modify
471      * @return keystore file path to be used in SSL connections
472      */
473     public String getKeyStoreFile(final FileSystemOptions opts) {
474         return (String) getParam(opts, KEYSTORE_FILE);
475     }
476 
477     /**
478      * Set keystore pass phrase for SSL connecdtions.
479      * @param opts the file system options to modify
480      * @param keyStorePass keystore pass phrase for SSL connecdtions
481      */
482     public void setKeyStorePass(final FileSystemOptions opts, final String keyStorePass) {
483         setParam(opts, KEYSTORE_PASS, keyStorePass);
484     }
485 
486     /**
487      * Return keystore pass phrase for SSL connections.
488      * @param opts the file system options to modify
489      * @return keystore pass phrase for SSL connections
490      */
491     String getKeyStorePass(final FileSystemOptions opts) {
492         return (String) getParam(opts, KEYSTORE_PASS);
493     }
494 
495     /**
496      * Sets if the hostname should be verified in SSL context.
497      *
498      * @param opts The FileSystemOptions.
499      * @param hostnameVerificationEnabled whether hostname should be verified
500      */
501     public void setHostnameVerificationEnabled(final FileSystemOptions opts, final boolean hostnameVerificationEnabled) {
502         setParam(opts, HOSTNAME_VERIFICATION_ENABLED, Boolean.valueOf(hostnameVerificationEnabled));
503     }
504 
505     /**
506      * Determines if the hostname should be verified in SSL context.
507      *
508      * @param opts The FileSystemOptions.
509      * @return true if if the FileSystemOptions indicate that HTTP Keep-Alive is respected.
510      */
511     public boolean isHostnameVerificationEnabled(final FileSystemOptions opts) {
512         return getBoolean(opts, HOSTNAME_VERIFICATION_ENABLED, DEFAULT_HOSTNAME_VERIFICATION_ENABLED);
513     }
514 
515     @Override
516     protected Class<? extends FileSystem> getConfigClass() {
517         return Http4FileSystem.class;
518     }
519 }