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