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 used to locate a {@link FileObject} by name from
31   * one of those file systems.
32   * <p>
33   * To locate a {@link FileObject}, use one of the {@code resolveFile()} methods.
34   * </p>
35   *
36   * <h2><a id="naming">File Naming</a></h2>
37   * <p>
38   * A file system manager can recognise several types of file names:
39   * </p>
40   * <ul>
41   * <li>Absolute URI. These must start with a scheme, such as {@code file:} or {@code ftp:}, followed by a scheme
42   * dependent file name. Some examples: {@code file:/c:/somefile} or {@code ftp://somewhere.org/somefile}.</li>
43   * <li>Absolute local file name. For example, {@code /home/someuser/a-file} or {@code c:\dir\somefile.html}. Elements in
44   * the name can be separated using any of the following characters: {@code /}, {@code \}, or the native file separator
45   * character. For example, the following file names are the same: {@code c:\somedir\somefile.xml} and
46   * {@code c:/somedir/somefile.xml}.</li>
47   * <li>Relative path. For example: {@code ../somefile} or {@code somedir/file.txt}. The file system manager resolves
48   * relative paths against its <i>base file</i>. Elements in the relative path can be separated using {@code /},
49   * {@code \}, or file system specific separator characters. Relative paths may also contain {@code ..} and {@code .}
50   * elements. See {@link FileObject#resolveFile} for more details.</li>
51   * </ul>
52   */
53  public interface FileSystemManager extends AutoCloseable {
54  
55      /**
56       * Adds the specified FileOperationProvider for the specified scheme.
57       * <p>
58       * Several FileOperationProvider's might be registered for the same scheme. For example, for {@code "file"} scheme
59       * we can register {@code SvnWsOperationProvider} and {@code CvsOperationProvider.}
60       * </p>
61       *
62       * @param scheme The scheme assoicated with this provider.
63       * @param operationProvider The FileOperationProvider to add.
64       * @throws FileSystemException if an error occurs.
65       */
66      void addOperationProvider(String scheme, FileOperationProvider operationProvider) throws FileSystemException;
67  
68      /**
69       * @see FileSystemManager#addOperationProvider(String, org.apache.commons.vfs2.operations.FileOperationProvider)
70       *
71       * @param schemes The schemes that will be associated with the provider.
72       * @param operationProvider The FileOperationProvider to add.
73       * @throws FileSystemException if an error occurs.
74       */
75      void addOperationProvider(String[] schemes, FileOperationProvider operationProvider) throws FileSystemException;
76  
77      /**
78       * Determines if a layered file system can be created for a given file.
79       *
80       * @param file The file to check for.
81       * @return true if the FileSystem can be created.
82       * @throws FileSystemException if an error occurs.
83       */
84      boolean canCreateFileSystem(FileObject file) throws FileSystemException;
85  
86      /**
87       * Closes this file system manager.
88       *
89       * @since 2.5.0
90       */
91      @Override
92      default void close() {
93          // noop
94      }
95  
96      /**
97       * Closes the given file system.
98       * <p>
99       * If you use VFS as singleton it is VERY dangerous to call this method.
100      * </p>
101      *
102      * @param fileSystem The FileSystem to close.
103      */
104     void closeFileSystem(FileSystem fileSystem);
105 
106     /**
107      * Creates a layered file system. A layered file system is a file system that is created from the contents of a
108      * file, such as a zip or tar file.
109      *
110      * @param file The file to use to create the file system.
111      * @return The root file of the new file system.
112      * @throws FileSystemException On error creating the file system.
113      */
114     FileObject/org/apache/commons/vfs2/FileObject.html#FileObject">FileObject createFileSystem(FileObject file) throws FileSystemException;
115 
116     /**
117      * Creates a layered file system. A layered file system is a file system that is created from the contents of a
118      * file, such as a zip or tar file.
119      *
120      * @param provider The name of the file system provider to use. This name is the same as the scheme used in URI to
121      *            identify the provider.
122      * @param file The file to use to create the file system.
123      * @return The root file of the new file system.
124      * @throws FileSystemException On error creating the file system.
125      */
126     FileObjectns/vfs2/FileObject.html#FileObject">FileObject createFileSystem(String provider, FileObject file) throws FileSystemException;
127 
128     /**
129      * Creates a virtual file system. The file system will contain a junction at the fs root to the supplied root file.
130      *
131      * @param rootFile The root file to backs the file system.
132      * @return The root of the new file system.
133      * @throws FileSystemException if an error occurs creating the VirtualFileSystem.
134      */
135     FileObjectache/commons/vfs2/FileObject.html#FileObject">FileObject createVirtualFileSystem(FileObject rootFile) throws FileSystemException;
136 
137     /**
138      * Creates an empty virtual file system. Can be populated by adding junctions to it.
139      *
140      * @param rootUri The root URI to use for the new file system. Can be null.
141      * @return The root file of the new file system.
142      * @throws FileSystemException if an error occurs creating the VirtualFileSystem.
143      */
144     FileObject createVirtualFileSystem(String rootUri) throws FileSystemException;
145 
146     /**
147      * Returns the base file used to resolve relative paths.
148      *
149      * @return The base FileObject.
150      * @throws FileSystemException if an error occurs.
151      */
152     FileObject getBaseFile() throws FileSystemException;
153 
154     /**
155      * Gets the cache strategy used.
156      *
157      * @return the CacheStrategy.
158      */
159     CacheStrategy getCacheStrategy();
160 
161     /**
162      * Gets the class to use to determine the content-type (mime-type).
163      *
164      * @return the FileContentInfoFactory.
165      */
166     FileContentInfoFactory getFileContentInfoFactory();
167 
168     /**
169      * Gets the file object decorator used.
170      *
171      * @return the file object decorator Class.
172      */
173     Class<?> getFileObjectDecorator();
174 
175     /**
176      * Gets the constructor associated to the fileObjectDecorator. We cache it here for performance reasons.
177      *
178      * @return the Constructor associated with the FileObjectDecorator.
179      */
180     Constructor<?> getFileObjectDecoratorConst();
181 
182     /**
183      * Gets the cache used to cache file objects.
184      *
185      * @return The FilesCache.
186      */
187     FilesCache getFilesCache();
188 
189     /**
190      * Gets the configuration builder for the given scheme.
191      *
192      * @param scheme The schem to use to obtain the FileSystemConfigBuidler.
193      * @return A FileSystemConfigBuilder appropriate for the given scheme.
194      * @throws FileSystemException if the given scheme is not konwn.
195      */
196     FileSystemConfigBuilder getFileSystemConfigBuilder(String scheme) throws FileSystemException;
197 
198     /**
199      * Gets Providers for file operations.
200      *
201      * @param scheme the scheme for wich we want to get the list af registered providers.
202      *
203      * @return the registered FileOperationProviders for the specified scheme. If there were no providers registered for
204      *         the scheme, it returns null.
205      *
206      * @throws FileSystemException if an error occurs.
207      */
208     FileOperationProvider[] getOperationProviders(String scheme) throws FileSystemException;
209 
210     /**
211      * Gets the capabilities for a given scheme.
212      *
213      * @param scheme The scheme to use to locate the provider's capabilities.
214      * @return A Collection of the various capabilities.
215      * @throws FileSystemException if the given scheme is not konwn.
216      */
217     Collection<Capability> getProviderCapabilities(String scheme) throws FileSystemException;
218 
219     /**
220      * Gets the schemes currently available.
221      *
222      * @return An array of available scheme names that are supported.
223      */
224     String[] getSchemes();
225 
226     /**
227      * Returns a stream handler factory to enable URL lookup using this FileSystemManager.
228      *
229      * @return the URLStreamHandlerFactory.
230      */
231     URLStreamHandlerFactory getURLStreamHandlerFactory();
232 
233     /**
234      * Returns true if this manager has a provider for a particular scheme.
235      *
236      * @param scheme The scheme for which a provider should be checked.
237      * @return true if a provider for the scheme is available.
238      */
239     boolean hasProvider(String scheme);
240 
241     /**
242      * Locates a file by name. See {@link #resolveFile(FileObject, String)} for details.
243      *
244      * @param baseFile The base file to use to resolve relative paths. Must not be {@code null}, not even if the
245      *            <i>name</i> is absolute.
246      * @param name The name of the file.
247      * @return The file. Never returns null.
248      * @throws FileSystemException On error parsing the file name.
249      */
250     FileObject resolveFile(File baseFile, String name) throws FileSystemException;
251 
252     /**
253      * Locates a file by name. The name is resolved as described <a href="#naming">above</a>. That is, the name can be
254      * either an absolute URI, an absolute file name, or a relative path to be resolved against {@code baseFile}.
255      * <p>
256      * Note that the file does not have to exist when this method is called.
257      * </p>
258      *
259      * @param baseFile The base file to use to resolve relative paths. May be null if the name is an absolute file name.
260      * @param name The name of the file.
261      * @return The file. Never returns null.
262      * @throws FileSystemException On error parsing the file name.
263      */
264     FileObject../../org/apache/commons/vfs2/FileObject.html#FileObject">FileObject resolveFile(FileObject baseFile, String name) throws FileSystemException;
265 
266     /**
267      * Locates a file by name. Equivalent to calling {@code resolveFile(getBaseFile(), name)}.
268      *
269      * @param name The name of the file.
270      * @return The file. Never returns null.
271      * @throws FileSystemException On error parsing the file name.
272      */
273     FileObject resolveFile(String name) throws FileSystemException;
274 
275     /**
276      * Locates a file by name. Equivalent to calling {@code resolveFile(getBaseFile(), name)}.
277      *
278      * @param name The name of the file.
279      * @param fileSystemOptions The FileSystemOptions used for FileSystem creation. All files that are later resolved
280      *            relative to the returned {@code FileObject} share the options.
281      * @return The file. Never returns null.
282      * @throws FileSystemException On error parsing the file name.
283      */
284     FileObject resolveFile(String name, FileSystemOptions fileSystemOptions) throws FileSystemException;
285 
286     /**
287      * Resolves a URI into a {@link FileObject}.
288      *
289      * @param uri The URI to convert.
290      * @return The {@link FileObject} that represents the URI. Never returns null.
291      * @throws FileSystemException On error converting the file.
292      * @since 2.1
293      */
294     FileObject resolveFile(URI uri) throws FileSystemException;
295 
296     /**
297      * Resolves a URL into a {@link FileObject}.
298      *
299      * @param url The URL to convert.
300      * @return The {@link FileObject} that represents the URL. Never returns null.
301      * @throws FileSystemException On error converting the file.
302      * @since 2.1
303      */
304     FileObject resolveFile(URL url) throws FileSystemException;
305 
306     /**
307      * Resolves a name, relative to this file name. Equivalent to calling
308      * {@code resolveName( path, NameScope.FILE_SYSTEM )}.
309      *
310      * @param root the base file name
311      * @param name The name to resolve.
312      * @return A {@link FileName} object representing the resolved file name.
313      * @throws FileSystemException If the name is invalid.
314      */
315     FileName./../../org/apache/commons/vfs2/FileName.html#FileName">FileName resolveName(FileName root, String name) throws FileSystemException;
316 
317     /**
318      * Resolves a name, relative to the "root" file name. Refer to {@link NameScope} for a description of how names are
319      * resolved.
320      *
321      * @param root the base file name
322      * @param name The name to resolve.
323      * @param scope The {@link NameScope} to use when resolving the name.
324      * @return A {@link FileName} object representing the resolved file name.
325      * @throws FileSystemException If the name is invalid.
326      */
327     FileName./../../org/apache/commons/vfs2/FileName.html#FileName">FileName resolveName(FileName root, String name, NameScope scope) throws FileSystemException;
328 
329     /**
330      * Resolves the URI to a file name.
331      *
332      * @param uri The URI to resolve.
333      * @return A FileName that matches the URI.
334      * @throws FileSystemException if this is not possible.
335      */
336     FileName resolveURI(String uri) throws FileSystemException;
337 
338     /**
339      * Sets the logger to use.
340      *
341      * @param log The logger to use.
342      */
343     void setLogger(Log log);
344 
345     /**
346      * Converts a local file into a {@link FileObject}.
347      *
348      * @param file The file to convert.
349      * @return The {@link FileObject} that represents the local file. Never returns null.
350      * @throws FileSystemException On error converting the file.
351      */
352     FileObject toFileObject(File file) throws FileSystemException;
353 
354 }