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 */
017 package org.apache.commons.vfs2;
018
019 import java.io.File;
020 import java.lang.reflect.Constructor;
021 import java.net.URLStreamHandlerFactory;
022 import java.util.Collection;
023
024 import org.apache.commons.logging.Log;
025 import org.apache.commons.vfs2.operations.FileOperationProvider;
026
027 /**
028 * A FileSystemManager manages a set of file systems. This interface is
029 * used to locate a {@link FileObject} by name from one of those file systems.
030 * <p/>
031 * <p>To locate a {@link FileObject}, use one of the <code>resolveFile()</code>
032 * methods.</p>
033 * <p/>
034 * <h4><a name="naming">File Naming</a></h4>
035 * <p/>
036 * <p>A file system manager can recognise several types of file names:
037 * <p/>
038 * <ul>
039 * <p/>
040 * <li><p>Absolute URI. These must start with a scheme, such as
041 * <code>file:</code> or <code>ftp:</code>, followed by a scheme dependent
042 * file name. Some examples:</p>
043 * <pre>
044 * file:/c:/somefile
045 * ftp://somewhere.org/somefile
046 * </pre>
047 * <p/>
048 * <li><p>Absolute local file name. For example,
049 * <code>/home/someuser/a-file</code> or <code>c:\dir\somefile.html</code>.
050 * Elements in the name can be separated using any of the following
051 * characters: <code>/</code>, <code>\</code>, or the native file separator
052 * character. For example, the following file names are the same:</p>
053 * <pre>
054 * c:\somedir\somefile.xml
055 * c:/somedir/somefile.xml
056 * </pre>
057 * <p/>
058 * <li><p>Relative path. For example: <code>../somefile</code> or
059 * <code>somedir/file.txt</code>. The file system manager resolves relative
060 * paths against its <i>base file</i>. Elements in the relative path can be
061 * separated using <code>/</code>, <code>\</code>, or file system specific
062 * separator characters. Relative paths may also contain <code>..</code> and
063 * <code>.</code> elements. See {@link FileObject#resolveFile} for more
064 * details.</p>
065 * <p/>
066 * </ul>
067 *
068 * @author <a href="http://commons.apache.org/vfs/team-list.html">Commons VFS team</a>
069 */
070 public 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(uri, getBaseName())</code>.
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(uri, getBaseName())</code>.
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</code>.
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 )</code>.
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 }