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