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;
018
019import java.io.File;
020import java.lang.reflect.Constructor;
021import java.net.URI;
022import java.net.URL;
023import java.net.URLStreamHandlerFactory;
024import java.util.Collection;
025
026import org.apache.commons.logging.Log;
027import org.apache.commons.vfs2.operations.FileOperationProvider;
028
029/**
030 * A FileSystemManager manages a set of file systems.  This interface is
031 * used to locate a {@link FileObject} by name from one of those file systems.
032 * <p/>
033 * <p>To locate a {@link FileObject}, use one of the {@code resolveFile()}
034 * methods.</p>
035 * <p/>
036 * <h4><a name="naming">File Naming</a></h4>
037 * <p/>
038 * <p>A file system manager can recognise several types of file names:
039 * <p/>
040 * <ul>
041 * <p/>
042 * <li><p>Absolute URI.  These must start with a scheme, such as
043 * {@code file:} or {@code ftp:}, followed by a scheme dependent
044 * file name.  Some examples:</p>
045 * <pre>
046 * file:/c:/somefile
047 * ftp://somewhere.org/somefile
048 * </pre>
049 * <p/>
050 * <li><p>Absolute local file name.  For example,
051 * {@code /home/someuser/a-file} or {@code c:\dir\somefile.html}.
052 * Elements in the name can be separated using any of the following
053 * characters: {@code /}, {@code \}, or the native file separator
054 * character. For example, the following file names are the same:</p>
055 * <pre>
056 * c:\somedir\somefile.xml
057 * c:/somedir/somefile.xml
058 * </pre>
059 * <p/>
060 * <li><p>Relative path.  For example: {@code ../somefile} or
061 * {@code somedir/file.txt}.   The file system manager resolves relative
062 * paths against its <i>base file</i>.  Elements in the relative path can be
063 * separated using {@code /}, {@code \}, or file system specific
064 * separator characters.  Relative paths may also contain {@code ..} and
065 * {@code .} elements.  See {@link FileObject#resolveFile} for more
066 * details.</p>
067 * <p/>
068 * </ul>
069 */
070public interface FileSystemManager
071{
072    /**
073     * Returns the base file used to resolve relative paths.
074     * @return The base FileObject.
075     * @throws FileSystemException if an error occurs.
076     */
077    FileObject getBaseFile() throws FileSystemException;
078
079    /**
080     * Locates a file by name.  Equivalent to calling
081     * {@code resolveFile(getBaseFile(), name)}.
082     *
083     * @param name The name of the file.
084     * @return The file.  Never returns null.
085     * @throws FileSystemException On error parsing the file name.
086     */
087    FileObject resolveFile(String name) throws FileSystemException;
088
089    /**
090     * Locates a file by name.  Equivalent to calling
091     * {@code resolveFile(getBaseFile(), name)}.
092     *
093     * @param name              The name of the file.
094     * @param fileSystemOptions The FileSystemOptions used for FileSystem creation
095     * @return The file.  Never returns null.
096     * @throws FileSystemException On error parsing the file name.
097     */
098    FileObject resolveFile(String name, FileSystemOptions fileSystemOptions)
099        throws FileSystemException;
100
101    /**
102     * Locates a file by name.  The name is resolved as described
103     * <a href="#naming">above</a>.  That is, the name can be either
104     * an absolute URI, an absolute file name, or a relative path to
105     * be resolved against {@code baseFile}.
106     * <p/>
107     * <p>Note that the file does not have to exist when this method is called.
108     *
109     * @param name     The name of the file.
110     * @param baseFile The base file to use to resolve relative paths.
111     *                 May be null.
112     * @return The file.  Never returns null.
113     * @throws FileSystemException On error parsing the file name.
114     */
115    FileObject resolveFile(FileObject baseFile, String name) throws FileSystemException;
116
117    /**
118     * Locates a file by name.  See {@link #resolveFile(FileObject, String)}
119     * for details.
120     *
121     * @param baseFile The base file to use to resolve relative paths.
122     *                 May be null.
123     * @param name     The name of the file.
124     * @return The file.  Never returns null.
125     * @throws FileSystemException On error parsing the file name.
126     */
127    FileObject resolveFile(File baseFile, String name) throws FileSystemException;
128
129    /**
130     * Resolves a name, relative to this file name.  Equivalent to calling
131     * {@code resolveName( path, NameScope.FILE_SYSTEM )}.
132     *
133     * @param root the base filename
134     * @param name The name to resolve.
135     * @return A {@link FileName} object representing the resolved file name.
136     * @throws FileSystemException If the name is invalid.
137     */
138    FileName resolveName(final FileName root, final String name) throws FileSystemException;
139
140    /**
141     * Resolves a name, relative to the "root" file name.  Refer to {@link NameScope}
142     * for a description of how names are resolved.
143     *
144     * @param root the base filename
145     * @param name  The name to resolve.
146     * @param scope The {@link NameScope} to use when resolving the name.
147     * @return A {@link FileName} object representing the resolved file name.
148     * @throws FileSystemException If the name is invalid.
149     */
150    FileName resolveName(final FileName root, String name, NameScope scope)
151        throws FileSystemException;
152
153    /**
154     * Converts a local file into a {@link FileObject}.
155     *
156     * @param file The file to convert.
157     * @return The {@link FileObject} that represents the local file.  Never
158     *         returns null.
159     * @throws FileSystemException On error converting the file.
160     */
161    FileObject toFileObject(File file) throws FileSystemException;
162
163    /**
164     * Creates a layered file system.  A layered file system is a file system
165     * that is created from the contents of a file, such as a zip or tar file.
166     *
167     * @param provider The name of the file system provider to use.  This name
168     *                 is the same as the scheme used in URI to identify the provider.
169     * @param file     The file to use to create the file system.
170     * @return The root file of the new file system.
171     * @throws FileSystemException On error creating the file system.
172     */
173    FileObject createFileSystem(String provider, FileObject file)
174        throws FileSystemException;
175
176    /**
177     * Closes the given filesystem.<br />
178     * If you use VFS as singleton it is VERY dangerous to call this method.
179     * @param filesystem The FileSystem to close.
180     */
181    void closeFileSystem(FileSystem filesystem);
182
183    /**
184     * Creates a layered file system.  A layered file system is a file system
185     * that is created from the contents of a file, such as a zip or tar file.
186     *
187     * @param file The file to use to create the file system.
188     * @return The root file of the new file system.
189     * @throws FileSystemException On error creating the file system.
190     */
191    FileObject createFileSystem(FileObject file) throws FileSystemException;
192
193    /**
194     * Creates an empty virtual file system.  Can be populated by adding
195     * junctions to it.
196     *
197     * @param rootUri The root URI to use for the new file system.  Can be null.
198     * @return The root file of the new file system.
199     * @throws FileSystemException if an error occurs creating the VirtualFileSystem.
200     */
201    FileObject createVirtualFileSystem(String rootUri) throws FileSystemException;
202
203    /**
204     * Creates a virtual file system.  The file system will contain a junction
205     * at the fs root to the supplied root file.
206     *
207     * @param rootFile The root file to backs the file system.
208     * @return The root of the new file system.
209     * @throws FileSystemException if an error occurs creating the VirtualFileSystem.
210     */
211    FileObject createVirtualFileSystem(FileObject rootFile) throws FileSystemException;
212
213    /**
214     * Returns a streamhandler factory to enable URL lookup using this
215     * FileSystemManager.
216     * @return the URLStreamHandlerFactory.
217     */
218    URLStreamHandlerFactory getURLStreamHandlerFactory();
219
220    /**
221     * Determines if a layered file system can be created for a given file.
222     *
223     * @param file The file to check for.
224     * @return true if the FileSystem can be created.
225     * @throws FileSystemException if an error occurs.
226     */
227    boolean canCreateFileSystem(FileObject file) throws FileSystemException;
228
229    /**
230     * Get the cache used to cache fileobjects.
231     * @return The FilesCache.
232     */
233    FilesCache getFilesCache();
234
235    /**
236     * Get the cache strategy used.
237     * @return the CacheStrategy.
238     */
239    CacheStrategy getCacheStrategy();
240
241    /**
242     * Get the file object decorator used.
243     * @return the file object decorator Class.
244     */
245    Class<?> getFileObjectDecorator();
246
247    /**
248     * The constructor associated to the fileObjectDecorator.
249     * We cache it here for performance reasons.
250     * @return the Constructor associated with the FileObjectDecorator.
251     */
252    Constructor<?> getFileObjectDecoratorConst();
253
254    /**
255     * The class to use to determine the content-type (mime-type).
256     * @return the FileContentInfoFactory.
257     */
258    FileContentInfoFactory getFileContentInfoFactory();
259
260    /**
261     * Returns true if this manager has a provider for a particular scheme.
262     * @param scheme The scheme for which a provider should be checked.
263     * @return true if a provider for the scheme is available.
264     */
265    boolean hasProvider(final String scheme);
266
267    /**
268     * Get the schemes currently available.
269     * @return An array of available scheme names that are supported.
270     */
271    String[] getSchemes();
272
273    /**
274     * Get the capabilities for a given scheme.
275     *
276     * @param scheme The scheme to use to locate the provider's capabilities.
277     * @return A Collection of the various capabilities.
278     * @throws FileSystemException if the given scheme is not konwn.
279     */
280    Collection<Capability> getProviderCapabilities(final String scheme) throws FileSystemException;
281
282    /**
283     * Sets the logger to use.
284     * @param log The logger to use.
285     */
286    void setLogger(final Log log);
287
288    /**
289     * Get the configuration builder for the given scheme.
290     *
291     * @param scheme The schem to use to obtain the FileSystemConfigBuidler.
292     * @return A FileSystemConfigBuilder appropriate for the given scheme.
293     * @throws FileSystemException if the given scheme is not konwn.
294     */
295    FileSystemConfigBuilder getFileSystemConfigBuilder(final String scheme) throws FileSystemException;
296
297    /**
298     * Resolve the uri to a filename.
299     *
300     * @param uri The uri to resolve.
301     * @return A FileName that matches the uri.
302     * @throws FileSystemException if this is not possible.
303     */
304    FileName resolveURI(String uri) throws FileSystemException;
305
306    // -- OPERATIONS --
307    /**
308     * Adds the specified FileOperationProvider for the specified scheme.
309     * Several FileOperationProvider's might be registered for the same scheme.
310     * For example, for "file" scheme we can register SvnWsOperationProvider and
311     * CvsOperationProvider.
312     *
313     * @param scheme The scheme assoicated with this provider.
314     * @param operationProvider The FileOperationProvider to add.
315     * @throws FileSystemException if an error occurs.
316     */
317    void addOperationProvider(final String scheme, final FileOperationProvider operationProvider)
318        throws FileSystemException;
319
320    /**
321     * @see FileSystemManager#addOperationProvider(String, org.apache.commons.vfs2.operations.FileOperationProvider)
322     *
323     * @param schemes The schemes that will be associated with the provider.
324     * @param operationProvider The FileOperationProvider to add.
325     * @throws FileSystemException if an error occurs.
326     */
327    void addOperationProvider(final String[] schemes, final FileOperationProvider operationProvider)
328        throws FileSystemException;
329
330
331    /**
332     * @param scheme the scheme for wich we want to get the list af registered providers.
333     *
334     * @return the registered FileOperationProviders for the specified scheme.
335     * If there were no providers registered for the scheme, it returns null.
336     *
337     * @throws FileSystemException if an error occurs.
338     */
339    FileOperationProvider[] getOperationProviders(final String scheme) throws FileSystemException;
340    
341    /**
342     * Resolves a URI into a {@link FileObject}.
343     *
344     * @param uri The URI to convert.
345     * @return The {@link FileObject} that represents the URI.  Never
346     *         returns null.
347     * @throws FileSystemException On error converting the file.
348     * @since 2.1
349     */
350    FileObject resolveFile(URI uri) throws FileSystemException;
351
352    /**
353     * Resolves a URL into a {@link FileObject}.
354     *
355     * @param url The URL to convert.
356     * @return The {@link FileObject} that represents the URL.  Never
357     *         returns null.
358     * @throws FileSystemException On error converting the file.
359     * @since 2.1
360     */
361    FileObject resolveFile(URL url) throws FileSystemException;
362
363}