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;
18  
19  import java.io.File;
20  import java.lang.reflect.Constructor;
21  import java.net.URI;
22  import java.net.URL;
23  import java.net.URLStreamHandlerFactory;
24  import java.util.Collection;
25  
26  import org.apache.commons.logging.Log;
27  import org.apache.commons.vfs2.operations.FileOperationProvider;
28  
29  /**
30   * A FileSystemManager manages a set of file systems.  This interface is
31   * used to locate a {@link FileObject} by name from one of those file systems.
32   * <p>
33   * To locate a {@link FileObject}, use one of the {@code resolveFile()}
34   * methods.
35   *
36   * <h2><a name="naming">File Naming</a></h2>
37   *
38   * A file system manager can recognise several types of file names:
39   * <ul>
40   * <li>Absolute URI.  These must start with a scheme, such as
41   * {@code file:} or {@code ftp:}, followed by a scheme dependent
42   * file name.  Some examples: {@code file:/c:/somefile} or
43   * {@code ftp://somewhere.org/somefile}.</li>
44   * <li>Absolute local file name.  For example,
45   * {@code /home/someuser/a-file} or {@code c:\dir\somefile.html}.
46   * Elements in the name can be separated using any of the following
47   * characters: {@code /}, {@code \}, or the native file separator
48   * character. For example, the following file names are the same:
49   * {@code c:\somedir\somefile.xml} and {@code c:/somedir/somefile.xml}.</li>
50   * <li>Relative path.  For example: {@code ../somefile} or
51   * {@code somedir/file.txt}. The file system manager resolves relative
52   * paths against its <i>base file</i>.  Elements in the relative path can be
53   * separated using {@code /}, {@code \}, or file system specific
54   * separator characters. Relative paths may also contain {@code ..} and
55   * {@code .} elements. See {@link FileObject#resolveFile} for more
56   * details.</li>
57   * </ul>
58   */
59  public interface FileSystemManager
60  {
61      /**
62       * Returns the base file used to resolve relative paths.
63       *
64       * @return The base FileObject.
65       * @throws FileSystemException if an error occurs.
66       */
67      FileObject getBaseFile() throws FileSystemException;
68  
69      /**
70       * Locates a file by name.  Equivalent to calling
71       * {@code resolveFile(getBaseFile(), name)}.
72       *
73       * @param name The name of the file.
74       * @return The file.  Never returns null.
75       * @throws FileSystemException On error parsing the file name.
76       */
77      FileObject resolveFile(String name) throws FileSystemException;
78  
79      /**
80       * Locates a file by name.  Equivalent to calling
81       * {@code resolveFile(getBaseFile(), name)}.
82       *
83       * @param name              The name of the file.
84       * @param fileSystemOptions The FileSystemOptions used for FileSystem creation.
85       *                          All files that are later resolved relative to the
86       *                          returned {@code FileObject} share the options.
87       * @return The file.  Never returns null.
88       * @throws FileSystemException On error parsing the file name.
89       */
90      FileObject resolveFile(String name, FileSystemOptions fileSystemOptions)
91          throws FileSystemException;
92  
93      /**
94       * Locates a file by name.  The name is resolved as described
95       * <a href="#naming">above</a>.  That is, the name can be either
96       * an absolute URI, an absolute file name, or a relative path to
97       * be resolved against {@code baseFile}.
98       * <p>
99       * 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 }