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