1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.commons.vfs;
18
19 import org.apache.commons.logging.Log;
20
21 import java.io.File;
22 import java.net.URLStreamHandlerFactory;
23 import java.util.Collection;
24 import java.lang.reflect.Constructor;
25
26 import org.apache.commons.vfs.operations.FileOperationProvider;
27
28 /***
29 * A FileSystemManager manages a set of file systems. This interface is
30 * used to locate a {@link FileObject} by name from one of those file systems.
31 * <p/>
32 * <p>To locate a {@link FileObject}, use one of the <code>resolveFile()</code>
33 * methods.</p>
34 * <p/>
35 * <h4><a name="naming">File Naming</a></h4>
36 * <p/>
37 * <p>A file system manager can recognise several types of file names:
38 * <p/>
39 * <ul>
40 * <p/>
41 * <li><p>Absolute URI. These must start with a scheme, such as
42 * <code>file:</code> or <code>ftp:</code>, followed by a scheme dependent
43 * file name. Some examples:</p>
44 * <pre>
45 * file:/c:/somefile
46 * ftp://somewhere.org/somefile
47 * </pre>
48 * <p/>
49 * <li><p>Absolute local file name. For example,
50 * <code>/home/someuser/a-file</code> or <code>c:\dir\somefile.html</code>.
51 * Elements in the name can be separated using any of the following
52 * characters: <code>/</code>, <code>\</code>, or the native file separator
53 * character. For example, the following file names are the same:</p>
54 * <pre>
55 * c:\somedir\somefile.xml
56 * c:/somedir/somefile.xml
57 * </pre>
58 * <p/>
59 * <li><p>Relative path. For example: <code>../somefile</code> or
60 * <code>somedir/file.txt</code>. The file system manager resolves relative
61 * paths against its <i>base file</i>. Elements in the relative path can be
62 * separated using <code>/</code>, <code>\</code>, or file system specific
63 * separator characters. Relative paths may also contain <code>..</code> and
64 * <code>.</code> elements. See {@link FileObject#resolveFile} for more
65 * details.</p>
66 * <p/>
67 * </ul>
68 *
69 * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
70 * @version $Revision: 484648 $ $Date: 2006-12-08 17:18:36 +0100 (Fr, 08 Dez 2006) $
71 */
72 public interface FileSystemManager
73 {
74 /***
75 * Returns the base file used to resolve relative paths.
76 */
77 public FileObject getBaseFile() throws FileSystemException;
78
79 /***
80 * Locates a file by name. Equivalent to calling
81 * <code>resolveFile(uri, getBaseName())</code>.
82 *
83 * @param name The name of the file.
84 * @return The file. Never returns null.
85 * @throws FileSystemException On error parsing the file name.
86 */
87 public FileObject resolveFile(String name)
88 throws FileSystemException;
89
90 /***
91 * Locates a file by name. Equivalent to calling
92 * <code>resolveFile(uri, getBaseName())</code>.
93 *
94 * @param name The name of the file.
95 * @param fileSystemOptions The FileSystemOptions used for FileSystem creation
96 * @return The file. Never returns null.
97 * @throws FileSystemException On error parsing the file name.
98 */
99 public FileObject resolveFile(String name, FileSystemOptions fileSystemOptions)
100 throws FileSystemException;
101
102 /***
103 * Locates a file by name. The name is resolved as described
104 * <a href="#naming">above</a>. That is, the name can be either
105 * an absolute URI, an absolute file name, or a relative path to
106 * be resolved against <code>baseFile</code>.
107 * <p/>
108 * <p>Note that the file does not have to exist when this method is called.
109 *
110 * @param name The name of the file.
111 * @param baseFile The base file to use to resolve relative paths.
112 * May be null.
113 * @return The file. Never returns null.
114 * @throws FileSystemException On error parsing the file name.
115 */
116 public FileObject resolveFile(FileObject baseFile, String name)
117 throws FileSystemException;
118
119 /***
120 * Locates a file by name. See {@link #resolveFile(FileObject, String)}
121 * for details.
122 *
123 * @param baseFile The base file to use to resolve relative paths.
124 * May be null.
125 * @param name The name of the file.
126 * @return The file. Never returns null.
127 * @throws FileSystemException On error parsing the file name.
128 */
129 public FileObject resolveFile(File baseFile, String name)
130 throws FileSystemException;
131
132 /***
133 * Resolves a name, relative to this file name. Equivalent to calling
134 * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
135 *
136 * @param root the base filename
137 * @param name The name to resolve.
138 * @return A {@link FileName} object representing the resolved file name.
139 * @throws FileSystemException If the name is invalid.
140 */
141 public FileName resolveName(final FileName root, final String name) throws FileSystemException;
142
143 /***
144 * Resolves a name, relative to the "root" file name. Refer to {@link NameScope}
145 * for a description of how names are resolved.
146 *
147 * @param root the base filename
148 * @param name The name to resolve.
149 * @param scope The {@link NameScope} to use when resolving the name.
150 * @return A {@link FileName} object representing the resolved file name.
151 * @throws FileSystemException If the name is invalid.
152 */
153 public FileName resolveName(final FileName root, String name, NameScope scope)
154 throws FileSystemException;
155
156 /***
157 * Converts a local file into a {@link FileObject}.
158 *
159 * @param file The file to convert.
160 * @return The {@link FileObject} that represents the local file. Never
161 * returns null.
162 * @throws FileSystemException On error converting the file.
163 */
164 public FileObject toFileObject(File file)
165 throws FileSystemException;
166
167 /***
168 * Creates a layered file system. A layered file system is a file system
169 * that is created from the contents of a file, such as a zip or tar file.
170 *
171 * @param provider The name of the file system provider to use. This name
172 * is the same as the scheme used in URI to identify the provider.
173 * @param file The file to use to create the file system.
174 * @return The root file of the new file system.
175 * @throws FileSystemException On error creating the file system.
176 */
177 public FileObject createFileSystem(String provider, FileObject file)
178 throws FileSystemException;
179
180 /***
181 * Closes the given filesystem.<br />
182 * If you use VFS as singleton it is VERY dangerous to call this method.
183 */
184 public void closeFileSystem(FileSystem filesystem);
185
186 /***
187 * Creates a layered file system. A layered file system is a file system
188 * that is created from the contents of a file, such as a zip or tar file.
189 *
190 * @param file The file to use to create the file system.
191 * @return The root file of the new file system.
192 * @throws FileSystemException On error creating the file system.
193 */
194 public FileObject createFileSystem(FileObject file)
195 throws FileSystemException;
196
197 /***
198 * Creates an empty virtual file system. Can be populated by adding
199 * junctions to it.
200 *
201 * @param rootUri The root URI to use for the new file system. Can be null.
202 * @return The root file of the new file system.
203 */
204 public FileObject createVirtualFileSystem(String rootUri)
205 throws FileSystemException;
206
207 /***
208 * Creates a virtual file system. The file system will contain a junction
209 * at the fs root to the supplied root file.
210 *
211 * @param rootFile The root file to backs the file system.
212 * @return The root of the new file system.
213 */
214 public FileObject createVirtualFileSystem(FileObject rootFile)
215 throws FileSystemException;
216
217 /***
218 * Returns a streamhandler factory to enable URL lookup using this
219 * FileSystemManager.
220 */
221 public URLStreamHandlerFactory getURLStreamHandlerFactory();
222
223 /***
224 * Determines if a layered file system can be created for a given file.
225 *
226 * @param file The file to check for.
227 */
228 public boolean canCreateFileSystem(FileObject file) throws FileSystemException;
229
230 /***
231 * Get the cache used to cache fileobjects.
232 */
233 public FilesCache getFilesCache();
234
235 /***
236 * Get the cache strategy used
237 */
238 public CacheStrategy getCacheStrategy();
239
240 /***
241 * Get the file object decorator used
242 */
243 public Class getFileObjectDecorator();
244
245 /***
246 * The constructor associated to the fileObjectDecorator.
247 * We cache it here for performance reasons.
248 */
249 public Constructor getFileObjectDecoratorConst();
250
251 /***
252 * The class to use to determine the content-type (mime-type)
253 */
254 public FileContentInfoFactory getFileContentInfoFactory();
255
256 /***
257 * Get the schemes currently available.
258 */
259 public String[] getSchemes();
260
261 /***
262 * Get the capabilities for a given scheme.
263 *
264 * @throws FileSystemException if the given scheme is not konwn
265 */
266 public Collection getProviderCapabilities(final String scheme) throws FileSystemException;
267
268 /***
269 * Sets the logger to use.
270 */
271 public void setLogger(final Log log);
272
273 /***
274 * Get the configuration builder for the given scheme
275 *
276 * @throws FileSystemException if the given scheme is not konwn
277 */
278 public FileSystemConfigBuilder getFileSystemConfigBuilder(final String scheme) throws FileSystemException;
279
280 /***
281 * Resolve the uri to a filename
282 *
283 * @throws FileSystemException if this is not possible
284 */
285 public FileName resolveURI(String uri) throws FileSystemException;
286
287
288 /***
289 * Adds the specified FileOperationProvider for the specified scheme.
290 * Several FileOperationProvider's might be registered for the same scheme.
291 * For example, for "file" scheme we can register SvnWsOperationProvider and
292 * CvsOperationProvider.
293 *
294 * @param scheme
295 * @param operationProvider
296 * @throws FileSystemException
297 */
298 public void addOperationProvider(final String scheme, final FileOperationProvider operationProvider) throws FileSystemException;
299
300 /***
301 * @see FileSystemManager#addOperationProvider(String, org.apache.commons.vfs.operations.FileOperationProvider)
302 *
303 * @param schemes
304 * @param operationProvider
305 * @throws FileSystemException
306 */
307 public void addOperationProvider(final String[] schemes, final FileOperationProvider operationProvider) throws FileSystemException;
308
309
310 /***
311 * @param scheme the scheme for wich we want to get the list af registered providers.
312 *
313 * @return the registered FileOperationProviders for the specified scheme.
314 * If there were no providers registered for the scheme, it returns null.
315 *
316 * @throws FileSystemException
317 */
318 public FileOperationProvider[] getOperationProviders(final String scheme) throws FileSystemException;
319 }