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.net.URL;
20 import java.util.List;
21
22 import org.apache.commons.vfs.operations.FileOperations;
23
24 /***
25 * Represents a file, and is used to access the content and
26 * structure of the file.
27 * <p/>
28 * <p>Files are arranged in a hierarchy. Each hierachy forms a
29 * <i>file system</i>. A file system represents things like a local OS
30 * file system, a windows share, an HTTP server, or the contents of a Zip file.
31 * <p/>
32 * <p>There are two types of files: <i>Folders</i>, which contain other files,
33 * and <i>normal files</i>, which contain data, or <i>content</i>. A folder may
34 * not have any content, and a normal file cannot contain other files.
35 * <p/>
36 * <h4>File Naming</h4>
37 * <p/>
38 * <p>TODO - write this.
39 * <p/>
40 * <h4>Reading and Writing a File</h4>
41 * <p/>
42 * <p>Reading and writing a file, and all other operations on the file's
43 * <i>content</i>, is done using the {@link FileContent} object returned
44 * by {@link #getContent}.
45 * <p/>
46 * <h4>Creating and Deleting a File</h4>
47 * <p/>
48 * <p>A file is created using either {@link #createFolder}, {@link #createFile},
49 * or by writing to the file using one of the {@link FileContent} methods.
50 * <p/>
51 * <p>A file is deleted using {@link #delete}. Recursive deletion can be
52 * done using {@link #delete(FileSelector)}.
53 * <p/>
54 * <h4>Finding Files</h4>
55 * <p/>
56 * <p>Other files in the <i>same</i> file system as this file can be found
57 * using:
58 * <ul>
59 * <li>{@link #resolveFile} to find another file relative to this file.
60 * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.
61 * <li>{@link #getParent} to find the folder containing this file.
62 * <li>{@link #getFileSystem} to find another file in the same file system.
63 * </ul>
64 * <p/>
65 * <p>To find files in another file system, use a {@link FileSystemManager}.
66 *
67 * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
68 * @version $Revision: 483899 $ $Date: 2006-12-08 10:47:09 +0100 (Fr, 08 Dez 2006) $
69 * @see FileSystemManager
70 * @see FileContent
71 * @see FileName
72 */
73 public interface FileObject
74 {
75 /***
76 * Returns the name of this file.
77 */
78 public FileName getName();
79
80 /***
81 * Returns a URL representing this file.
82 */
83 public URL getURL() throws FileSystemException;
84
85 /***
86 * Determines if this file exists.
87 *
88 * @return <code>true</code> if this file exists, <code>false</code> if not.
89 * @throws FileSystemException On error determining if this file exists.
90 */
91 public boolean exists() throws FileSystemException;
92
93 /***
94 * Determines if this file is hidden.
95 *
96 * @return <code>true</code> if this file is hidden, <code>false</code> if not.
97 * @throws FileSystemException On error determining if this file exists.
98 */
99 public boolean isHidden() throws FileSystemException;
100
101 /***
102 * Determines if this file can be read.
103 *
104 * @return <code>true</code> if this file is readable, <code>false</code> if not.
105 * @throws FileSystemException On error determining if this file exists.
106 */
107 public boolean isReadable() throws FileSystemException;
108
109 /***
110 * Determines if this file can be written to.
111 *
112 * @return <code>true</code> if this file is writeable, <code>false</code> if not.
113 * @throws FileSystemException On error determining if this file exists.
114 */
115 public boolean isWriteable() throws FileSystemException;
116
117 /***
118 * Returns this file's type.
119 *
120 * @return One of the {@link FileType} constants. Never returns null.
121 * @throws FileSystemException On error determining the file's type.
122 */
123 public FileType getType() throws FileSystemException;
124
125 /***
126 * Returns the folder that contains this file.
127 *
128 * @return The folder that contains this file. Returns null if this file is
129 * the root of a file system.
130 * @throws FileSystemException On error finding the file's parent.
131 */
132 public FileObject getParent() throws FileSystemException;
133
134 /***
135 * Returns the file system that contains this file.
136 *
137 * @return The file system.
138 */
139 public FileSystem getFileSystem();
140
141 /***
142 * Lists the children of this file.
143 *
144 * @return An array containing the children of this file. The array is
145 * unordered. If the file does not have any children, a zero-length
146 * array is returned. This method never returns null.
147 * @throws FileSystemException If this file does not exist, or is not a folder, or on error
148 * listing this file's children.
149 */
150 public FileObject[] getChildren() throws FileSystemException;
151
152 /***
153 * Returns a child of this file. Note that this method returns <code>null</code>
154 * when the child does not exist. This differs from
155 * {@link #resolveFile( String, NameScope)} which never returns null.
156 *
157 * @param name The name of the child.
158 * @return The child, or null if there is no such child.
159 * @throws FileSystemException If this file does not exist, or is not a folder, or on error
160 * determining this file's children.
161 */
162 public FileObject getChild(String name) throws FileSystemException;
163
164 /***
165 * Finds a file, relative to this file. Refer to {@link NameScope}
166 * for a description of how names are resolved in the different scopes.
167 *
168 * @param name The name to resolve.
169 * @return The file.
170 * @throws FileSystemException On error parsing the path, or on error finding the file.
171 */
172 public FileObject resolveFile(String name, NameScope scope)
173 throws FileSystemException;
174
175 /***
176 * Finds a file, relative to this file. Equivalent to calling
177 * <code>resolveFile( path, NameScope.FILE_SYSTEM )</code>.
178 *
179 * @param path The path of the file to locate. Can either be a relative
180 * path or an absolute path.
181 * @return The file.
182 * @throws FileSystemException On error parsing the path, or on error finding the file.
183 */
184 public FileObject resolveFile(String path) throws FileSystemException;
185
186 /***
187 * Finds the set of matching descendents of this file, in depthwise order.
188 *
189 * @param selector The selector to use to select matching files.
190 * @return The matching files. The files are returned in depthwise order
191 * (that is, a child appears in the list before its parent).
192 */
193 public FileObject[] findFiles(FileSelector selector) throws FileSystemException;
194
195 /***
196 * Finds the set of matching descendents of this file.
197 *
198 * @param selector the selector used to determine if the file should be selected
199 * @param depthwise controls the ordering in the list. e.g. deepest first
200 * @param selected container for selected files. list needs not to be empty.
201 * @throws FileSystemException
202 */
203 public void findFiles(FileSelector selector,
204 boolean depthwise,
205 List selected) throws FileSystemException;
206
207 /***
208 * Deletes this file. Does nothing if this file does not exist of if it is a
209 * folder that has children. Does not delete any descendents of this file,
210 * use {@link #delete(FileSelector)} for that.
211 *
212 * @return true if this object has been deleted
213 * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only,
214 * or on error deleteing this file.
215 */
216 public boolean delete() throws FileSystemException;
217
218 /***
219 * Deletes all descendents of this file that match a selector. Does
220 * nothing if this file does not exist.
221 * <p/>
222 * <p>This method is not transactional. If it fails and throws an
223 * exception, this file will potentially only be partially deleted.
224 *
225 * @param selector The selector to use to select which files to delete.
226 * @return the number of deleted objects
227 * @throws FileSystemException If this file or one of its descendents is read-only, or on error
228 * deleting this file or one of its descendents.
229 */
230 public int delete(FileSelector selector) throws FileSystemException;
231
232 /***
233 * Creates this folder, if it does not exist. Also creates any ancestor
234 * folders which do not exist. This method does nothing if the folder
235 * already exists.
236 *
237 * @throws FileSystemException If the folder already exists with the wrong type, or the parent
238 * folder is read-only, or on error creating this folder or one of
239 * its ancestors.
240 */
241 public void createFolder() throws FileSystemException;
242
243 /***
244 * Creates this file, if it does not exist. Also creates any ancestor
245 * folders which do not exist. This method does nothing if the file
246 * already exists and is a file.
247 *
248 * @throws FileSystemException If the file already exists with the wrong type, or the parent
249 * folder is read-only, or on error creating this file or one of
250 * its ancestors.
251 */
252 public void createFile() throws FileSystemException;
253
254 /***
255 * Copies another file, and all its descendents, to this file.
256 * <p/>
257 * If this file does not exist, it is created. Its parent folder is also
258 * created, if necessary. If this file does exist, it is deleted first.
259 * <p/>
260 * <p>This method is not transactional. If it fails and throws an
261 * exception, this file will potentially only be partially copied.
262 *
263 * @param srcFile The source file to copy.
264 * @param selector The selector to use to select which files to copy.
265 * @throws FileSystemException If this file is read-only, or if the source file does not exist,
266 * or on error copying the file.
267 */
268 public void copyFrom(FileObject srcFile, FileSelector selector)
269 throws FileSystemException;
270
271 /***
272 * Move this file.
273 * <p>If the destFile exists, it is deleted first</b>
274 *
275 * @param destFile the New filename.
276 * @throws FileSystemException If this file is read-only, or if the source file does not exist,
277 * or on error copying the file.
278 */
279 public void moveTo(FileObject destFile)
280 throws FileSystemException;
281
282 /***
283 * Queries the file if it is possible to rename it to newfile.
284 *
285 * @param newfile the new file(-name)
286 * @return true it this is the case
287 */
288 public boolean canRenameTo(FileObject newfile);
289
290 /***
291 * Returns this file's content. The {@link FileContent} returned by this
292 * method can be used to read and write the content of the file.
293 * <p/>
294 * <p>This method can be called if the file does not exist, and
295 * the returned {@link FileContent} can be used to create the file
296 * by writing its content.
297 *
298 * @return This file's content.
299 * @throws FileSystemException On error getting this file's content.
300 */
301 public FileContent getContent() throws FileSystemException;
302
303 /***
304 * Closes this file, and its content. This method is a hint to the
305 * implementation that it can release any resources associated with
306 * the file.
307 * <p/>
308 * <p>The file object can continue to be used after this method is called.
309 *
310 * @throws FileSystemException On error closing the file.
311 * @see FileContent#close
312 */
313 public void close() throws FileSystemException;
314
315 /***
316 * This will prepare the fileObject to get resynchronized with the underlaying filesystem if required
317 */
318 public void refresh() throws FileSystemException;
319
320 /***
321 * check if the fileObject is attaced
322 */
323 public boolean isAttached();
324
325 /***
326 * check if someone reads/write to this file
327 */
328 public boolean isContentOpen();
329
330
331
332 /***
333 * @return FileOperations interface that provides access to the operations API.
334 * @throws FileSystemException
335 */
336 FileOperations getFileOperations() throws FileSystemException;
337 }