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.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     // -- OPERATIONS --
    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 }