1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 }