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