001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.vfs2;
018
019import java.io.Closeable;
020import java.net.URL;
021import java.util.List;
022
023import org.apache.commons.vfs2.operations.FileOperations;
024
025/**
026 * Represents a file, and is used to access the content and structure of the file.
027 * <p>
028 * Files are arranged in a hierarchy. Each hierarchy forms a <i>file system</i>. A file system represents things like a
029 * local OS file system, a windows share, an HTTP server, or the contents of a Zip file.
030 * <p>
031 * There are two types of files: <i>Folders</i>, which contain other files, and <i>normal files</i>, which contain data,
032 * or <i>content</i>. A folder may not have any content, and a normal file cannot contain other files.
033 *
034 * <h2>File Naming</h2>
035 *
036 * TODO - write this.
037 *
038 * <h2>Reading and Writing a File</h2>
039 *
040 * Reading and writing a file, and all other operations on the file's <i>content</i>, is done using the
041 * {@link FileContent} object returned by {@link #getContent}.
042 *
043 * <h2>Creating and Deleting a File</h2>
044 *
045 * A file is created using either {@link #createFolder}, {@link #createFile}, or by writing to the file using one of the
046 * {@link FileContent} methods.
047 * <p>
048 * A file is deleted using {@link #delete}. Recursive deletion can be done using {@link #delete(FileSelector)}.
049 *
050 * <h2>Finding Files</h2>
051 *
052 * Other files in the <i>same</i> file system as this file can be found using:
053 * <ul>
054 * <li>{@link #findFiles} to find a set of matching descendants in in the same file system.</li>
055 * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.</li>
056 * <li>{@link #getParent} to find the folder containing this file.</li>
057 * <li>{@link #getFileSystem} to find another file in the same file system.</li>
058 * <li>{@link #resolveFile} to find another file relative to this file.</li>
059 * </ul>
060 * To find files in another file system, use a {@link FileSystemManager}.
061 *
062 * <h2>Iterating Files</h2>
063 *
064 * You can iterate over a FileObject using the Java "foreach" statement, which provides all descendants of a File
065 * Object.
066 *
067 * <h2>Sorting Files</h2>
068 *
069 * Files may be sorted using {@link java.util.Arrays#sort(Object[]) Arrays.sort()} and
070 * {@link java.util.Collections#sort(List) Collections.sort()}.
071 *
072 * @see FileSystemManager
073 * @see FileContent
074 * @see FileName
075 */
076public interface FileObject extends Comparable<FileObject>, Iterable<FileObject>, Closeable {
077    /**
078     * Queries the file if it is possible to rename it to newfile.
079     *
080     * @param newfile the new file(-name)
081     * @return true it this is the case
082     */
083    boolean canRenameTo(FileObject newfile);
084
085    /**
086     * Closes this file, and its content. This method is a hint to the implementation that it can release any resources
087     * associated with the file.
088     * <p>
089     * The file object can continue to be used after this method is called.
090     * </p>
091     *
092     * @throws FileSystemException On error closing the file.
093     * @see FileContent#close
094     */
095    @Override
096    void close() throws FileSystemException;
097
098    /**
099     * Copies another file, and all its descendants, to this file.
100     * <p>
101     * If this file does not exist, it is created. Its parent folder is also created, if necessary. If this file does
102     * exist, it is deleted first.
103     * </p>
104     * <p>
105     * This method is not transactional. If it fails and throws an exception, this file will potentially only be
106     * partially copied.
107     * </p>
108     *
109     * @param srcFile The source file to copy.
110     * @param selector The selector to use to select which files to copy.
111     * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
112     *             the file.
113     */
114    void copyFrom(FileObject srcFile, FileSelector selector) throws FileSystemException;
115
116    /**
117     * Creates this file, if it does not exist. Also creates any ancestor folders which do not exist. This method does
118     * nothing if the file already exists and is a file.
119     *
120     * @throws FileSystemException If the file already exists with the wrong type, or the parent folder is read-only, or
121     *             on error creating this file or one of its ancestors.
122     */
123    void createFile() throws FileSystemException;
124
125    /**
126     * Creates this folder, if it does not exist. Also creates any ancestor folders which do not exist. This method does
127     * nothing if the folder already exists.
128     *
129     * @throws FileSystemException If the folder already exists with the wrong type, or the parent folder is read-only,
130     *             or on error creating this folder or one of its ancestors.
131     */
132    void createFolder() throws FileSystemException;
133
134    /**
135     * Deletes this file. Does nothing if this file does not exist of if it is a folder that has children. Does not
136     * delete any descendants of this file, use {@link #delete(FileSelector)} or {@link #deleteAll()} for that.
137     *
138     * @return true if this object has been deleted
139     * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only, or on error
140     *             deleteing this file.
141     */
142    boolean delete() throws FileSystemException;
143
144    /**
145     * Deletes all descendants of this file that match a selector. Does nothing if this file does not exist.
146     *
147     * <p>
148     * This method is not transactional. If it fails and throws an exception, this file will potentially only be
149     * partially deleted.
150     * </p>
151     *
152     * @param selector The selector to use to select which files to delete.
153     * @return the number of deleted objects
154     * @throws FileSystemException If this file or one of its descendants is read-only, or on error deleting this file
155     *             or one of its descendants.
156     */
157    int delete(FileSelector selector) throws FileSystemException;
158
159    /**
160     * Deletes this file and all children.
161     *
162     * @return the number of deleted files.
163     * @throws FileSystemException if an error occurs.
164     * @see #delete(FileSelector)
165     * @see Selectors#SELECT_ALL
166     */
167    int deleteAll() throws FileSystemException;
168
169    /**
170     * Determines if this file exists.
171     *
172     * @return {@code true} if this file exists, {@code false} if not.
173     * @throws FileSystemException On error determining if this file exists.
174     */
175    boolean exists() throws FileSystemException;
176
177    /**
178     * Finds the set of matching descendants of this file, in depthwise order.
179     *
180     * @param selector The selector to use to select matching files.
181     * @return The matching files. The files are returned in depthwise order (that is, a child appears in the list
182     *         before its parent).
183     * @throws FileSystemException if an error occurs.
184     */
185    FileObject[] findFiles(FileSelector selector) throws FileSystemException;
186
187    /**
188     * Finds the set of matching descendants of this file.
189     *
190     * @param selector the selector used to determine if the file should be selected
191     * @param depthwise controls the ordering in the list. e.g. deepest first
192     * @param selected container for selected files. list needs not to be empty.
193     * @throws FileSystemException if an error occurs.
194     */
195    void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;
196
197    /**
198     * Returns a child of this file. Note that this method returns {@code null} when the child does not exist. This
199     * differs from {@link #resolveFile(String, NameScope)} which never returns null.
200     *
201     * @param name The name of the child.
202     * @return The child, or null if there is no such child.
203     * @throws FileSystemException If this file does not exist, or is not a folder, or on error determining this file's
204     *             children.
205     */
206    FileObject getChild(String name) throws FileSystemException;
207
208    /**
209     * Lists the children of this file.
210     *
211     * @return An array containing the children of this file. The array is unordered. If the file does not have any
212     *         children, a zero-length array is returned. This method never returns null.
213     * @throws FileSystemException If this file does not exist, or is not a folder, or on error listing this file's
214     *             children.
215     */
216    FileObject[] getChildren() throws FileSystemException;
217
218    /**
219     * Returns this file's content. The {@link FileContent} returned by this method can be used to read and write the
220     * content of the file.
221     *
222     * <p>
223     * This method can be called if the file does not exist, and the returned {@link FileContent} can be used to create
224     * the file by writing its content.
225     * </p>
226     *
227     * @return This file's content.
228     * @throws FileSystemException On error getting this file's content.
229     */
230    FileContent getContent() throws FileSystemException;
231
232    /**
233     * @return FileOperations interface that provides access to the operations API.
234     * @throws FileSystemException if an error occurs.
235     */
236    FileOperations getFileOperations() throws FileSystemException;
237
238    /**
239     * Returns the file system that contains this file.
240     *
241     * @return The file system.
242     */
243    FileSystem getFileSystem();
244
245    /**
246     * Returns the name of this file.
247     *
248     * @return the FileName.
249     */
250    FileName getName();
251
252    /**
253     * Returns the folder that contains this file.
254     *
255     * @return The folder that contains this file. Returns null if this file is the root of a file system.
256     * @throws FileSystemException On error finding the file's parent.
257     */
258    FileObject getParent() throws FileSystemException;
259
260    /**
261     * Returns the receiver as a URI String for public display, like, without a password.
262     *
263     * @return A URI String without a password, never {@code null}.
264     */
265    String getPublicURIString();
266
267    /**
268     * Returns this file's type.
269     *
270     * @return One of the {@link FileType} constants. Never returns null.
271     * @throws FileSystemException On error determining the file's type.
272     */
273    FileType getType() throws FileSystemException;
274
275    /**
276     * Returns a URL representing this file.
277     *
278     * @return the URL for the file.
279     * @throws FileSystemException if an error occurs.
280     */
281    URL getURL() throws FileSystemException;
282
283    /**
284     * Checks if the fileObject is attached.
285     *
286     * @return true if the FileObject is attached.
287     */
288    boolean isAttached();
289
290    /**
291     * Checks if someone reads/write to this file.
292     *
293     * @return true if the file content is open.
294     */
295    boolean isContentOpen();
296
297    /**
298     * Determines if this file is executable.
299     *
300     * @return {@code true} if this file is executable, {@code false} if not.
301     * @throws FileSystemException On error determining if this file exists.
302     */
303    boolean isExecutable() throws FileSystemException;
304
305    /**
306     * Checks if this file is a regular file.
307     *
308     * @return true if this file is a regular file.
309     * @throws FileSystemException if an error occurs.
310     * @see #getType()
311     * @see FileType#FILE
312     * @since 2.1
313     */
314    boolean isFile() throws FileSystemException;
315
316    /**
317     * Checks if this file is a folder.
318     *
319     * @return true if this file is a folder.
320     * @throws FileSystemException if an error occurs.
321     * @see #getType()
322     * @see FileType#FOLDER
323     * @since 2.1
324     */
325    boolean isFolder() throws FileSystemException;
326
327    /**
328     * Determines if this file is hidden.
329     *
330     * @return {@code true} if this file is hidden, {@code false} if not.
331     * @throws FileSystemException On error determining if this file exists.
332     */
333    boolean isHidden() throws FileSystemException;
334
335    /**
336     * Determines if this file can be read.
337     *
338     * @return {@code true} if this file is readable, {@code false} if not.
339     * @throws FileSystemException On error determining if this file exists.
340     */
341    boolean isReadable() throws FileSystemException;
342
343    /**
344     * Determines if this file can be written to.
345     *
346     * @return {@code true} if this file is writeable, {@code false} if not.
347     * @throws FileSystemException On error determining if this file exists.
348     */
349    boolean isWriteable() throws FileSystemException;
350
351    /**
352     * Move this file.
353     *
354     * <p>
355     * If the destFile exists, it is deleted first.
356     * </p>
357     *
358     * @param destFile the New filename.
359     * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
360     *             the file.
361     */
362    void moveTo(FileObject destFile) throws FileSystemException;
363
364    /**
365     * This will prepare the fileObject to get resynchronized with the underlying file system if required.
366     *
367     * @throws FileSystemException if an error occurs.
368     */
369    void refresh() throws FileSystemException;
370
371    /**
372     * Finds a file, relative to this file. Equivalent to calling {@code resolveFile( path, NameScope.FILE_SYSTEM )}.
373     *
374     * @param path The path of the file to locate. Can either be a relative path or an absolute path.
375     * @return The file.
376     * @throws FileSystemException On error parsing the path, or on error finding the file.
377     */
378    FileObject resolveFile(String path) throws FileSystemException;
379
380    /**
381     * Finds a file relative to this file.
382     *
383     * Refer to {@link NameScope} for a description of how names are resolved in the different scopes.
384     *
385     * @param name The name to resolve.
386     * @param scope the NameScope for the file.
387     * @return The file.
388     * @throws FileSystemException On error parsing the path, or on error finding the file.
389     */
390    FileObject resolveFile(String name, NameScope scope) throws FileSystemException;
391
392    /**
393     * Sets the owner's (or everybody's) write permission.
394     *
395     * @param executable True to allow read access, false to disallow.
396     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
397     * @return true if the operation succeeded.
398     * @throws FileSystemException On error determining if this file exists.
399     * @since 2.1
400     */
401    boolean setExecutable(boolean executable, boolean ownerOnly) throws FileSystemException;
402
403    /**
404     * Sets the owner's (or everybody's) read permission.
405     *
406     * @param readable True to allow read access, false to disallow
407     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
408     * @return true if the operation succeeded
409     * @throws FileSystemException On error determining if this file exists.
410     * @since 2.1
411     */
412    boolean setReadable(boolean readable, boolean ownerOnly) throws FileSystemException;
413
414    /**
415     * Sets the owner's (or everybody's) write permission.
416     *
417     * @param writable True to allow read access, false to disallow
418     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
419     * @return true if the operation succeeded
420     * @throws FileSystemException On error determining if this file exists.
421     * @since 2.1
422     */
423    boolean setWritable(boolean writable, boolean ownerOnly) throws FileSystemException;
424}