FileSystemManager


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.vfs;
17  
18  import org.apache.commons.logging.Log;
19  
20  import java.io.File  ;
21  import java.net.URLStreamHandlerFactory  ;
22  import java.util.Collection  ;
23  
24  /**
25   * A FileSystemManager manages a set of file systems.  This interface is
26   * used to locate a {@link FileObject} by name from one of those file systems.
27   * <p/>
28   * <p>To locate a {@link FileObject}, use one of the <code>resolveFile()</code>
29   * methods.</p>
30   * <p/>
31   * <h4><a name="naming">File Naming</a></h4>
32   * <p/>
33   * <p>A file system manager can recognise several types of file names:
34   * <p/>
35   * <ul>
36   * <p/>
37   * <li><p>Absolute URI.  These must start with a scheme, such as
38   * <code>file:</code> or <code>ftp:</code>, followed by a scheme dependent
39   * file name.  Some examples:</p>
40   * <pre>
41   * file:/c:/somefile
42   * ftp://somewhere.org/somefile
43   * </pre>
44   * <p/>
45   * <li><p>Absolute local file name.  For example,
46   * <code>/home/someuser/a-file</code> or <code>c:\dir\somefile.html</code>.
47   * Elements in the name can be separated using any of the following
48   * characters: <code>/</code>, <code>\</code>, or the native file separator
49   * character. For example, the following file names are the same:</p>
50   * <pre>
51   * c:\somedir\somefile.xml
52   * c:/somedir/somefile.xml
53   * </pre>
54   * <p/>
55   * <li><p>Relative path.  For example: <code>../somefile</code> or
56   * <code>somedir/file.txt</code>.   The file system manager resolves relative
57   * paths against its <i>base file</i>.  Elements in the relative path can be
58   * separated using <code>/</code>, <code>\</code>, or file system specific
59   * separator characters.  Relative paths may also contain <code>..</code> and
60   * <code>.</code> elements.  See {@link FileObject#resolveFile} for more
61   * details.</p>
62   * <p/>
63   * </ul>
64   *
65   * @author <a HREF="mailto:adammurdoch@apache.org">Adam Murdoch</a>
66   */
67  public interface FileSystemManager
68  {
69      /**
70       * Returns the base file used to resolve relative paths.
71       */
72      FileObject getBaseFile() throws FileSystemException;
73  
74      /**
75       * Locates a file by name.  Equivalent to calling
76       * <code>resolveFile(uri, getBaseName())</code>.
77       *
78       * @param name The name of the file.
79       * @return The file.  Never returns null.
80       * @throws FileSystemException On error parsing the file name.
81       */
82      FileObject resolveFile(String   name)
83          throws FileSystemException;
84  
85      /**
86       * Locates a file by name.  Equivalent to calling
87       * <code>resolveFile(uri, getBaseName())</code>.
88       *
89       * @param name              The name of the file.
90       * @param fileSystemOptions The FileSystemOptions used for FileSystem creation
91       * @return The file.  Never returns null.
92       * @throws FileSystemException On error parsing the file name.
93       */
94      FileObject resolveFile(String   name, FileSystemOptions fileSystemOptions)
95          throws FileSystemException;
96  
97      /**
98       * Locates a file by name.  The name is resolved as described
99       * <a HREF="#naming">above</a>.  That is, the name can be either
100      * an absolute URI, an absolute file name, or a relative path to
101      * be resolved against <code>baseFile</code>.
102      * <p/>
103      * <p>Note that the file does not have to exist when this method is called.
104      *
105      * @param name     The name of the file.
106      * @param baseFile The base file to use to resolve relative paths.
107      *                 May be null.
108      * @return The file.  Never returns null.
109      * @throws FileSystemException On error parsing the file name.
110      */
111     FileObject resolveFile(FileObject baseFile, String   name)
112         throws FileSystemException;
113 
114     /**
115      * Locates a file by name.  See {@link #resolveFile(FileObject, String)}
116      * for details.
117      *
118      * @param baseFile The base file to use to resolve relative paths.
119      *                 May be null.
120      * @param name     The name of the file.
121      * @return The file.  Never returns null.
122      * @throws FileSystemException On error parsing the file name.
123      */
124     FileObject resolveFile(File   baseFile, String   name)
125         throws FileSystemException;
126 
127     /**
128      * Resolves a name, relative to this file name.  Equivalent to calling
129      * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
130      *
131      * @param root the base filename
132      * @param name The name to resolve.
133      * @return A {@link FileName} object representing the resolved file name.
134      * @throws FileSystemException If the name is invalid.
135      */
136     FileName resolveName(final FileName root, final String   name) throws FileSystemException;
137 
138     /**
139      * Resolves a name, relative to the "root" file name.  Refer to {@link NameScope}
140      * for a description of how names are resolved.
141      *
142      * @param root the base filename
143      * @param name  The name to resolve.
144      * @param scope The {@link NameScope} to use when resolving the name.
145      * @return A {@link FileName} object representing the resolved file name.
146      * @throws FileSystemException If the name is invalid.
147      */
148     FileName resolveName(final FileName root, String   name, NameScope scope)
149         throws FileSystemException;
150 
151     /**
152      * Converts a local file into a {@link FileObject}.
153      *
154      * @param file The file to convert.
155      * @return The {@link FileObject} that represents the local file.  Never
156      *         returns null.
157      * @throws FileSystemException On error converting the file.
158      */
159     FileObject toFileObject(File   file)
160         throws FileSystemException;
161 
162     /**
163      * Creates a layered file system.  A layered file system is a file system
164      * that is created from the contents of a file, such as a zip or tar file.
165      *
166      * @param provider The name of the file system provider to use.  This name
167      *                 is the same as the scheme used in URI to identify the provider.
168      * @param file     The file to use to create the file system.
169      * @return The root file of the new file system.
170      * @throws FileSystemException On error creating the file system.
171      */
172     FileObject createFileSystem(String   provider, FileObject file)
173         throws FileSystemException;
174 
175     /**
176      * Creates a layered file system.  A layered file system is a file system
177      * that is created from the contents of a file, such as a zip or tar file.
178      *
179      * @param file The file to use to create the file system.
180      * @return The root file of the new file system.
181      * @throws FileSystemException On error creating the file system.
182      */
183     FileObject createFileSystem(FileObject file)
184         throws FileSystemException;
185 
186     /**
187      * Creates an empty virtual file system.  Can be populated by adding
188      * junctions to it.
189      *
190      * @param rootUri The root URI to use for the new file system.  Can be null.
191      * @return The root file of the new file system.
192      */
193     FileObject createVirtualFileSystem(String   rootUri)
194         throws FileSystemException;
195 
196     /**
197      * Creates a virtual file system.  The file system will contain a junction
198      * at the fs root to the supplied root file.
199      *
200      * @param rootFile The root file to backs the file system.
201      * @return The root of the new file system.
202      */
203     FileObject createVirtualFileSystem(FileObject rootFile)
204         throws FileSystemException;
205 
206     /**
207      * Returns a streamhandler factory to enable URL lookup using this
208      * FileSystemManager.
209      */
210     URLStreamHandlerFactory   getURLStreamHandlerFactory();
211 
212     /**
213      * Determines if a layered file system can be created for a given file.
214      *
215      * @param file The file to check for.
216      */
217     boolean canCreateFileSystem(FileObject file) throws FileSystemException;
218 
219     /**
220      * Get the cache used to cache fileobjects.
221      */
222     FilesCache getFilesCache();
223 
224     /**
225      * The class to use to determine the content-type (mime-type)
226      */
227     FileContentInfoFactory getFileContentInfoFactory();
228 
229     /**
230      * Get the schemes currently available.
231      */
232     public String  [] getSchemes();
233 
234     /**
235      * Get the capabilities for a given scheme.
236      *
237      * @throws FileSystemException if the given scheme is not konwn
238      */
239     public Collection   getProviderCapabilities(final String   scheme) throws FileSystemException;
240 
241     /**
242      * Sets the logger to use.
243      */
244     public void setLogger(final Log log);
245 
246     /**
247      * Get the configuration builder for the given scheme
248      *
249      * @throws FileSystemException if the given scheme is not konwn
250      */
251     public FileSystemConfigBuilder getFileSystemConfigBuilder(final String   scheme) throws FileSystemException;
252 
253     /**
254      * Resolve the uri to a filename
255      *
256      * @throws FileSystemException if this is not possible
257      */
258     public FileName resolveURI(String   uri) throws FileSystemException;
259 }
260
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags