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