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 java.io.File;
20  
21  /***
22   * A file system, made up of a hierarchy of files.
23   *
24   * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
25   * @version $Revision: 484648 $ $Date: 2006-12-08 17:18:36 +0100 (Fr, 08 Dez 2006) $
26   */
27  public interface FileSystem
28  {
29      /***
30       * Returns the root file of this file system.
31       */
32      FileObject getRoot() throws FileSystemException;
33  
34      /***
35       * Returns the name of the root file of this file system.
36       */
37      FileName getRootName();
38  
39      /***
40       * Determines if this file system has a particular capability.
41       *
42       * @param capability The capability to check for.
43       * @return true if this filesystem has the requested capability.
44       *         Note that not all files in the file system may have the
45       *         capability.
46       * @todo Move this to another interface, so that set of capabilities can be queried.
47       */
48      boolean hasCapability(Capability capability);
49  
50      /***
51       * Returns the parent layer if this is a layered file system.
52       *
53       * @return The parent layer, or null if this is not a layered file system.
54       */
55      FileObject getParentLayer() throws FileSystemException;
56  
57      /***
58       * Gets the value of an attribute of the file system.
59       * <p/>
60       * <p>TODO - change to <code>Map getAttributes()</code> instead?
61       * <p/>
62       * <p>TODO - define the standard attribute names, and define which attrs
63       * are guaranteed to be present.
64       *
65       * @param attrName The name of the attribute.
66       * @return The value of the attribute.
67       * @throws org.apache.commons.vfs.FileSystemException
68       *          If the file does not exist, or is being written, or if the
69       *          attribute is unknown.
70       * @see org.apache.commons.vfs.FileContent#getAttribute
71       */
72      Object getAttribute(String attrName) throws FileSystemException;
73  
74      /***
75       * Sets the value of an attribute of the file's content.  Creates the
76       * file if it does not exist.
77       *
78       * @param attrName The name of the attribute.
79       * @param value    The value of the attribute.
80       * @throws FileSystemException If the file is read-only, or is being read, or if the attribute
81       *                             is not supported, or on error setting the attribute.
82       * @see FileContent#setAttribute
83       */
84      void setAttribute(String attrName, Object value)
85          throws FileSystemException;
86  
87      /***
88       * Finds a file in this file system.
89       *
90       * @param name The name of the file.
91       * @return The file.  Never returns null.
92       */
93      FileObject resolveFile(FileName name) throws FileSystemException;
94  
95      /***
96       * Finds a file in this file system.
97       *
98       * @param name The name of the file.  This must be an absolute path.
99       * @return The file.  Never returns null.
100      */
101     FileObject resolveFile(String name) throws FileSystemException;
102 
103     /***
104      * Adds a listener on a file in this file system.
105      *
106      * @param file     The file to attach the listener to.
107      * @param listener The listener to add.
108      */
109     void addListener(FileObject file, FileListener listener);
110 
111     /***
112      * Removes a listener from a file in this file system.
113      *
114      * @param file     The file to remove the listener from.
115      * @param listener The listener to remove.
116      */
117     void removeListener(FileObject file, FileListener listener);
118 
119     /***
120      * Adds a junction to this file system.  A junction is a link that attaches
121      * the supplied file to a point in this file system, making it look like
122      * part of the file system.
123      *
124      * @param junctionPoint The point in this file system to add the junction.
125      * @param targetFile    The file to link to.
126      * @throws FileSystemException If this file system does not support junctions, or the junction
127      *                             point or target file is invalid (the file system may not support
128      *                             nested junctions, for example).
129      */
130     void addJunction(String junctionPoint, FileObject targetFile)
131         throws FileSystemException;
132 
133     /***
134      * Removes a junction from this file system.
135      *
136      * @param junctionPoint The junction to remove.
137      * @throws FileSystemException On error removing the junction.
138      */
139     void removeJunction(String junctionPoint) throws FileSystemException;
140 
141     /***
142      * Creates a temporary local copy of a file and its descendents.  If
143      * this file is already a local file, a copy is not made.
144      * <p/>
145      * <p>Note that the local copy may include additonal files, that were
146      * not selected by the given selector.
147      *
148      * @param file     The file to replicate.
149      * @param selector The selector to use to select the files to replicate.
150      * @return The local copy of this file.
151      * @throws FileSystemException If this file does not exist, or on error replicating the file.
152      * @todo Add options to indicate whether the caller is happy to deal with
153      * extra files being present locally (eg if the file has been
154      * replicated previously), or whether the caller expects only
155      * the selected files to be present.
156      */
157     File replicateFile(FileObject file, FileSelector selector)
158         throws FileSystemException;
159 
160     /***
161      * Returns the FileSystemOptions used to instantiate this filesystem
162      */
163     FileSystemOptions getFileSystemOptions();
164 
165     /***
166      * Returns a reference to the FileSytemManager
167      */
168     FileSystemManager getFileSystemManager();
169 
170     /***
171      * Returns the accuracy of the last modification time
172      *
173      * @return ms 0 perfectly accurate, >0 might be off by this value e.g. sftp 1000ms
174      */
175     double getLastModTimeAccuracy();
176 }