001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.vfs2.provider.http;
018
019import org.apache.commons.httpclient.Cookie;
020import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
021import org.apache.commons.httpclient.params.HttpConnectionParams;
022import org.apache.commons.vfs2.FileSystem;
023import org.apache.commons.vfs2.FileSystemConfigBuilder;
024import org.apache.commons.vfs2.FileSystemOptions;
025import org.apache.commons.vfs2.UserAuthenticator;
026
027/**
028 * Configuration options for HTTP.
029 */
030public class HttpFileSystemConfigBuilder extends FileSystemConfigBuilder {
031    protected static final String KEY_FOLLOW_REDIRECT = "followRedirect";
032
033    protected static final String KEY_USER_AGENT = "userAgent";
034
035    private static final HttpFileSystemConfigBuilder BUILDER = new HttpFileSystemConfigBuilder();
036
037    private static final int DEFAULT_MAX_HOST_CONNECTIONS = 5;
038
039    private static final int DEFAULT_MAX_CONNECTIONS = 50;
040
041    private static final int DEFAULT_CONNECTION_TIMEOUT = 0;
042
043    private static final int DEFAULT_SO_TIMEOUT = 0;
044
045    private static final boolean DEFAULT_FOLLOW_REDIRECT = true;
046
047    private static final String DEFAULT_USER_AGENT = "Jakarta-Commons-VFS";
048
049    private static final String KEY_PREEMPTIVE_AUTHENTICATION = "preemptiveAuth";
050
051    /**
052     * Create new config builder.
053     *
054     * @param prefix String for properties of this file system.
055     * @since 2.0
056     */
057    protected HttpFileSystemConfigBuilder(final String prefix) {
058        super(prefix);
059    }
060
061    private HttpFileSystemConfigBuilder() {
062        super("http.");
063    }
064
065    /**
066     * Gets the singleton builder.
067     *
068     * @return the singleton builder.
069     */
070    public static HttpFileSystemConfigBuilder getInstance() {
071        return BUILDER;
072    }
073
074    /**
075     * Set the charset used for url encoding.<br>
076     *
077     * @param opts The FileSystem options.
078     * @param chaset the chaset
079     */
080    public void setUrlCharset(final FileSystemOptions opts, final String chaset) {
081        setParam(opts, "urlCharset", chaset);
082    }
083
084    /**
085     * Set the charset used for url encoding.<br>
086     *
087     * @param opts The FileSystem options.
088     * @return the chaset
089     */
090    public String getUrlCharset(final FileSystemOptions opts) {
091        return getString(opts, "urlCharset");
092    }
093
094    /**
095     * Set the proxy to use for http connection.<br>
096     * You have to set the ProxyPort too if you would like to have the proxy really used.
097     *
098     * @param opts The FileSystem options.
099     * @param proxyHost the host
100     * @see #setProxyPort
101     */
102    public void setProxyHost(final FileSystemOptions opts, final String proxyHost) {
103        setParam(opts, "proxyHost", proxyHost);
104    }
105
106    /**
107     * Set the proxy-port to use for http connection. You have to set the ProxyHost too if you would like to have the
108     * proxy really used.
109     *
110     * @param opts The FileSystem options.
111     * @param proxyPort the port
112     * @see #setProxyHost
113     */
114    public void setProxyPort(final FileSystemOptions opts, final int proxyPort) {
115        setParam(opts, "proxyPort", Integer.valueOf(proxyPort));
116    }
117
118    /**
119     * Get the proxy to use for http connection. You have to set the ProxyPort too if you would like to have the proxy
120     * really used.
121     *
122     * @param opts The FileSystem options.
123     * @return proxyHost
124     * @see #setProxyPort
125     */
126    public String getProxyHost(final FileSystemOptions opts) {
127        return getString(opts, "proxyHost");
128    }
129
130    /**
131     * Get the proxy-port to use for http the connection. You have to set the ProxyHost too if you would like to have
132     * the proxy really used.
133     *
134     * @param opts The FileSystem options.
135     * @return proxyPort: the port number or 0 if it is not set
136     * @see #setProxyHost
137     */
138    public int getProxyPort(final FileSystemOptions opts) {
139        return getInteger(opts, "proxyPort", 0);
140    }
141
142    /**
143     * Set the proxy authenticator where the system should get the credentials from.
144     *
145     * @param opts The FileSystem options.
146     * @param authenticator The UserAuthenticator.
147     */
148    public void setProxyAuthenticator(final FileSystemOptions opts, final UserAuthenticator authenticator) {
149        setParam(opts, "proxyAuthenticator", authenticator);
150    }
151
152    /**
153     * Get the proxy authenticator where the system should get the credentials from.
154     *
155     * @param opts The FileSystem options.
156     * @return The UserAuthenticator.
157     */
158    public UserAuthenticator getProxyAuthenticator(final FileSystemOptions opts) {
159        return (UserAuthenticator) getParam(opts, "proxyAuthenticator");
160    }
161
162    /**
163     * The cookies to add to the request.
164     *
165     * @param opts The FileSystem options.
166     * @param cookies An array of Cookies.
167     */
168    public void setCookies(final FileSystemOptions opts, final Cookie[] cookies) {
169        setParam(opts, "cookies", cookies);
170    }
171
172    /**
173     * Sets whether to follow redirects for the connection.
174     *
175     * @param opts The FileSystem options.
176     * @param redirect {@code true} to follow redirects, {@code false} not to.
177     * @see #setFollowRedirect
178     * @since 2.1
179     */
180    public void setFollowRedirect(final FileSystemOptions opts, final boolean redirect) {
181        setParam(opts, KEY_FOLLOW_REDIRECT, redirect);
182    }
183
184    /**
185     * The cookies to add to the request.
186     *
187     * @param opts The FileSystem options.
188     * @return the Cookie array.
189     */
190    public Cookie[] getCookies(final FileSystemOptions opts) {
191        return (Cookie[]) getParam(opts, "cookies");
192    }
193
194    /**
195     * Gets whether to follow redirects for the connection.
196     *
197     * @param opts The FileSystem options.
198     * @return {@code true} to follow redirects, {@code false} not to.
199     * @see #setFollowRedirect
200     * @since 2.1
201     */
202    public boolean getFollowRedirect(final FileSystemOptions opts) {
203        return getBoolean(opts, KEY_FOLLOW_REDIRECT, DEFAULT_FOLLOW_REDIRECT);
204    }
205
206    /**
207     * The maximum number of connections allowed.
208     *
209     * @param opts The FileSystem options.
210     * @param maxTotalConnections The maximum number of connections.
211     * @since 2.0
212     */
213    public void setMaxTotalConnections(final FileSystemOptions opts, final int maxTotalConnections) {
214        setParam(opts, HttpConnectionManagerParams.MAX_TOTAL_CONNECTIONS, Integer.valueOf(maxTotalConnections));
215    }
216
217    /**
218     * Retrieve the maximum number of connections allowed.
219     *
220     * @param opts The FileSystemOptions.
221     * @return The maximum number of connections allowed.
222     * @since 2.0
223     */
224    public int getMaxTotalConnections(final FileSystemOptions opts) {
225        return getInteger(opts, HttpConnectionManagerParams.MAX_TOTAL_CONNECTIONS, DEFAULT_MAX_CONNECTIONS);
226    }
227
228    /**
229     * The maximum number of connections allowed to any host.
230     *
231     * @param opts The FileSystem options.
232     * @param maxHostConnections The maximum number of connections to a host.
233     * @since 2.0
234     */
235    public void setMaxConnectionsPerHost(final FileSystemOptions opts, final int maxHostConnections) {
236        setParam(opts, HttpConnectionManagerParams.MAX_HOST_CONNECTIONS, Integer.valueOf(maxHostConnections));
237    }
238
239    /**
240     * Retrieve the maximum number of connections allowed per host.
241     *
242     * @param opts The FileSystemOptions.
243     * @return The maximum number of connections allowed per host.
244     * @since 2.0
245     */
246    public int getMaxConnectionsPerHost(final FileSystemOptions opts) {
247        return getInteger(opts, HttpConnectionManagerParams.MAX_HOST_CONNECTIONS, DEFAULT_MAX_HOST_CONNECTIONS);
248    }
249
250    /**
251     * Determines if the FileSystemOptions indicate that preemptive authentication is requested.
252     *
253     * @param opts The FileSystemOptions.
254     * @return true if preemptiveAuth is requested.
255     * @since 2.0
256     */
257    public boolean isPreemptiveAuth(final FileSystemOptions opts) {
258        return getBoolean(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.FALSE).booleanValue();
259    }
260
261    /**
262     * Sets the given value for preemptive HTTP authentication (using BASIC) on the given FileSystemOptions object.
263     * Defaults to false if not set. It may be appropriate to set to true in cases when the resulting chattiness of the
264     * conversation outweighs any architectural desire to use a stronger authentication scheme than basic/preemptive.
265     *
266     * @param opts The FileSystemOptions.
267     * @param preemptiveAuth the desired setting; true=enabled and false=disabled.
268     */
269    public void setPreemptiveAuth(final FileSystemOptions opts, final boolean preemptiveAuth) {
270        setParam(opts, KEY_PREEMPTIVE_AUTHENTICATION, Boolean.valueOf(preemptiveAuth));
271    }
272
273    /**
274     * The connection timeout.
275     *
276     * @param opts The FileSystem options.
277     * @param connectionTimeout The connection timeout.
278     * @since 2.1
279     */
280    public void setConnectionTimeout(final FileSystemOptions opts, final int connectionTimeout) {
281        setParam(opts, HttpConnectionParams.CONNECTION_TIMEOUT, Integer.valueOf(connectionTimeout));
282    }
283
284    /**
285     * Retrieve the connection timeout.
286     *
287     * @param opts The FileSystem options.
288     * @return The connection timeout.
289     * @since 2.1
290     */
291    public int getConnectionTimeout(final FileSystemOptions opts) {
292        return getInteger(opts, HttpConnectionParams.CONNECTION_TIMEOUT, DEFAULT_CONNECTION_TIMEOUT);
293    }
294
295    /**
296     * The socket timeout.
297     *
298     * @param opts The FileSystem options.
299     * @param soTimeout socket timeout.
300     * @since 2.1
301     */
302    public void setSoTimeout(final FileSystemOptions opts, final int soTimeout) {
303        setParam(opts, HttpConnectionParams.SO_TIMEOUT, Integer.valueOf(soTimeout));
304    }
305
306    /**
307     * Retrieve the socket timeout.
308     *
309     * @param opts The FileSystemOptions.
310     * @return The socket timeout.
311     * @since 2.1
312     */
313    public int getSoTimeout(final FileSystemOptions opts) {
314        return getInteger(opts, HttpConnectionParams.SO_TIMEOUT, DEFAULT_SO_TIMEOUT);
315    }
316
317    /**
318     * Assign the user agent to attach to the outgoing http methods
319     *
320     * @param userAgent User Agent String
321     */
322    public void setUserAgent(final FileSystemOptions opts, final String userAgent) {
323        setParam(opts, "userAgent", userAgent);
324    }
325
326    /**
327     * Return the user agent string
328     *
329     * @return User provided User-Agent string, otherwise default of: Jakarta-Commons-VFS
330     */
331    public String getUserAgent(final FileSystemOptions opts) {
332        final String userAgent = (String) getParam(opts, KEY_USER_AGENT);
333        return userAgent != null ? userAgent : DEFAULT_USER_AGENT;
334    }
335
336    @Override
337    protected Class<? extends FileSystem> getConfigClass() {
338        return HttpFileSystem.class;
339    }
340}