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
027 * structure of the file.
028 * <p>
029 * Files are arranged in a hierarchy.  Each hierarchy forms a
030 * <i>file system</i>.  A file system represents things like a local OS
031 * file system, a windows share, an HTTP server, or the contents of a Zip file.
032 * <p>
033 * There are two types of files: <i>Folders</i>, which contain other files,
034 * and <i>normal files</i>, which contain data, or <i>content</i>.  A folder may
035 * not have any content, and a normal file cannot contain other files.
036 *
037 * <h2>File Naming</h2>
038 *
039 * TODO - write this.
040 *
041 * <h2>Reading and Writing a File</h2>
042 *
043 * Reading and writing a file, and all other operations on the file's
044 * <i>content</i>, is done using the {@link FileContent} object returned
045 * by {@link #getContent}.
046
047 * <h2>Creating and Deleting a File</h2>
048 *
049 * A file is created using either {@link #createFolder}, {@link #createFile},
050 * or by writing to the file using one of the {@link FileContent} methods.
051 * <p>
052 * A file is deleted using {@link #delete}.  Recursive deletion can be
053 * done using {@link #delete(FileSelector)}.
054 *
055 * <h2>Finding Files</h2>
056 *
057 * Other files in the <i>same</i> file system as this file can be found
058 * using:
059 * <ul>
060 * <li>{@link #findFiles} to find a set of matching descendants in in the same file system.</li>
061 * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.</li>
062 * <li>{@link #getParent} to find the folder containing this file.</li>
063 * <li>{@link #getFileSystem} to find another file in the same file system.</li>
064 * <li>{@link #resolveFile} to find another file relative to this file.</li>
065 * </ul>
066 * To find files in another file system, use a {@link FileSystemManager}.
067 *
068 * <h2>Iterating Files</h2>
069 *
070 * You can iterate over a FileObject using the Java "foreach" statement, which provides all descendants of a File
071 * Object.
072 *
073 * <h2>Sorting Files</h2>
074 *
075 * Files may be sorted using {@link java.util.Arrays#sort(Object[]) Arrays.sort()}
076 * and {@link java.util.Collections#sort(List) Collections.sort()}.
077 *
078 * @see FileSystemManager
079 * @see FileContent
080 * @see FileName
081 */
082public interface FileObject extends Comparable<FileObject>, Iterable<FileObject>, Closeable
083{
084    /**
085     * Queries the file if it is possible to rename it to newfile.
086     *
087     * @param newfile the new file(-name)
088     * @return true it this is the case
089     */
090    boolean canRenameTo(FileObject newfile);
091
092    /**
093     * Closes this file, and its content.  This method is a hint to the
094     * implementation that it can release any resources associated with
095     * the file.
096     * <p>
097     * The file object can continue to be used after this method is called.
098     * </p>
099     *
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}