Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.vfs2; import java.io.File; import java.lang.reflect.Constructor; import java.net.URI; import java.net.URL; import java.net.URLStreamHandlerFactory; import java.util.Collection; import org.apache.commons.logging.Log; import org.apache.commons.vfs2.operations.FileOperationProvider; /** * A FileSystemManager manages a set of file systems. This interface is * used to locate a {@link FileObject} by name from one of those file systems. * <p> * To locate a {@link FileObject}, use one of the {@code resolveFile()} * methods. * * <h2><a name="naming">File Naming</a></h2> * * A file system manager can recognise several types of file names: * <ul> * <li>Absolute URI. These must start with a scheme, such as * {@code file:} or {@code ftp:}, followed by a scheme dependent * file name. Some examples: {@code file:/c:/somefile} or * {@code ftp://somewhere.org/somefile}.</li> * <li>Absolute local file name. For example, * {@code /home/someuser/a-file} or {@code c:\dir\somefile.html}. * Elements in the name can be separated using any of the following * characters: {@code /}, {@code \}, or the native file separator * character. For example, the following file names are the same: * {@code c:\somedir\somefile.xml} and {@code c:/somedir/somefile.xml}.</li> * <li>Relative path. For example: {@code ../somefile} or * {@code somedir/file.txt}. The file system manager resolves relative * paths against its <i>base file</i>. Elements in the relative path can be * separated using {@code /}, {@code \}, or file system specific * separator characters. Relative paths may also contain {@code ..} and * {@code .} elements. See {@link FileObject#resolveFile} for more * details.</li> * </ul> */ public interface FileSystemManager { /** * Returns the base file used to resolve relative paths. * * @return The base FileObject. * @throws FileSystemException if an error occurs. */ FileObject getBaseFile() throws FileSystemException; /** * Locates a file by name. Equivalent to calling * {@code resolveFile(getBaseFile(), name)}. * * @param name The name of the file. * @return The file. Never returns null. * @throws FileSystemException On error parsing the file name. */ FileObject resolveFile(String name) throws FileSystemException; /** * Locates a file by name. Equivalent to calling * {@code resolveFile(getBaseFile(), name)}. * * @param name The name of the file. * @param fileSystemOptions The FileSystemOptions used for FileSystem creation. * All files that are later resolved relative to the * returned {@code FileObject} share the options. * @return The file. Never returns null. * @throws FileSystemException On error parsing the file name. */ FileObject resolveFile(String name, FileSystemOptions fileSystemOptions) throws FileSystemException; /** * Locates a file by name. The name is resolved as described * <a href="#naming">above</a>. That is, the name can be either * an absolute URI, an absolute file name, or a relative path to * be resolved against {@code baseFile}. * <p> * Note that the file does not have to exist when this method is called. * * @param baseFile The base file to use to resolve relative paths. * May be null if the name is an absolute file name. * @param name The name of the file. * @return The file. Never returns null. * @throws FileSystemException On error parsing the file name. */ FileObject resolveFile(FileObject baseFile, String name) throws FileSystemException; /** * Locates a file by name. See {@link #resolveFile(FileObject, String)} * for details. * * @param baseFile The base file to use to resolve relative paths. * Must not be {@code null}, not even if the <i>name</i> is absolute. * @param name The name of the file. * @return The file. Never returns null. * @throws FileSystemException On error parsing the file name. */ FileObject resolveFile(File baseFile, String name) throws FileSystemException; /** * Resolves a name, relative to this file name. Equivalent to calling * {@code resolveName( path, NameScope.FILE_SYSTEM )}. * * @param root the base filename * @param name The name to resolve. * @return A {@link FileName} object representing the resolved file name. * @throws FileSystemException If the name is invalid. */ FileName resolveName(FileName root, String name) throws FileSystemException; /** * Resolves a name, relative to the "root" file name. Refer to {@link NameScope} * for a description of how names are resolved. * * @param root the base filename * @param name The name to resolve. * @param scope The {@link NameScope} to use when resolving the name. * @return A {@link FileName} object representing the resolved file name. * @throws FileSystemException If the name is invalid. */ FileName resolveName(FileName root, String name, NameScope scope) throws FileSystemException; /** * Converts a local file into a {@link FileObject}. * * @param file The file to convert. * @return The {@link FileObject} that represents the local file. Never * returns null. * @throws FileSystemException On error converting the file. */ FileObject toFileObject(File file) throws FileSystemException; /** * Creates a layered file system. A layered file system is a file system * that is created from the contents of a file, such as a zip or tar file. * * @param provider The name of the file system provider to use. This name * is the same as the scheme used in URI to identify the provider. * @param file The file to use to create the file system. * @return The root file of the new file system. * @throws FileSystemException On error creating the file system. */ FileObject createFileSystem(String provider, FileObject file) throws FileSystemException; /** * Closes the given filesystem. * <p> * If you use VFS as singleton it is VERY dangerous to call this method. * * @param filesystem The FileSystem to close. */ void closeFileSystem(FileSystem filesystem); /** * Creates a layered file system. A layered file system is a file system * that is created from the contents of a file, such as a zip or tar file. * * @param file The file to use to create the file system. * @return The root file of the new file system. * @throws FileSystemException On error creating the file system. */ FileObject createFileSystem(FileObject file) throws FileSystemException; /** * Creates an empty virtual file system. Can be populated by adding * junctions to it. * * @param rootUri The root URI to use for the new file system. Can be null. * @return The root file of the new file system. * @throws FileSystemException if an error occurs creating the VirtualFileSystem. */ FileObject createVirtualFileSystem(String rootUri) throws FileSystemException; /** * Creates a virtual file system. The file system will contain a junction * at the fs root to the supplied root file. * * @param rootFile The root file to backs the file system. * @return The root of the new file system. * @throws FileSystemException if an error occurs creating the VirtualFileSystem. */ FileObject createVirtualFileSystem(FileObject rootFile) throws FileSystemException; /** * Returns a streamhandler factory to enable URL lookup using this * FileSystemManager. * * @return the URLStreamHandlerFactory. */ URLStreamHandlerFactory getURLStreamHandlerFactory(); /** * Determines if a layered file system can be created for a given file. * * @param file The file to check for. * @return true if the FileSystem can be created. * @throws FileSystemException if an error occurs. */ boolean canCreateFileSystem(FileObject file) throws FileSystemException; /** * Get the cache used to cache fileobjects. * * @return The FilesCache. */ FilesCache getFilesCache(); /** * Get the cache strategy used. * * @return the CacheStrategy. */ CacheStrategy getCacheStrategy(); /** * Get the file object decorator used. * * @return the file object decorator Class. */ Class<?> getFileObjectDecorator(); /** * The constructor associated to the fileObjectDecorator. * We cache it here for performance reasons. * * @return the Constructor associated with the FileObjectDecorator. */ Constructor<?> getFileObjectDecoratorConst(); /** * The class to use to determine the content-type (mime-type). * * @return the FileContentInfoFactory. */ FileContentInfoFactory getFileContentInfoFactory(); /** * Returns true if this manager has a provider for a particular scheme. * * @param scheme The scheme for which a provider should be checked. * @return true if a provider for the scheme is available. */ boolean hasProvider(String scheme); /** * Get the schemes currently available. * * @return An array of available scheme names that are supported. */ String[] getSchemes(); /** * Get the capabilities for a given scheme. * * @param scheme The scheme to use to locate the provider's capabilities. * @return A Collection of the various capabilities. * @throws FileSystemException if the given scheme is not konwn. */ Collection<Capability> getProviderCapabilities(String scheme) throws FileSystemException; /** * Sets the logger to use. * * @param log The logger to use. */ void setLogger(Log log); /** * Get the configuration builder for the given scheme. * * @param scheme The schem to use to obtain the FileSystemConfigBuidler. * @return A FileSystemConfigBuilder appropriate for the given scheme. * @throws FileSystemException if the given scheme is not konwn. */ FileSystemConfigBuilder getFileSystemConfigBuilder(String scheme) throws FileSystemException; /** * Resolve the uri to a filename. * * @param uri The uri to resolve. * @return A FileName that matches the uri. * @throws FileSystemException if this is not possible. */ FileName resolveURI(String uri) throws FileSystemException; // -- OPERATIONS -- /** * Adds the specified FileOperationProvider for the specified scheme. * <p> * Several FileOperationProvider's might be registered for the same scheme. * For example, for {@code "file"} scheme we can register {@code SvnWsOperationProvider} and * {@code CvsOperationProvider.} * * @param scheme The scheme assoicated with this provider. * @param operationProvider The FileOperationProvider to add. * @throws FileSystemException if an error occurs. */ void addOperationProvider(String scheme, FileOperationProvider operationProvider) throws FileSystemException; /** * @see FileSystemManager#addOperationProvider(String, org.apache.commons.vfs2.operations.FileOperationProvider) * * @param schemes The schemes that will be associated with the provider. * @param operationProvider The FileOperationProvider to add. * @throws FileSystemException if an error occurs. */ void addOperationProvider(String[] schemes, FileOperationProvider operationProvider) throws FileSystemException; /** * Get Providers for file operations. * * @param scheme the scheme for wich we want to get the list af registered providers. * * @return the registered FileOperationProviders for the specified scheme. * If there were no providers registered for the scheme, it returns null. * * @throws FileSystemException if an error occurs. */ FileOperationProvider[] getOperationProviders(String scheme) throws FileSystemException; /** * Resolves a URI into a {@link FileObject}. * * @param uri The URI to convert. * @return The {@link FileObject} that represents the URI. Never * returns null. * @throws FileSystemException On error converting the file. * @since 2.1 */ FileObject resolveFile(URI uri) throws FileSystemException; /** * Resolves a URL into a {@link FileObject}. * * @param url The URL to convert. * @return The {@link FileObject} that represents the URL. Never * returns null. * @throws FileSystemException On error converting the file. * @since 2.1 */ FileObject resolveFile(URL url) throws FileSystemException; }