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.http;
18  
19  import java.time.Duration;
20  
21  import org.apache.commons.httpclient.Cookie;
22  import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
23  import org.apache.commons.httpclient.params.HttpConnectionParams;
24  import org.apache.commons.vfs2.FileSystem;
25  import org.apache.commons.vfs2.FileSystemConfigBuilder;
26  import org.apache.commons.vfs2.FileSystemOptions;
27  import org.apache.commons.vfs2.UserAuthenticator;
28  
29  /**
30   * Configuration options for HTTP.
31   */
32  public class HttpFileSystemConfigBuilder extends FileSystemConfigBuilder {
33  
34      protected static final String KEY_FOLLOW_REDIRECT = "followRedirect";
35  
36      protected static final String KEY_USER_AGENT = "userAgent";
37  
38      private static final HttpFileSystemConfigBuilderleSystemConfigBuilder.html#HttpFileSystemConfigBuilder">HttpFileSystemConfigBuilder BUILDER = new HttpFileSystemConfigBuilder();
39  
40      private static final int DEFAULT_MAX_HOST_CONNECTIONS = 5;
41  
42      private static final int DEFAULT_MAX_CONNECTIONS = 50;
43  
44      private static final Duration DEFAULT_CONNECTION_TIMEOUT = Duration.ZERO;
45  
46      private static final Duration DEFAULT_SO_TIMEOUT = Duration.ZERO;
47  
48      private static final boolean DEFAULT_FOLLOW_REDIRECT = true;
49  
50      private static final String DEFAULT_USER_AGENT = "Jakarta-Commons-VFS";
51  
52      private static final String KEY_PREEMPTIVE_AUTHENTICATION = "preemptiveAuth";
53  
54      /**
55       * Gets the singleton builder.
56       *
57       * @return the singleton builder.
58       */
59      public static HttpFileSystemConfigBuilder getInstance() {
60          return BUILDER;
61      }
62  
63      private HttpFileSystemConfigBuilder() {
64          super("http.");
65      }
66  
67      /**
68       * Creates new config builder.
69       *
70       * @param prefix String for properties of this file system.
71       * @since 2.0
72       */
73      protected HttpFileSystemConfigBuilder(final String prefix) {
74          super(prefix);
75      }
76  
77      @Override
78      protected Class<? extends FileSystem> getConfigClass() {
79          return HttpFileSystem.class;
80      }
81  
82      /**
83       * Gets the connection timeout.
84       *
85       * @param opts The FileSystem options.
86       * @return The connection timeout.
87       * @since 2.1
88       * @deprecated Use {@link #getConnectionTimeoutDuration(FileSystemOptions)}.
89       */
90      @Deprecated
91      public int getConnectionTimeout(final FileSystemOptions opts) {
92          return getDurationInteger(opts, HttpConnectionParams.CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
93      }
94  
95      /**
96       * Gets the connection timeout.
97       *
98       * @param opts The FileSystem options.
99       * @return The connection timeout.
100      * @since 2.8.0
101      */
102     public Duration getConnectionTimeoutDuration(final FileSystemOptions opts) {
103         return getDuration(opts, HttpConnectionParams.CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
104     }
105 
106     /**
107      * Gets the cookies to add to the request.
108      *
109      * @param opts The FileSystem options.
110      * @return the Cookie array.
111      */
112     public Cookie[] getCookies(final FileSystemOptions opts) {
113         return getParam(opts, "cookies");
114     }
115 
116     /**
117      * Gets whether to follow redirects for the connection.
118      *
119      * @param opts The FileSystem options.
120      * @return {@code true} to follow redirects, {@code false} not to.
121      * @see #setFollowRedirect
122      * @since 2.1
123      */
124     public boolean getFollowRedirect(final FileSystemOptions opts) {
125         return getBoolean(opts, KEY_FOLLOW_REDIRECT, DEFAULT_FOLLOW_REDIRECT);
126     }
127 
128     /**
129      * Gets the maximum number of connections allowed per host.
130      *
131      * @param opts The FileSystemOptions.
132      * @return The maximum number of connections allowed per host.
133      * @since 2.0
134      */
135     public int getMaxConnectionsPerHost(final FileSystemOptions opts) {
136         return getInteger(opts, HttpConnectionManagerParams.MAX_HOST_CONNECTIONS, DEFAULT_MAX_HOST_CONNECTIONS);
137     }
138 
139     /**
140      * Gets the maximum number of connections allowed.
141      *
142      * @param opts The FileSystemOptions.
143      * @return The maximum number of connections allowed.
144      * @since 2.0
145      */
146     public int getMaxTotalConnections(final FileSystemOptions opts) {
147         return getInteger(opts, HttpConnectionManagerParams.MAX_TOTAL_CONNECTIONS, DEFAULT_MAX_CONNECTIONS);
148     }
149 
150     /**
151      * Gets the proxy authenticator where the system should get the credentials from.
152      *
153      * @param opts The FileSystem options.
154      * @return The UserAuthenticator.
155      */
156     public UserAuthenticator getProxyAuthenticator(final FileSystemOptions opts) {
157         return getParam(opts, "proxyAuthenticator");
158     }
159 
160     /**
161      * Gets the proxy to use for http connection. You have to set the ProxyPort too if you would like to have the proxy
162      * really used.
163      *
164      * @param opts The FileSystem options.
165      * @return proxyHost
166      * @see #setProxyPort
167      */
168     public String getProxyHost(final FileSystemOptions opts) {
169         return getString(opts, "proxyHost");
170     }
171 
172     /**
173      * Gets the proxy-port to use for http the connection. You have to set the ProxyHost too if you would like to have
174      * the proxy really used.
175      *
176      * @param opts The FileSystem options.
177      * @return proxyPort: the port number or 0 if it is not set
178      * @see #setProxyHost
179      */
180     public int getProxyPort(final FileSystemOptions opts) {
181         return getInteger(opts, "proxyPort", 0);
182     }
183 
184     /**
185      * Gets the socket timeout.
186      *
187      * @param opts The FileSystemOptions.
188      * @return The socket timeout.
189      * @since 2.1
190      * @deprecated Use {@link #getSoTimeoutDuration(FileSystemOptions)}.
191      */
192     @Deprecated
193     public int getSoTimeout(final FileSystemOptions opts) {
194         return getDurationInteger(opts, HttpConnectionParams.SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
195     }
196 
197     /**
198      * Gets the socket timeout.
199      *
200      * @param opts The FileSystemOptions.
201      * @return The socket timeout.
202      * @since 2.8.0
203      */
204     public Duration getSoTimeoutDuration(final FileSystemOptions opts) {
205         return getDuration(opts, HttpConnectionParams.SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
206     }
207 
208     /**
209      * Gets the charset used for url encoding.
210      *
211      * @param opts The FileSystem options.
212      * @return the charset name.
213      */
214     public String getUrlCharset(final FileSystemOptions opts) {
215         return getString(opts, "urlCharset");
216     }
217 
218     /**
219      * Gets the user agent string
220      *
221      * @param opts the file system options to modify
222      * @return User provided User-Agent string, otherwise default of: Commons-VFS
223      */
224     public String getUserAgent(final FileSystemOptions opts) {
225         final String userAgent = getParam(opts, KEY_USER_AGENT);
226         return userAgent != null ? userAgent : DEFAULT_USER_AGENT;
227     }
228 
229     /**
230      * Determines if the FileSystemOptions indicate that preemptive authentication is requested.
231      *
232      * @param opts The FileSystemOptions.
233      * @return true if preemptiveAuth is requested.
234      * @since 2.0
235      */
236     public boolean isPreemptiveAuth(final FileSystemOptions opts) {
237         return getBoolean(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.FALSE).booleanValue();
238     }
239 
240     /**
241      * The connection timeout.
242      *
243      * @param opts The FileSystem options.
244      * @param timeout The connection timeout.
245      * @since 2.8.0
246      */
247     public void setConnectionTimeout(final FileSystemOptions opts, final Duration timeout) {
248         setParam(opts, HttpConnectionParams.CONNECTION_TIMEOUT, timeout);
249     }
250 
251     /**
252      * The connection timeout.
253      *
254      * @param opts The FileSystem options.
255      * @param timeout The connection timeout.
256      * @since 2.1
257      * @deprecated Use {@link #setConnectionTimeout(FileSystemOptions, Duration)}.
258      */
259     @Deprecated
260     public void setConnectionTimeout(final FileSystemOptions opts, final int timeout) {
261         setConnectionTimeout(opts, Duration.ofMillis(timeout));
262     }
263 
264     /**
265      * The cookies to add to the request.
266      *
267      * @param opts The FileSystem options.
268      * @param cookies An array of Cookies.
269      */
270     public void setCookies(final FileSystemOptions opts, final Cookie[] cookies) {
271         setParam(opts, "cookies", cookies);
272     }
273 
274     /**
275      * Sets whether to follow redirects for the connection.
276      *
277      * @param opts The FileSystem options.
278      * @param redirect {@code true} to follow redirects, {@code false} not to.
279      * @see #setFollowRedirect
280      * @since 2.1
281      */
282     public void setFollowRedirect(final FileSystemOptions opts, final boolean redirect) {
283         setParam(opts, KEY_FOLLOW_REDIRECT, redirect);
284     }
285 
286     /**
287      * Sets the maximum number of connections allowed to any host.
288      *
289      * @param opts The FileSystem options.
290      * @param maxHostConnections The maximum number of connections to a host.
291      * @since 2.0
292      */
293     public void setMaxConnectionsPerHost(final FileSystemOptions opts, final int maxHostConnections) {
294         setParam(opts, HttpConnectionManagerParams.MAX_HOST_CONNECTIONS, Integer.valueOf(maxHostConnections));
295     }
296 
297     /**
298      * Sets the maximum number of connections allowed.
299      *
300      * @param opts The FileSystem options.
301      * @param maxTotalConnections The maximum number of connections.
302      * @since 2.0
303      */
304     public void setMaxTotalConnections(final FileSystemOptions opts, final int maxTotalConnections) {
305         setParam(opts, HttpConnectionManagerParams.MAX_TOTAL_CONNECTIONS, Integer.valueOf(maxTotalConnections));
306     }
307 
308     /**
309      * Sets the given value for preemptive HTTP authentication (using BASIC) on the given FileSystemOptions object.
310      * Defaults to false if not set. It may be appropriate to set to true in cases when the resulting chattiness of the
311      * conversation outweighs any architectural desire to use a stronger authentication scheme than basic/preemptive.
312      *
313      * @param opts The FileSystemOptions.
314      * @param preemptiveAuth the desired setting; true=enabled and false=disabled.
315      */
316     public void setPreemptiveAuth(final FileSystemOptions opts, final boolean preemptiveAuth) {
317         setParam(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.valueOf(preemptiveAuth));
318     }
319 
320     /**
321      * Sets the proxy authenticator where the system should get the credentials from.
322      *
323      * @param opts The FileSystem options.
324      * @param authenticator The UserAuthenticator.
325      */
326     public void setProxyAuthenticator(final FileSystemOptions opts, final UserAuthenticator authenticator) {
327         setParam(opts, "proxyAuthenticator", authenticator);
328     }
329 
330     /**
331      * Sets the proxy to use for http connection.
332      * <p>
333      * You have to set the ProxyPort too if you would like to have the proxy really used.
334      * </p>
335      *
336      * @param opts The FileSystem options.
337      * @param proxyHost the host
338      * @see #setProxyPort
339      */
340     public void setProxyHost(final FileSystemOptions opts, final String proxyHost) {
341         setParam(opts, "proxyHost", proxyHost);
342     }
343 
344     /**
345      * Sets the proxy-port to use for http connection. You have to set the ProxyHost too if you would like to have the
346      * proxy really used.
347      *
348      * @param opts The FileSystem options.
349      * @param proxyPort the port
350      * @see #setProxyHost
351      */
352     public void setProxyPort(final FileSystemOptions opts, final int proxyPort) {
353         setParam(opts, "proxyPort", Integer.valueOf(proxyPort));
354     }
355 
356     /**
357      * The socket timeout.
358      *
359      * @param opts The FileSystem options.
360      * @param timeout socket timeout.
361      * @since 2.8.0
362      */
363     public void setSoTimeout(final FileSystemOptions opts, final Duration timeout) {
364         setParam(opts, HttpConnectionParams.SO_TIMEOUT, timeout);
365     }
366 
367     /**
368      * The socket timeout.
369      *
370      * @param opts The FileSystem options.
371      * @param timeout socket timeout.
372      * @since 2.1
373      * @deprecated Use {@link #setSoTimeout(FileSystemOptions, Duration)}.
374      */
375     @Deprecated
376     public void setSoTimeout(final FileSystemOptions opts, final int timeout) {
377         setSoTimeout(opts, Duration.ofMillis(timeout));
378     }
379 
380     /**
381      * Sets the charset used for url encoding.
382      *
383      * @param opts The FileSystem options.
384      * @param charset the charset name.
385      */
386     public void setUrlCharset(final FileSystemOptions opts, final String charset) {
387         setParam(opts, "urlCharset", charset);
388     }
389 
390     /**
391      * Sets the user agent to attach to the outgoing http methods
392      *
393      * @param opts the file system options to modify
394      * @param userAgent User Agent String
395      */
396     public void setUserAgent(final FileSystemOptions opts, final String userAgent) {
397         setParam(opts, "userAgent", userAgent);
398     }
399 }