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.vfs2;
18  
19  import java.io.Closeable;
20  import java.net.URL;
21  import java.util.List;
22  
23  import org.apache.commons.vfs2.operations.FileOperations;
24  
25  /**
26   * Represents a file, and is used to access the content and structure of the file.
27   * <p>
28   * Files are arranged in a hierarchy. Each hierarchy forms a <i>file system</i>. A file system represents things like a
29   * local OS file system, a windows share, an HTTP server, or the contents of a Zip file.
30   * </p>
31   * <p>
32   * There are two types of files: <i>Folders</i>, which contain other files, and <i>normal files</i>, which contain data,
33   * or <i>content</i>. A folder may not have any content, and a normal file cannot contain other files.
34   * </p>
35   *
36   * <h2>File Naming</h2>
37   *
38   * <p>
39   * TODO - write this.
40   * </p>
41   *
42   * <h2>Reading and Writing a File</h2>
43   *
44   * <p>
45   * Reading and writing a file, and all other operations on the file's <i>content</i>, is done using the
46   * {@link FileContent} object returned by {@link #getContent}.
47   * </p>
48   *
49   * <h2>Creating and Deleting a File</h2>
50   *
51   * <p>
52   * A file is created using either {@link #createFolder}, {@link #createFile}, or by writing to the file using one of the
53   * {@link FileContent} methods.
54   * </p>
55   * <p>
56   * A file is deleted using {@link #delete}. Recursive deletion can be done using {@link #delete(FileSelector)}.
57   * </p>
58   *
59   * <h2>Finding Files</h2>
60   *
61   * <p>
62   * Other files in the <i>same</i> file system as this file can be found using:
63   * </p>
64   * <ul>
65   * <li>{@link #findFiles} to find a set of matching descendants in in the same file system.</li>
66   * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.</li>
67   * <li>{@link #getParent} to find the folder containing this file.</li>
68   * <li>{@link #getFileSystem} to find another file in the same file system.</li>
69   * <li>{@link #resolveFile} to find another file relative to this file.</li>
70   * </ul>
71   * <p>
72   * To find files in another file system, use a {@link FileSystemManager}.
73   * </p>
74   *
75   * <h2>Iterating Files</h2>
76   *
77   * <p>
78   * You can iterate over a FileObject using the Java "foreach" statement, which provides all descendants of a File
79   * Object.
80   * </p>
81   *
82   * <h2>Sorting Files</h2>
83   *
84   * <p>
85   * Files may be sorted using {@link java.util.Arrays#sort(Object[]) Arrays.sort()} and
86   * {@link java.util.Collections#sort(List) Collections.sort()}.
87   * </p>
88   *
89   * @see FileSystemManager
90   * @see FileContent
91   * @see FileName
92   */
93  public interface FileObject extends Comparable<FileObject>, Iterable<FileObject>, Closeable {
94  
95      /**
96       * Queries the file if it is possible to rename it to newfile.
97       *
98       * @param newfile the new file(-name)
99       * @return true it this is the case
100      */
101     boolean canRenameTo(FileObject newfile);
102 
103     /**
104      * Closes this file, and its content. This method is a hint to the implementation that it can release any resources
105      * associated with the file.
106      * <p>
107      * The file object can continue to be used after this method is called.
108      * </p>
109      *
110      * @throws FileSystemException On error closing the file.
111      * @see FileContent#close
112      */
113     @Override
114     void close() throws FileSystemException;
115 
116     /**
117      * Copies another file, and all its descendants, to this file.
118      * <p>
119      * If this file does not exist, it is created. Its parent folder is also created, if necessary. If this file does
120      * exist, it is deleted first.
121      * </p>
122      * <p>
123      * This method is not transactional. If it fails and throws an exception, this file will potentially only be
124      * partially copied.
125      * </p>
126      *
127      * @param srcFile The source file to copy.
128      * @param selector The selector to use to select which files to copy.
129      * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
130      *             the file.
131      */
132     void copyFrom(FileObject srcFile, FileSelector selector) throws FileSystemException;
133 
134     /**
135      * Creates this file, if it does not exist. Also creates any ancestor folders which do not exist. This method does
136      * nothing if the file already exists and is a file.
137      *
138      * @throws FileSystemException If the file already exists with the wrong type, or the parent folder is read-only, or
139      *             on error creating this file or one of its ancestors.
140      */
141     void createFile() throws FileSystemException;
142 
143     /**
144      * Creates this folder, if it does not exist. Also creates any ancestor folders which do not exist. This method does
145      * nothing if the folder already exists.
146      *
147      * @throws FileSystemException If the folder already exists with the wrong type, or the parent folder is read-only,
148      *             or on error creating this folder or one of its ancestors.
149      */
150     void createFolder() throws FileSystemException;
151 
152     /**
153      * Deletes this file. Does nothing if this file does not exist of if it is a folder that has children. Does not
154      * delete any descendants of this file, use {@link #delete(FileSelector)} or {@link #deleteAll()} for that.
155      *
156      * @return true if this object has been deleted
157      * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only, or on error
158      *             deleteing this file.
159      */
160     boolean delete() throws FileSystemException;
161 
162     /**
163      * Deletes all descendants of this file that match a selector. Does nothing if this file does not exist.
164      *
165      * <p>
166      * This method is not transactional. If it fails and throws an exception, this file will potentially only be
167      * partially deleted.
168      * </p>
169      *
170      * @param selector The selector to use to select which files to delete.
171      * @return the number of deleted objects
172      * @throws FileSystemException If this file or one of its descendants is read-only, or on error deleting this file
173      *             or one of its descendants.
174      */
175     int delete(FileSelector selector) throws FileSystemException;
176 
177     /**
178      * Deletes this file and all children.
179      *
180      * @return the number of deleted files.
181      * @throws FileSystemException if an error occurs.
182      * @see #delete(FileSelector)
183      * @see Selectors#SELECT_ALL
184      */
185     int deleteAll() throws FileSystemException;
186 
187     /**
188      * Determines if this file exists.
189      *
190      * @return {@code true} if this file exists, {@code false} if not.
191      * @throws FileSystemException On error determining if this file exists.
192      */
193     boolean exists() throws FileSystemException;
194 
195     /**
196      * Finds the set of matching descendants of this file, in depthwise order.
197      *
198      * @param selector The selector to use to select matching files.
199      * @return The matching files. The files are returned in depthwise order (that is, a child appears in the list
200      *         before its parent).
201      * @throws FileSystemException if an error occurs.
202      */
203     FileObject[] findFiles(FileSelector selector) throws FileSystemException;
204 
205     /**
206      * Finds the set of matching descendants of this file.
207      *
208      * @param selector the selector used to determine if the file should be selected
209      * @param depthwise controls the ordering in the list. e.g. deepest first
210      * @param selected container for selected files. list needs not to be empty.
211      * @throws FileSystemException if an error occurs.
212      */
213     void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;
214 
215     /**
216      * Returns a child of this file. Note that this method returns {@code null} when the child does not exist. This
217      * differs from {@link #resolveFile(String, NameScope)} which never returns null.
218      *
219      * @param name The name of the child.
220      * @return The child, or null if there is no such child.
221      * @throws FileSystemException If this file does not exist, or is not a folder, or on error determining this file's
222      *             children.
223      */
224     FileObject getChild(String name) throws FileSystemException;
225 
226     /**
227      * Lists the children of this file.
228      *
229      * @return An array containing the children of this file. The array is unordered. If the file does not have any
230      *         children, a zero-length array is returned. This method never returns null.
231      * @throws FileSystemException If this file does not exist, or is not a folder, or on error listing this file's
232      *             children.
233      */
234     FileObject[] getChildren() throws FileSystemException;
235 
236     /**
237      * Returns this file's content. The {@link FileContent} returned by this method can be used to read and write the
238      * content of the file.
239      *
240      * <p>
241      * This method can be called if the file does not exist, and the returned {@link FileContent} can be used to create
242      * the file by writing its content.
243      * </p>
244      *
245      * @return This file's content.
246      * @throws FileSystemException On error getting this file's content.
247      */
248     FileContent getContent() throws FileSystemException;
249 
250     /**
251      * @return FileOperations interface that provides access to the operations API.
252      * @throws FileSystemException if an error occurs.
253      */
254     FileOperations getFileOperations() throws FileSystemException;
255 
256     /**
257      * Returns the file system that contains this file.
258      *
259      * @return The file system.
260      */
261     FileSystem getFileSystem();
262 
263     /**
264      * Returns the name of this file.
265      *
266      * @return the FileName.
267      */
268     FileName getName();
269 
270     /**
271      * Returns the folder that contains this file.
272      *
273      * @return The folder that contains this file. Returns null if this file is the root of a file system.
274      * @throws FileSystemException On error finding the file's parent.
275      */
276     FileObject getParent() throws FileSystemException;
277 
278     /**
279      * Returns the receiver as a URI String for public display, like, without a password.
280      *
281      * @return A URI String without a password, never {@code null}.
282      */
283     String getPublicURIString();
284 
285     /**
286      * Returns this file's type.
287      *
288      * @return One of the {@link FileType} constants. Never returns null.
289      * @throws FileSystemException On error determining the file's type.
290      */
291     FileType getType() throws FileSystemException;
292 
293     /**
294      * Returns a URL representing this file.
295      *
296      * @return the URL for the file.
297      * @throws FileSystemException if an error occurs.
298      */
299     URL getURL() throws FileSystemException;
300 
301     /**
302      * Checks if the fileObject is attached.
303      *
304      * @return true if the FileObject is attached.
305      */
306     boolean isAttached();
307 
308     /**
309      * Checks if someone reads/write to this file.
310      *
311      * @return true if the file content is open.
312      */
313     boolean isContentOpen();
314 
315     /**
316      * Determines if this file is executable.
317      *
318      * @return {@code true} if this file is executable, {@code false} if not.
319      * @throws FileSystemException On error determining if this file exists.
320      */
321     boolean isExecutable() throws FileSystemException;
322 
323     /**
324      * Checks if this file is a regular file.
325      *
326      * @return true if this file is a regular file.
327      * @throws FileSystemException if an error occurs.
328      * @see #getType()
329      * @see FileType#FILE
330      * @since 2.1
331      */
332     boolean isFile() throws FileSystemException;
333 
334     /**
335      * Checks if this file is a folder.
336      *
337      * @return true if this file is a folder.
338      * @throws FileSystemException if an error occurs.
339      * @see #getType()
340      * @see FileType#FOLDER
341      * @since 2.1
342      */
343     boolean isFolder() throws FileSystemException;
344 
345     /**
346      * Determines if this file is hidden.
347      *
348      * @return {@code true} if this file is hidden, {@code false} if not.
349      * @throws FileSystemException On error determining if this file exists.
350      */
351     boolean isHidden() throws FileSystemException;
352 
353     /**
354      * Determines if this file can be read.
355      *
356      * @return {@code true} if this file is readable, {@code false} if not.
357      * @throws FileSystemException On error determining if this file exists.
358      */
359     boolean isReadable() throws FileSystemException;
360 
361     /**
362      * Determines if this file is a symbolic link.
363      *
364      * @return {@code true} if this file is a symbolic link, {@code false} if not.
365      * @throws FileSystemException On error determining if this file exists.
366      * @since 2.4
367      */
368     default boolean isSymbolicLink() throws FileSystemException {
369         return false;
370     }
371 
372     /**
373      * Determines if this file can be written to.
374      *
375      * @return {@code true} if this file is writeable, {@code false} if not.
376      * @throws FileSystemException On error determining if this file exists.
377      */
378     boolean isWriteable() throws FileSystemException;
379 
380     /**
381      * Move this file.
382      *
383      * <p>
384      * If the destFile exists, it is deleted first.
385      * </p>
386      *
387      * @param destFile the New file name.
388      * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
389      *             the file.
390      */
391     void moveTo(FileObject destFile) throws FileSystemException;
392 
393     /**
394      * This will prepare the fileObject to get resynchronized with the underlying file system if required.
395      *
396      * @throws FileSystemException if an error occurs.
397      */
398     void refresh() throws FileSystemException;
399 
400     /**
401      * Finds a file, relative to this file. Equivalent to calling {@code resolveFile( path, NameScope.FILE_SYSTEM )}.
402      *
403      * @param path The path of the file to locate. Can either be a relative path or an absolute path.
404      * @return The file.
405      * @throws FileSystemException On error parsing the path, or on error finding the file.
406      */
407     FileObject resolveFile(String path) throws FileSystemException;
408 
409     /**
410      * Finds a file relative to this file.
411      *
412      * Refer to {@link NameScope} for a description of how names are resolved in the different scopes.
413      *
414      * @param name The name to resolve.
415      * @param scope the NameScope for the file.
416      * @return The file.
417      * @throws FileSystemException On error parsing the path, or on error finding the file.
418      */
419     FileObject resolveFile(String name, NameScope scope) throws FileSystemException;
420 
421     /**
422      * Sets the owner's (or everybody's) write permission.
423      *
424      * @param executable True to allow read access, false to disallow.
425      * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
426      * @return true if the operation succeeded.
427      * @throws FileSystemException On error determining if this file exists.
428      * @since 2.1
429      */
430     boolean setExecutable(boolean executable, boolean ownerOnly) throws FileSystemException;
431 
432     /**
433      * Sets the owner's (or everybody's) read permission.
434      *
435      * @param readable True to allow read access, false to disallow
436      * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
437      * @return true if the operation succeeded
438      * @throws FileSystemException On error determining if this file exists.
439      * @since 2.1
440      */
441     boolean setReadable(boolean readable, boolean ownerOnly) throws FileSystemException;
442 
443     /**
444      * Sets the owner's (or everybody's) write permission.
445      *
446      * @param writable True to allow read access, false to disallow
447      * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
448      * @return true if the operation succeeded
449      * @throws FileSystemException On error determining if this file exists.
450      * @since 2.1
451      */
452     boolean setWritable(boolean writable, boolean ownerOnly) throws FileSystemException;
453 }