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