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