You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2013/11/12 15:32:57 UTC
svn commit: r1541084 -
/commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java
Author: ggregory
Date: Tue Nov 12 14:32:56 2013
New Revision: 1541084
URL: http://svn.apache.org/r1541084
Log:
Sort in AB order.
Modified:
commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java
Modified: commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java
URL: http://svn.apache.org/viewvc/commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java?rev=1541084&r1=1541083&r2=1541084&view=diff
==============================================================================
--- commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java (original)
+++ commons/proper/vfs/trunk/core/src/main/java/org/apache/commons/vfs2/FileObject.java Tue Nov 12 14:32:56 2013
@@ -81,94 +81,131 @@ import org.apache.commons.vfs2.operation
public interface FileObject extends Comparable<FileObject>, Iterable<FileObject>, Closeable
{
/**
- * Returns the name of this file.
+ * Queries the file if it is possible to rename it to newfile.
*
- * @return the FileName.
+ * @param newfile the new file(-name)
+ * @return true it this is the case
*/
- FileName getName();
+ boolean canRenameTo(FileObject newfile);
/**
- * Returns a URL representing this file.
+ * Closes this file, and its content. This method is a hint to the
+ * implementation that it can release any resources associated with
+ * the file.
+ * <p>
+ * The file object can continue to be used after this method is called.
+ * </p>
*
- * @return the URL for the file.
- * @throws FileSystemException if an error occurs.
+ * @throws FileSystemException On error closing the file.
+ * @see FileContent#close
*/
- URL getURL() throws FileSystemException;
+ @Override
+ void close() throws FileSystemException;
/**
- * Determines if this file exists.
+ * Copies another file, and all its descendants, to this file.
+ * <p>
+ * If this file does not exist, it is created. Its parent folder is also
+ * created, if necessary. If this file does exist, it is deleted first.
+ * </p>
+ * <p>
+ * This method is not transactional. If it fails and throws an
+ * exception, this file will potentially only be partially copied.
+ * </p>
*
- * @return {@code true} if this file exists, {@code false} if not.
- * @throws FileSystemException On error determining if this file exists.
+ * @param srcFile The source file to copy.
+ * @param selector The selector to use to select which files to copy.
+ * @throws FileSystemException If this file is read-only, or if the source file does not exist,
+ * or on error copying the file.
*/
- boolean exists() throws FileSystemException;
+ void copyFrom(FileObject srcFile, FileSelector selector)
+ throws FileSystemException;
/**
- * Determines if this file is executable.
+ * Creates this file, if it does not exist. Also creates any ancestor
+ * folders which do not exist. This method does nothing if the file
+ * already exists and is a file.
*
- * @return {@code true} if this file is executable, {@code false} if not.
- * @throws FileSystemException On error determining if this file exists.
+ * @throws FileSystemException If the file already exists with the wrong type, or the parent
+ * folder is read-only, or on error creating this file or one of
+ * its ancestors.
*/
- boolean isExecutable() throws FileSystemException;
+ void createFile() throws FileSystemException;
/**
- * Determines if this file is hidden.
+ * Creates this folder, if it does not exist. Also creates any ancestor
+ * folders which do not exist. This method does nothing if the folder
+ * already exists.
*
- * @return {@code true} if this file is hidden, {@code false} if not.
- * @throws FileSystemException On error determining if this file exists.
+ * @throws FileSystemException If the folder already exists with the wrong type, or the parent
+ * folder is read-only, or on error creating this folder or one of
+ * its ancestors.
*/
- boolean isHidden() throws FileSystemException;
+ void createFolder() throws FileSystemException;
/**
- * Determines if this file can be read.
+ * Deletes this file. Does nothing if this file does not exist of if it is a
+ * folder that has children. Does not delete any descendants of this file,
+ * use {@link #delete(FileSelector)} or {@link #deleteAll()} for that.
*
- * @return {@code true} if this file is readable, {@code false} if not.
- * @throws FileSystemException On error determining if this file exists.
+ * @return true if this object has been deleted
+ * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only,
+ * or on error deleteing this file.
*/
- boolean isReadable() throws FileSystemException;
+ boolean delete() throws FileSystemException;
/**
- * Determines if this file can be written to.
+ * Deletes all descendants of this file that match a selector. Does
+ * nothing if this file does not exist.
*
- * @return {@code true} if this file is writeable, {@code false} if not.
- * @throws FileSystemException On error determining if this file exists.
+ * <p>This method is not transactional. If it fails and throws an
+ * exception, this file will potentially only be partially deleted.
+ * </p>
+ *
+ * @param selector The selector to use to select which files to delete.
+ * @return the number of deleted objects
+ * @throws FileSystemException If this file or one of its descendants is read-only, or on error
+ * deleting this file or one of its descendants.
*/
- boolean isWriteable() throws FileSystemException;
+ int delete(FileSelector selector) throws FileSystemException;
/**
- * Returns this file's type.
+ * Deletes this file and all children.
*
- * @return One of the {@link FileType} constants. Never returns null.
- * @throws FileSystemException On error determining the file's type.
+ * @return the number of deleted files.
+ * @throws FileSystemException if an error occurs.
+ * @see #delete(FileSelector)
+ * @see Selectors#SELECT_ALL
*/
- FileType getType() throws FileSystemException;
+ int deleteAll() throws FileSystemException;
/**
- * Returns the folder that contains this file.
+ * Determines if this file exists.
*
- * @return The folder that contains this file. Returns null if this file is
- * the root of a file system.
- * @throws FileSystemException On error finding the file's parent.
+ * @return {@code true} if this file exists, {@code false} if not.
+ * @throws FileSystemException On error determining if this file exists.
*/
- FileObject getParent() throws FileSystemException;
+ boolean exists() throws FileSystemException;
/**
- * Returns the file system that contains this file.
+ * Finds the set of matching descendants of this file, in depthwise order.
*
- * @return The file system.
+ * @param selector The selector to use to select matching files.
+ * @return The matching files. The files are returned in depthwise order
+ * (that is, a child appears in the list before its parent).
+ * @throws FileSystemException if an error occurs.
*/
- FileSystem getFileSystem();
+ FileObject[] findFiles(FileSelector selector) throws FileSystemException;
/**
- * Lists the children of this file.
- *
- * @return An array containing the children of this file. The array is
- * unordered. If the file does not have any children, a zero-length
- * array is returned. This method never returns null.
- * @throws FileSystemException If this file does not exist, or is not a folder, or on error
- * listing this file's children.
- */
- FileObject[] getChildren() throws FileSystemException;
+ * Finds the set of matching descendants of this file.
+ *
+ * @param selector the selector used to determine if the file should be selected
+ * @param depthwise controls the ordering in the list. e.g. deepest first
+ * @param selected container for selected files. list needs not to be empty.
+ * @throws FileSystemException if an error occurs.
+ */
+ void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;
/**
* Returns a child of this file. Note that this method returns {@code null}
@@ -183,167 +220,142 @@ public interface FileObject extends Comp
FileObject getChild(String name) throws FileSystemException;
/**
- * Finds a file relative to this file.
+ * Lists the children of this file.
*
- * Refer to {@link NameScope} for a description of how names are resolved in the different scopes.
+ * @return An array containing the children of this file. The array is
+ * unordered. If the file does not have any children, a zero-length
+ * array is returned. This method never returns null.
+ * @throws FileSystemException If this file does not exist, or is not a folder, or on error
+ * listing this file's children.
+ */
+ FileObject[] getChildren() throws FileSystemException;
+
+ /**
+ * Returns this file's content. The {@link FileContent} returned by this
+ * method can be used to read and write the content of the file.
*
- * @param name The name to resolve.
- * @param scope the NameScope for the file.
- * @return The file.
- * @throws FileSystemException On error parsing the path, or on error finding the file.
+ * <p>This method can be called if the file does not exist, and
+ * the returned {@link FileContent} can be used to create the file
+ * by writing its content.
+ * </p>
+ *
+ * @return This file's content.
+ * @throws FileSystemException On error getting this file's content.
*/
- FileObject resolveFile(String name, NameScope scope)
- throws FileSystemException;
+ FileContent getContent() throws FileSystemException;
/**
- * Sets the owner's (or everybody's) write permission.
+ * @return FileOperations interface that provides access to the operations API.
+ * @throws FileSystemException if an error occurs.
+ */
+ FileOperations getFileOperations() throws FileSystemException;
+
+ /**
+ * Returns the file system that contains this file.
*
- * @param executable
- * True to allow read access, false to disallow.
- * @param ownerOnly
- * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
- * @return true if the operation succeeded.
- * @throws FileSystemException
- * On error determining if this file exists.
- * @since 2.1
+ * @return The file system.
*/
- boolean setExecutable(boolean executable, boolean ownerOnly) throws FileSystemException;
+ FileSystem getFileSystem();
/**
- * Sets the owner's (or everybody's) read permission.
+ * Returns the name of this file.
*
- * @param readable
- * True to allow read access, false to disallow
- * @param ownerOnly
- * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
- * @return true if the operation succeeded
- * @throws FileSystemException
- * On error determining if this file exists.
- * @since 2.1
+ * @return the FileName.
*/
- boolean setReadable(boolean readable, boolean ownerOnly) throws FileSystemException;
+ FileName getName();
/**
- * Sets the owner's (or everybody's) write permission.
+ * Returns the folder that contains this file.
*
- * @param writable
- * True to allow read access, false to disallow
- * @param ownerOnly
- * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
- * @return true if the operation succeeded
- * @throws FileSystemException
- * On error determining if this file exists.
- * @since 2.1
+ * @return The folder that contains this file. Returns null if this file is
+ * the root of a file system.
+ * @throws FileSystemException On error finding the file's parent.
*/
- boolean setWritable(boolean writable, boolean ownerOnly) throws FileSystemException;
+ FileObject getParent() throws FileSystemException;
/**
- * Finds a file, relative to this file. Equivalent to calling
- * {@code resolveFile( path, NameScope.FILE_SYSTEM )}.
+ * Returns this file's type.
*
- * @param path The path of the file to locate. Can either be a relative
- * path or an absolute path.
- * @return The file.
- * @throws FileSystemException On error parsing the path, or on error finding the file.
+ * @return One of the {@link FileType} constants. Never returns null.
+ * @throws FileSystemException On error determining the file's type.
*/
- FileObject resolveFile(String path) throws FileSystemException;
+ FileType getType() throws FileSystemException;
/**
- * Finds the set of matching descendants of this file, in depthwise order.
+ * Returns a URL representing this file.
*
- * @param selector The selector to use to select matching files.
- * @return The matching files. The files are returned in depthwise order
- * (that is, a child appears in the list before its parent).
+ * @return the URL for the file.
* @throws FileSystemException if an error occurs.
*/
- FileObject[] findFiles(FileSelector selector) throws FileSystemException;
+ URL getURL() throws FileSystemException;
/**
- * Finds the set of matching descendants of this file.
- *
- * @param selector the selector used to determine if the file should be selected
- * @param depthwise controls the ordering in the list. e.g. deepest first
- * @param selected container for selected files. list needs not to be empty.
- * @throws FileSystemException if an error occurs.
- */
- void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;
+ * Checks if the fileObject is attached.
+ *
+ * @return true if the FileObject is attached.
+ */
+ boolean isAttached();
/**
- * Deletes this file. Does nothing if this file does not exist of if it is a
- * folder that has children. Does not delete any descendants of this file,
- * use {@link #delete(FileSelector)} or {@link #deleteAll()} for that.
+ * Checks if someone reads/write to this file.
*
- * @return true if this object has been deleted
- * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only,
- * or on error deleteing this file.
+ * @return true if the file content is open.
*/
- boolean delete() throws FileSystemException;
+ boolean isContentOpen();
/**
- * Deletes all descendants of this file that match a selector. Does
- * nothing if this file does not exist.
+ * Determines if this file is executable.
*
- * <p>This method is not transactional. If it fails and throws an
- * exception, this file will potentially only be partially deleted.
- * </p>
+ * @return {@code true} if this file is executable, {@code false} if not.
+ * @throws FileSystemException On error determining if this file exists.
+ */
+ boolean isExecutable() throws FileSystemException;
+
+ /**
+ * Checks if this file is a regular file.
*
- * @param selector The selector to use to select which files to delete.
- * @return the number of deleted objects
- * @throws FileSystemException If this file or one of its descendants is read-only, or on error
- * deleting this file or one of its descendants.
+ * @return true if this file is a regular file.
+ * @throws FileSystemException if an error occurs.
+ * @see #getType()
+ * @see FileType#FILE
+ * @since 2.1
*/
- int delete(FileSelector selector) throws FileSystemException;
+ boolean isFile() throws FileSystemException;
/**
- * Deletes this file and all children.
+ * Checks if this file is a folder.
*
- * @return the number of deleted files.
+ * @return true if this file is a folder.
* @throws FileSystemException if an error occurs.
- * @see #delete(FileSelector)
- * @see Selectors#SELECT_ALL
+ * @see #getType()
+ * @see FileType#FOLDER
+ * @since 2.1
*/
- int deleteAll() throws FileSystemException;
+ boolean isFolder() throws FileSystemException;
/**
- * Creates this folder, if it does not exist. Also creates any ancestor
- * folders which do not exist. This method does nothing if the folder
- * already exists.
+ * Determines if this file is hidden.
*
- * @throws FileSystemException If the folder already exists with the wrong type, or the parent
- * folder is read-only, or on error creating this folder or one of
- * its ancestors.
+ * @return {@code true} if this file is hidden, {@code false} if not.
+ * @throws FileSystemException On error determining if this file exists.
*/
- void createFolder() throws FileSystemException;
+ boolean isHidden() throws FileSystemException;
/**
- * Creates this file, if it does not exist. Also creates any ancestor
- * folders which do not exist. This method does nothing if the file
- * already exists and is a file.
+ * Determines if this file can be read.
*
- * @throws FileSystemException If the file already exists with the wrong type, or the parent
- * folder is read-only, or on error creating this file or one of
- * its ancestors.
+ * @return {@code true} if this file is readable, {@code false} if not.
+ * @throws FileSystemException On error determining if this file exists.
*/
- void createFile() throws FileSystemException;
+ boolean isReadable() throws FileSystemException;
/**
- * Copies another file, and all its descendants, to this file.
- * <p>
- * If this file does not exist, it is created. Its parent folder is also
- * created, if necessary. If this file does exist, it is deleted first.
- * </p>
- * <p>
- * This method is not transactional. If it fails and throws an
- * exception, this file will potentially only be partially copied.
- * </p>
+ * Determines if this file can be written to.
*
- * @param srcFile The source file to copy.
- * @param selector The selector to use to select which files to copy.
- * @throws FileSystemException If this file is read-only, or if the source file does not exist,
- * or on error copying the file.
+ * @return {@code true} if this file is writeable, {@code false} if not.
+ * @throws FileSystemException On error determining if this file exists.
*/
- void copyFrom(FileObject srcFile, FileSelector selector)
- throws FileSystemException;
+ boolean isWriteable() throws FileSystemException;
/**
* Move this file.
@@ -360,42 +372,6 @@ public interface FileObject extends Comp
throws FileSystemException;
/**
- * Queries the file if it is possible to rename it to newfile.
- *
- * @param newfile the new file(-name)
- * @return true it this is the case
- */
- boolean canRenameTo(FileObject newfile);
-
- /**
- * Returns this file's content. The {@link FileContent} returned by this
- * method can be used to read and write the content of the file.
- *
- * <p>This method can be called if the file does not exist, and
- * the returned {@link FileContent} can be used to create the file
- * by writing its content.
- * </p>
- *
- * @return This file's content.
- * @throws FileSystemException On error getting this file's content.
- */
- FileContent getContent() throws FileSystemException;
-
- /**
- * Closes this file, and its content. This method is a hint to the
- * implementation that it can release any resources associated with
- * the file.
- * <p>
- * The file object can continue to be used after this method is called.
- * </p>
- *
- * @throws FileSystemException On error closing the file.
- * @see FileContent#close
- */
- @Override
- void close() throws FileSystemException;
-
- /**
* This will prepare the fileObject to get resynchronized with the underlying file system if required.
*
* @throws FileSystemException if an error occurs.
@@ -403,45 +379,69 @@ public interface FileObject extends Comp
void refresh() throws FileSystemException;
/**
- * Checks if the fileObject is attached.
+ * Finds a file, relative to this file. Equivalent to calling
+ * {@code resolveFile( path, NameScope.FILE_SYSTEM )}.
*
- * @return true if the FileObject is attached.
+ * @param path The path of the file to locate. Can either be a relative
+ * path or an absolute path.
+ * @return The file.
+ * @throws FileSystemException On error parsing the path, or on error finding the file.
*/
- boolean isAttached();
+ FileObject resolveFile(String path) throws FileSystemException;
/**
- * Checks if someone reads/write to this file.
+ * Finds a file relative to this file.
*
- * @return true if the file content is open.
+ * Refer to {@link NameScope} for a description of how names are resolved in the different scopes.
+ *
+ * @param name The name to resolve.
+ * @param scope the NameScope for the file.
+ * @return The file.
+ * @throws FileSystemException On error parsing the path, or on error finding the file.
*/
- boolean isContentOpen();
+ FileObject resolveFile(String name, NameScope scope)
+ throws FileSystemException;
/**
- * Checks if this file is a regular file.
+ * Sets the owner's (or everybody's) write permission.
*
- * @return true if this file is a regular file.
- * @throws FileSystemException if an error occurs.
- * @see #getType()
- * @see FileType#FILE
+ * @param executable
+ * True to allow read access, false to disallow.
+ * @param ownerOnly
+ * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
+ * @return true if the operation succeeded.
+ * @throws FileSystemException
+ * On error determining if this file exists.
* @since 2.1
*/
- boolean isFile() throws FileSystemException;
+ boolean setExecutable(boolean executable, boolean ownerOnly) throws FileSystemException;
/**
- * Checks if this file is a folder.
+ * Sets the owner's (or everybody's) read permission.
*
- * @return true if this file is a folder.
- * @throws FileSystemException if an error occurs.
- * @see #getType()
- * @see FileType#FOLDER
+ * @param readable
+ * True to allow read access, false to disallow
+ * @param ownerOnly
+ * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
+ * @return true if the operation succeeded
+ * @throws FileSystemException
+ * On error determining if this file exists.
* @since 2.1
*/
- boolean isFolder() throws FileSystemException;
+ boolean setReadable(boolean readable, boolean ownerOnly) throws FileSystemException;
/**
- * @return FileOperations interface that provides access to the operations API.
- * @throws FileSystemException if an error occurs.
+ * Sets the owner's (or everybody's) write permission.
+ *
+ * @param writable
+ * True to allow read access, false to disallow
+ * @param ownerOnly
+ * If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
+ * @return true if the operation succeeded
+ * @throws FileSystemException
+ * On error determining if this file exists.
+ * @since 2.1
*/
- FileOperations getFileOperations() throws FileSystemException;
+ boolean setWritable(boolean writable, boolean ownerOnly) throws FileSystemException;
}