harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [3/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Date Fri, 01 May 2009 08:09:01 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java Fri May  1 08:08:59 2009
@@ -31,12 +31,13 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * File is a class which represents a file name or directory. The file may be
- * absolute relative to the root directory of the file system or relative to the
- * current directory in which the program is running.
+ * An "abstract" representation of a file system entity identified by a
+ * pathname. The pathname may be absolute (relative to the root directory
+ * of the file system) or relative to the current directory in which the program
+ * is running.
  * <p>
  * This class provides methods for querying/changing information about the file
- * and also directory listing capabilities if the File represents a directory.
+ * as well as directory listing capabilities if the file represents a directory.
  * <p>
  * When manipulating file paths, the static fields of this class may be used to
  * determine the platform specific separators.
@@ -55,24 +56,24 @@
     transient byte[] properPath;
 
     /**
-     * System dependent file separator character.
+     * The system dependent file separator character.
      */
     public static final char separatorChar;
 
     /**
-     * System dependent file separator String. The initial value of this field
-     * is the System property "file.separator".
+     * The system dependent file separator string. The initial value of this
+     * field is the system property "file.separator".
      */
     public static final String separator;
 
     /**
-     * System dependent path separator character.
+     * The system dependent path separator character.
      */
     public static final char pathSeparatorChar;
 
     /**
-     * System dependent path separator String. The initial value of this field
-     * is the System property "path.separator".
+     * The system dependent path separator string. The initial value of this
+     * field is the system property "path.separator".
      */
     public static final String pathSeparator;
 
@@ -95,12 +96,14 @@
     }
 
     /**
-     * Constructs a new File using the specified directory and name.
+     * Constructs a new file using the specified directory and name.
      * 
      * @param dir
-     *            the directory for the file name
+     *            the directory where the file is stored.
      * @param name
-     *            the file name to be contained in the dir
+     *            the file's name.
+     * @throws NullPointerException
+     *             if {@code name} is null.
      */
     public File(File dir, String name) {
         if (name == null) {
@@ -114,10 +117,10 @@
     }
 
     /**
-     * Constructs a new File using the specified path.
+     * Constructs a new file using the specified path.
      * 
      * @param path
-     *            the path to be used for the file
+     *            the path to be used for the file.
      */
     public File(String path) {
         // path == null check & NullPointerException thrown by fixSlashes
@@ -125,13 +128,15 @@
     }
 
     /**
-     * Constructs a new File using the specified directory and name placing a
-     * path separator between the two.
+     * Constructs a new File using the specified directory path and file name,
+     * placing a path separator between the two.
      * 
      * @param dirPath
-     *            the directory for the file name
+     *            the path to the directory where the file is stored.
      * @param name
-     *            the file name to be contained in the dir
+     *            the file's name.
+     * @throws NullPointerException
+     *             if {@code name} is null.
      */
     public File(String dirPath, String name) {
         if (name == null) {
@@ -145,19 +150,16 @@
     }
 
     /**
-     * Constructs a new File using the path of the specified URI
-     * 
-     * <code>uri</code> needs to be an absolute and hierarchical
-     * <code>URI </code> with file scheme, and non-empty path component, but
-     * with undefined authority, query or fragment components.
+     * Constructs a new File using the path of the specified URI. {@code uri}
+     * needs to be an absolute and hierarchical Unified Resource Identifier with
+     * file scheme and non-empty path component, but with undefined authority,
+     * query or fragment components.
      * 
      * @param uri
-     *            the URI instance which will be used to construct this file
-     * 
+     *            the Unified Resource Identifier that is used to construct this
+     *            file.
      * @throws IllegalArgumentException
-     *             if <code>uri</code> does not comply with the conditions
-     *             above.
-     * 
+     *             if {@code uri} does not comply with the conditions above.
      * @see #toURI
      * @see java.net.URI
      */
@@ -232,13 +234,12 @@
     private static native boolean isCaseSensitiveImpl();
 
     /**
-     * Lists the filesystem roots.
+     * Lists the file system roots. The Java platform may support zero or more
+     * file systems, each with its own platform-dependent root. Further, the
+     * canonical pathname of any file on the system will always begin with one
+     * of the returned file system roots.
      * 
-     * The Java platform may support zero or more filesystems, each with its own
-     * platform-dependent root. Further, the canonical pathname of any file on
-     * the system will always begin with one of the returned filesystem roots.
-     * 
-     * @return the array of filesystem roots
+     * @return the array of file system roots.
      */
     public static File[] listRoots() {
         byte[][] rootsList = rootsImpl();
@@ -302,13 +303,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not the current context is
-     * allowed to read this File.
+     * Indicates whether the current context is allowed to read from this file.
      * 
-     * @return <code>true</code> if this File can be read, <code>false</code>
-     *         otherwise.
-     * 
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
+     * @return {@code true} if this file can be read, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             read request.
      */
     public boolean canRead() {
         if (path.length() == 0) {
@@ -323,13 +323,13 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not the current context is
-     * allowed to write to this File.
+     * Indicates whether the current context is allowed to write to this file.
      * 
-     * @return <code>true</code> if this File can be written,
-     *         <code>false</code> otherwise.
-     * 
-     * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
+     * @return {@code true} if this file can be written, {@code false}
+     *         otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      */
     public boolean canWrite() {
         SecurityManager security = System.getSecurityManager();
@@ -346,12 +346,12 @@
     }
 
     /**
-     * Answers the relative sort ordering of paths for the receiver and given
-     * argument. The ordering is platform dependent.
+     * Returns the relative sort ordering of the paths for this file and the
+     * file {@code another}. The ordering is platform dependent.
      * 
      * @param another
-     *            a File to compare the receiver to
-     * @return an int determined by comparing the two paths. The meaning is
+     *            a file to compare this file to
+     * @return an int determined by comparing the two paths. Possible values are
      *         described in the Comparable interface.
      * @see Comparable
      */
@@ -363,12 +363,12 @@
     }
 
     /**
-     * Deletes the file specified by this File. Directories must be empty before
-     * they will be deleted.
-     * 
-     * @return <code>true</code> if this File was deleted, <code>false</code>
-     *         otherwise.
+     * Deletes this file. Directories must be empty before they will be deleted.
      * 
+     * @return {@code true} if this file was deleted, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             request.
      * @see java.lang.SecurityManager#checkDelete
      */
     public boolean delete() {
@@ -388,11 +388,13 @@
     private native boolean deleteFileImpl(byte[] filePath);
 
     /**
-     * When the virtual machine terminates, any abstract files which have been
-     * sent <code>deleteOnExit()</code> will be deleted. This will only happen
-     * when the virtual machine terminates normally as described by the Java
-     * Language Specification section 12.9.
-     * 
+     * Schedules this file to be automatically deleted once the virtual machine
+     * terminates. This will only happen when the virtual machine terminates
+     * normally as described by the Java Language Specification section 12.9.
+     * 
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             request.
      */
     public void deleteOnExit() {
         SecurityManager security = System.getSecurityManager();
@@ -404,14 +406,13 @@
     }
 
     /**
-     * Compares the argument <code>obj</code> to the receiver, and answers
-     * <code>true</code> if they represent the <em>same</em> object using a
-     * path specific comparison.
+     * Compares {@code obj} to this file and returns {@code true} if they
+     * represent the <em>same</em> object using a path specific comparison.
      * 
      * @param obj
-     *            the Object to compare with this Object
-     * @return <code>true</code> if the object is the same as this object,
-     *         <code>false</code> otherwise.
+     *            the object to compare this file with.
+     * @return {@code true} if {@code obj} is the same as this object,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object obj) {
@@ -425,12 +426,13 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this File can be found on the
+     * Returns a boolean indicating whether this file can be found on the
      * underlying file system.
      * 
-     * @return <code>true</code> if this File exists, <code>false</code>
-     *         otherwise.
-     * 
+     * @return {@code true} if this file exists, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      * @see #getPath
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
      */
@@ -448,10 +450,9 @@
     private native boolean existsImpl(byte[] filePath);
 
     /**
-     * Answers the absolute file path of this File.
-     * 
-     * @return the absolute file path
+     * Returns the absolute path of this file.
      * 
+     * @return the absolute file path.
      * @see java.lang.SecurityManager#checkPropertyAccess
      */
     public String getAbsolutePath() {
@@ -460,10 +461,9 @@
     }
 
     /**
-     * Answers a new File constructed using the absolute file path of this File.
-     * 
-     * @return a new File from this absolute file path
+     * Returns a new file constructed using the absolute path of this file.
      * 
+     * @return a new file from this file's absolute path.
      * @see java.lang.SecurityManager#checkPropertyAccess
      */
     public File getAbsoluteFile() {
@@ -471,20 +471,18 @@
     }
 
     /**
-     * Answers the absolute file path of this File with all references resolved.
-     * An <em>absolute</em> file path is one which begins at the root of the
-     * file system. The canonical path is one in which all references have been
-     * resolved. For the cases of '..' and '.' where the file system supports
-     * parent and working directory respectively, these should be removed and
-     * replaced with a direct directory reference. If the File does not exist,
-     * getCanonicalPath() may not resolve any references and simply return an
-     * absolute path name or throw an IOException.
-     * 
-     * @return the canonical file path
+     * Returns the absolute path of this file with all references resolved. An
+     * <em>absolute</em> path is one that begins at the root of the file
+     * system. The canonical path is one in which all references have been
+     * resolved. For the cases of '..' and '.', where the file system supports
+     * parent and working directory respectively, these are removed and replaced
+     * with a direct directory reference. If the file does not exist,
+     * getCanonicalPath() may not resolve any references and simply returns an
+     * absolute path name or throws an IOException.
      * 
+     * @return the canonical path of this file.
      * @throws IOException
-     *             if an IO error occurs
-     * 
+     *             if an I/O error occurs.
      * @see java.lang.SecurityManager#checkPropertyAccess
      */
     public String getCanonicalPath() throws IOException {
@@ -651,14 +649,12 @@
     }
 
     /**
-     * Answers a new File created using the canonical file path of this File.
-     * Equivalent to <code>new File(this.getCanonicalPath())</code>.
-     * 
-     * @return the canonical file path
+     * Returns a new file created using the canonical path of this file.
+     * Equivalent to {@code new File(this.getCanonicalPath())}.
      * 
+     * @return the new file constructed from this file's canonical path.
      * @throws IOException
-     *             If an IO error occurs
-     * 
+     *             if an I/O error occurs.
      * @see java.lang.SecurityManager#checkPropertyAccess
      */
     public File getCanonicalFile() throws IOException {
@@ -668,9 +664,10 @@
     private native byte[] getCanonImpl(byte[] filePath);
 
     /**
-     * Answers the filename (not directory) of this File.
+     * Returns the name of the file or directory represented by this file.
      * 
-     * @return the filename or empty string
+     * @return this file's name or an empty string if there is no name part in
+     *         the file's path.
      */
     public String getName() {
         int separatorIndex = path.lastIndexOf(separator);
@@ -679,11 +676,11 @@
     }
 
     /**
-     * Answers the pathname of the parent of this File. This is the path up to
-     * but not including the last name. <code>null</code> is returned when
-     * there is no parent.
+     * Returns the pathname of the parent of this file. This is the path up to
+     * but not including the last name. {@code null} is returned if there is no
+     * parent.
      * 
-     * @return the parent name or <code>null</code>
+     * @return this file's parent pathname or {@code null}.
      */
     public String getParent() {
         int length = path.length(), firstInPath = 0;
@@ -705,11 +702,11 @@
     }
 
     /**
-     * Answers a new File made from the pathname of the parent of this File.
-     * This is the path up to but not including the last name. <code>null</code>
-     * is returned when there is no parent.
+     * Returns a new file made from the pathname of the parent of this file.
+     * This is the path up to but not including the last name. {@code null} is
+     * returned when there is no parent.
      * 
-     * @return a new File representing parent or <code>null</code>
+     * @return a new file representing this file's parent or {@code null}.
      */
     public File getParentFile() {
         String tempParent = getParent();
@@ -720,21 +717,19 @@
     }
 
     /**
-     * Answers the file path of this File.
+     * Returns the path of this file.
      * 
-     * @return the file path
+     * @return this file's path.
      */
     public String getPath() {
         return path;
     }
 
     /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
+     * Returns an integer hash code for the receiver. Any two objects for which
+     * {@code equals} returns {@code true} must return the same hash code.
      * 
+     * @return this files's hash value.
      * @see #equals
      */
     @Override
@@ -746,14 +741,14 @@
     }
 
     /**
-     * Answers if this File is an absolute pathname. Whether a pathname is
-     * absolute is platform specific. On UNIX it is if the path starts with the
-     * character '/', on Windows it is absolute if either it starts with '\',
-     * '/', '\\' (to represent a file server), or a letter followed by ':\'.
+     * Indicates if this file's pathname is absolute. Whether a pathname is
+     * absolute is platform specific. On UNIX, absolute paths must start with
+     * the character '/'; on Windows it is absolute if either it starts with
+     * '\', '/', '\\' (to represent a file server), or a letter followed by a
+     * colon.
      * 
-     * @return <code>true</code> if this File is absolute, <code>false</code>
+     * @return {@code true} if this file's pathname is absolute, {@code false}
      *         otherwise.
-     * 
      * @see #getPath
      */
     public boolean isAbsolute() {
@@ -763,14 +758,14 @@
     private native boolean isAbsoluteImpl(byte[] filePath);
 
     /**
-     * Answers if this File represents a <em>directory</em> on the underlying
-     * file system.
-     * 
-     * @return <code>true</code> if this File is a directory,
-     *         <code>false</code> otherwise.
+     * Indicates if this file represents a <em>directory</em> on the
+     * underlying file system.
      * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
+     * @return {@code true} if this file is a directory, {@code false}
+     *         otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      */
     public boolean isDirectory() {
         if (path.length() == 0) {
@@ -786,14 +781,13 @@
     private native boolean isDirectoryImpl(byte[] filePath);
 
     /**
-     * Answers if this File represents a <em>file</em> on the underlying file
-     * system.
-     * 
-     * @return <code>true</code> if this File is a file, <code>false</code>
-     *         otherwise.
+     * Indicates if this file represents a <em>file</em> on the underlying
+     * file system.
      * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
+     * @return {@code true} if this file is a file, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      */
     public boolean isFile() {
         if (path.length() == 0) {
@@ -810,10 +804,15 @@
 
     /**
      * Returns whether or not this file is a hidden file as defined by the
-     * operating system.
-     * 
-     * @return <code>true</code> if the file is hidden, <code>false</code>
-     *         otherwise.
+     * operating system. The notion of "hidden" is system-dependent. For Unix
+     * systems a file is considered hidden if its name starts with a ".". For
+     * Windows systems there is an explicit flag in the file system for this
+     * purpose.
+     * 
+     * @return {@code true} if the file is hidden, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      */
     public boolean isHidden() {
         if (path.length() == 0) {
@@ -835,12 +834,13 @@
     private native byte[] getLinkImpl(byte[] filePath);
 
     /**
-     * Answers the time this File was last modified.
+     * Returns the time when this file was last modified, measured in
+     * milliseconds since January 1st, 1970, midnight.
      * 
-     * @return the time this File was last modified.
-     * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
+     * @return the time when this file was last modified.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      */
     public long lastModified() {
         SecurityManager security = System.getSecurityManager();
@@ -858,13 +858,18 @@
     private native long lastModifiedImpl(byte[] filePath);
 
     /**
-     * Sets the time this File was last modified.
+     * Sets the time this file was last modified, measured in milliseconds since
+     * January 1st, 1970, midnight.
      * 
      * @param time
-     *            The time to set the file as last modified.
-     * @return the time this File was last modified.
-     * 
-     * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
+     *            the last modification time for this file.
+     * @return {@code true} if the operation is successful, {@code false}
+     *         otherwise.
+     * @throws IllegalArgumentException
+     *             if {@code time < 0}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access to this file.
      */
     public boolean setLastModified(long time) {
         if (time < 0) {
@@ -883,8 +888,11 @@
      * Marks this file or directory to be read-only as defined by the operating
      * system.
      * 
-     * @return <code>true</code> if the operation was a success,
-     *         <code>false</code> otherwise
+     * @return {@code true} if the operation is successful, {@code false}
+     *         otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access to this file.
      */
     public boolean setReadOnly() {
         SecurityManager security = System.getSecurityManager();
@@ -897,12 +905,12 @@
     private native boolean setReadOnlyImpl(byte[] path);
 
     /**
-     * Answers the length of this File in bytes.
+     * Returns the length of this file in bytes.
      * 
-     * @return the number of bytes in the file.
-     * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
+     * @return the number of bytes in this file.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      */
     public long length() {
         SecurityManager security = System.getSecurityManager();
@@ -915,16 +923,17 @@
     private native long lengthImpl(byte[] filePath);
 
     /**
-     * Answers an array of Strings representing the file names in the directory
-     * represented by this File. If this File is not a directory the result is
-     * <code>null</code>.
+     * Returns an array of strings with the file names in the directory
+     * represented by this file. The result is {@code null} if this file is not
+     * a directory.
      * <p>
-     * The entries <code>.</code> and <code>..</code> representing current
-     * directory and parent directory are not returned as part of the list.
-     * 
-     * @return an array of Strings or <code>null</code>.
-     * 
-     * @see #getPath
+     * The entries {@code .} and {@code ..} representing the current and parent
+     * directory are not returned as part of the list.
+     *
+     * @return an array of strings with file names or {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      * @see #isDirectory
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
      */
@@ -956,15 +965,16 @@
     }
 
     /**
-     * Answers an array of Files representing the file names in the directory
-     * represented by this File. If this File is not a directory the result is
-     * <code>null</code>. The Files returned will be absolute if this File is
-     * absolute, relative otherwise.
-     * 
-     * @return an array of Files or <code>null</code>.
-     * 
-     * @see #getPath
-     * @see #list()
+     * Returns an array of files contained in the directory represented by this
+     * file. The result is {@code null} if this file is not a directory. The
+     * paths of the files in the array are absolute if the path of this file is
+     * absolute, they are relative otherwise.
+     * 
+     * @return an array of files or {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
+     * @see #list
      * @see #isDirectory
      */
     public File[] listFiles() {
@@ -981,18 +991,21 @@
     }
 
     /**
-     * Answers an array of Files representing the file names in the directory
-     * represented by this File that match a specific filter. If this File is
-     * not a directory the result is <code>null</code>. If the filter is
-     * <code>null</code> then all filenames match.
+     * Gets a list of the files in the directory represented by this file. This
+     * list is then filtered through a FilenameFilter and files with matching
+     * names are returned as an array of files. Returns {@code null} if this
+     * file is not a directory. If {@code filter} is {@code null} then all
+     * filenames match.
      * <p>
-     * The entries <code>.</code> and <code>..</code> representing current
-     * directory and parent directory are not returned as part of the list.
-     * 
+     * The entries {@code .} and {@code ..} representing the current and parent
+     * directories are not returned as part of the list.
+     *
      * @param filter
-     *            the filter to match names to or <code>null</code>.
-     * @return an array of Files or <code>null</code>.
-     * 
+     *            the filter to match names against, may be {@code null}.
+     * @return an array of files or {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      * @see #list(FilenameFilter filter)
      * @see #getPath
      * @see #isDirectory
@@ -1012,18 +1025,20 @@
     }
 
     /**
-     * Answers an array of Files representing the file names in the directory
-     * represented by this File that match a specific filter. If this File is
-     * not a directory the result is <code>null</code>. If the filter is
-     * <code>null</code> then all filenames match.
+     * Gets a list of the files in the directory represented by this file. This
+     * list is then filtered through a FileFilter and matching files are
+     * returned as an array of files. Returns {@code null} if this file is not a
+     * directory. If {@code filter} is {@code null} then all files match.
      * <p>
-     * The entries <code>.</code> and <code>..</code> representing current
-     * directory and parent directory are not returned as part of the list.
-     * 
+     * The entries {@code .} and {@code ..} representing the current and parent
+     * directories are not returned as part of the list.
+     *
      * @param filter
-     *            the filter to match names to or <code>null</code>.
-     * @return an array of Files or <code>null</code>.
-     * 
+     *            the filter to match names against, may be {@code null}.
+     * @return an array of files or {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      * @see #getPath
      * @see #isDirectory
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
@@ -1059,18 +1074,21 @@
     }
 
     /**
-     * Answers an array of Strings representing the file names in the directory
-     * represented by this File that match a specific filter. If this File is
-     * not a directory the result is <code>null</code>. If the filter is
-     * <code>null</code> then all filenames match.
+     * Gets a list of the files in the directory represented by this file. This
+     * list is then filtered through a FilenameFilter and the names of files
+     * with matching names are returned as an array of strings. Returns
+     * {@code null} if this file is not a directory. If {@code filter} is
+     * {@code null} then all filenames match.
      * <p>
-     * The entries <code>.</code> and <code>..</code> representing current
-     * directory and parent directory are not returned as part of the list.
+     * The entries {@code .} and {@code ..} representing the current and parent
+     * directories are not returned as part of the list.
      * 
      * @param filter
-     *            the filter to match names to or <code>null</code>.
-     * @return an array of Strings or <code>null</code>.
-     * 
+     *            the filter to match names against, may be {@code null}.
+     * @return an array of files or {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies read
+     *             access to this file.
      * @see #getPath
      * @see #isDirectory
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
@@ -1109,14 +1127,15 @@
     private synchronized static native byte[][] listImpl(byte[] path);
 
     /**
-     * Creates the directory named by the trailing filename of this File. Not
-     * all directories required to create this File are created.
+     * Creates the directory named by the trailing filename of this file. Does
+     * not create the complete path required to create this directory.
      * 
-     * @return <code>true</code> if the directory was created,
-     *         <code>false</code> otherwise.
-     * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
+     * @return {@code true} if the directory has been created, {@code false}
+     *         otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access for this file.
+     * @see #mkdirs
      */
     public boolean mkdir() {
         SecurityManager security = System.getSecurityManager();
@@ -1129,13 +1148,16 @@
     private native boolean mkdirImpl(byte[] filePath);
 
     /**
-     * Create all the directories needed for this File. If the terminal
-     * directory already exists, answer false. If the directories were created
-     * successfully, answer <code>true</code>.
-     * 
-     * @return <code>true</code> if the necessary directories were created,
-     *         <code>false</code> otherwise.
+     * Creates the directory named by the trailing filename of this file,
+     * including the complete directory path required to create this directory.
      * 
+     * @return {@code true} if the necessary directories have been created,
+     *         {@code false} if the target directory already exists or one of
+     *         the directories can not be created.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access for this file.
+     * @see #mkdir
      */
     public boolean mkdirs() {
         /* If the terminal directory already exists, answer false */
@@ -1159,18 +1181,17 @@
     }
 
     /**
-     * Creates the file specified by this File. If the file already exists this
-     * method returns <code>false</code>. Otherwise, if the file is created
-     * successfully, the result is <code>true</code>. An IOException will be
-     * thrown if the directory to contain this file does not exist.
-     * 
-     * @return <code>true</code> if this File was created, <code>false</code>
-     *         otherwise.
+     * Creates a new, empty file on the file system according to the path
+     * information stored in this file.
      * 
+     * @return {@code true} if the file has been created, {@code false} if it
+     *         already exists.
      * @throws IOException
-     *             if an I/O error occurs or the directory does not exist.
-     * 
-     * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
+     *             if an I/O error occurs or the directory does not exist where
+     *             the file should have been created.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access for this file.
      */
     public boolean createNewFile() throws IOException {
         SecurityManager security = System.getSecurityManager();
@@ -1195,16 +1216,17 @@
 
     /**
      * Creates an empty temporary file using the given prefix and suffix as part
-     * of the file name. If suffix is null, <code>.tmp</code> is used.
+     * of the file name. If suffix is null, {@code .tmp} is used. This method
+     * is a convenience method that calls {@link #createTempFile(String, String,
+     * File)} with the third argument being {@code null}.
      * 
      * @param prefix
-     *            the prefix to the temp file name
+     *            the prefix to the temp file name.
      * @param suffix
-     *            the suffix to the temp file name
-     * @return the temporary file
-     * 
+     *            the suffix to the temp file name.
+     * @return the temporary file.
      * @throws IOException
-     *             If an error occurs when writing the file
+     *             if an error occurs when writing the file.
      */
     public static File createTempFile(String prefix, String suffix)
             throws IOException {
@@ -1216,16 +1238,20 @@
      * prefix and suffix as part of the file name.
      * 
      * @param prefix
-     *            the prefix to the temp file name
+     *            the prefix to the temp file name.
      * @param suffix
-     *            the suffix to the temp file name
+     *            the suffix to the temp file name.
      * @param directory
-     *            the location to which the temp file is to be written, or null
-     *            for the default temp location
-     * @return the temporary file
-     * 
+     *            the location to which the temp file is to be written, or
+     *            {@code null} for the default location for temporary files,
+     *            which is taken from the "java.io.tmpdir" system property. It
+     *            may be necessary to set this property to an existing, writable
+     *            directory for this method to work properly.
+     * @return the temporary file.
+     * @throws IllegalArgumentException
+     *             if the length of {@code prefix} is less than 3.
      * @throws IOException
-     *             If an error occurs when writing the file
+     *             if an error occurs when writing the file.
      */
     @SuppressWarnings("nls")
     public static File createTempFile(String prefix, String suffix,
@@ -1263,12 +1289,13 @@
     }
 
     /**
-     * Answer a String representing the proper path for the receiver. If the
-     * receiver is absolute do not prepend the user.dir property, otherwise do.
+     * Returns a string representing the proper path for this file. If this file
+     * path is absolute, the user.dir property is not prepended, otherwise it
+     * is.
      * 
      * @param internal
-     *            is user.dir internal
-     * @return the proper path
+     *            is user.dir internal.
+     * @return the proper path.
      */
     byte[] properPath(boolean internal) {
         if (properPath != null) {
@@ -1318,17 +1345,15 @@
     private static native byte[] properPathImpl(byte[] path);
 
     /**
-     * Renames this File to the name represented by the File <code>dest</code>.
-     * This works for both normal files and directories.
+     * Renames this file to the name represented by the {@code dest} file. This
+     * works for both normal files and directories.
      * 
      * @param dest
-     *            the File containing the new name.
-     * @return <code>true</code> if the File was renamed, <code>false</code>
-     *         otherwise.
-     * 
-     * @see #getPath
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
-     * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
+     *            the file containing the new name.
+     * @return {@code true} if the File was renamed, {@code false} otherwise.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies write
+     *             access for this file or the {@code dest} file.
      */
     public boolean renameTo(java.io.File dest) {
         SecurityManager security = System.getSecurityManager();
@@ -1342,10 +1367,10 @@
     private native boolean renameToImpl(byte[] pathExist, byte[] pathNew);
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable description of this
+     * file.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation of this file.
      */
     @Override
     public String toString() {
@@ -1353,11 +1378,11 @@
     }
 
     /**
-     * Answers a <code>file</code> URI for this File. The URI is System
-     * dependent and may not be transferable between different operating/file
+     * Returns a Uniform Resource Identifier for this file. The URI is system
+     * dependent and may not be transferable between different operating / file
      * systems.
      * 
-     * @return a <code>file</code> URI for this File.
+     * @return an URI for this file.
      */
     @SuppressWarnings("nls")
     public URI toURI() {
@@ -1379,14 +1404,13 @@
     }
 
     /**
-     * Answers a <code>file</code> URL for this File. The URL is System
-     * dependent and may not be transferable between different operating/file
+     * Returns a Uniform Resource Locator for this file. The URL is system
+     * dependent and may not be transferable between different operating / file
      * systems.
      * 
-     * @return a <code>file</code> URL for this File.
-     * 
+     * @return an URL for this file.
      * @throws java.net.MalformedURLException
-     *             if the path cannot be transformed into an URL
+     *             if the path cannot be transformed into an URL.
      */
     @SuppressWarnings("nls")
     public URL toURL() throws java.net.MalformedURLException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java Fri May  1 08:08:59 2009
@@ -18,14 +18,16 @@
 package java.io;
 
 /**
- * FileDescriptor is the lowest level representation of a File, Device, or
- * Socket. You can create any of the IO classes which take a FileDescriptor as
- * an argument by querying an open Socket or File for the FileDescriptor.
+ * The lowest-level representation of a file, device, or
+ * socket. If is often used for wrapping an operating system "handle". Some
+ * I/O classes can be queried for the FileDescriptor they are operating on, and
+ * this descriptor can subsequently be used during the instantiation of another
+ * I/O class, so that the new object will reuse it.
  * <p>
- * The FileDescriptor class also contains static fields representing Standard
- * Input, Output and Error. You can use these directly if desired but it is
- * recommended you go through System.in, System.out, and System.err streams
- * respectively.
+ * The FileDescriptor class also contains static fields representing the
+ * system's standard input, output and error streams. These can be used directly
+ * if desired, but it is recommended to go through System.in, System.out, and
+ * System.err streams respectively.
  * <p>
  * Applications should not create new FileDescriptors.
  * 
@@ -35,13 +37,19 @@
  */
 public final class FileDescriptor {
 
-    /** FileDescriptor representing Standard In */
+    /**
+     * The FileDescriptor representing standard input.
+     */
     public static final FileDescriptor in = new FileDescriptor();
 
-    /** FileDescriptor representing Standard Out */
+    /**
+     * FileDescriptor representing standard out.
+     */
     public static final FileDescriptor out = new FileDescriptor();
 
-    /** FileDescriptor representing Standard Error */
+    /**
+     * FileDescriptor representing standard error.
+     */
     public static final FileDescriptor err = new FileDescriptor();
 
     /**
@@ -63,9 +71,8 @@
     }
 
     /**
-     * Constructs a new FileDescriptor containing an invalid handle. This
-     * constructor does nothing interesting. Provided for signature
-     * compatibility.
+     * Constructs a new FileDescriptor containing an invalid handle. The
+     * contained handle is usually modified by native code at a later point.
      */
     public FileDescriptor() {
         super();
@@ -76,7 +83,7 @@
      * is written out to the appropriate device before returning.
      * 
      * @throws SyncFailedException
-     *             when the operation fails
+     *             when the operation fails.
      */
     public void sync() throws SyncFailedException {
         // if the descriptor is a read-only one, do nothing
@@ -88,10 +95,10 @@
     private native void syncImpl() throws SyncFailedException;
 
     /**
-     * Answers a boolean indicating whether or not this FileDescriptor is valid.
+     * Indicates whether this FileDescriptor is valid.
      * 
-     * @return <code>true</code> if this FileDescriptor is valid,
-     *         <code>false</code> otherwise
+     * @return {@code true} if this FileDescriptor is valid, {@code false}
+     *         otherwise.
      */
     public boolean valid() {
         return descriptor != -1;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java Fri May  1 08:08:59 2009
@@ -18,18 +18,20 @@
 package java.io;
 
 /**
- * FileFilter is an interface for filtering abstract Files
+ * An interface for filtering {@link File} objects based on their names
+ * or other information.
+ *
+ * @see File#listFiles(FileFilter)
  */
 public abstract interface FileFilter {
 
     /**
-     * Answers a boolean indicating whether or not a specific File should be
-     * included in a pathname list.
+     * Indicating whether a specific file should be included in a pathname list.
      * 
      * @param pathname
-     *            the abstract File to check.
-     * @return <code>true</code> if the File should be includes,
-     *         <code>false</code> otherwise.
+     *            the abstract file to check.
+     * @return {@code true} if the file should be included, {@code false}
+     *         otherwise.
      */
     public abstract boolean accept(File pathname);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java Fri May  1 08:08:59 2009
@@ -25,15 +25,19 @@
 import org.apache.harmony.nio.FileChannelFactory;
 
 /**
- * FileInputStream is a class for reading bytes from a file. This class may also
- * be used with other InputStreams, ie: BufferedInputStream, to read data from a
- * file with buffering.
+ * A specialized {@link InputStream} that reads from a file in the file system.
+ * All read requests made by calling methods in this class are directly
+ * forwarded to the equivalent function of the underlying operating system.
+ * Since this may induce some performance penalty, in particular if many small
+ * read requests are made, a FileInputStream is often wrapped by a
+ * BufferedInputStream.
  * 
+ * @see BufferedInputStream
  * @see FileOutputStream
  */
 public class FileInputStream extends InputStream implements Closeable {
     /**
-     * The FileDescriptor representing this FileInputStream.
+     * The {@link FileDescriptor} representing this {@code FileInputStream}.
      */
     FileDescriptor fd;
 
@@ -51,18 +55,15 @@
     private Object repositioningLock = new RepositioningLock();
 
     /**
-     * Constructs a new FileInputStream on the File <code>file</code>. If the
-     * file does not exist, the <code>FileNotFoundException</code> is thrown.
+     * Constructs a new {@code FileInputStream} based on {@code file}.
      * 
      * @param file
-     *            the File on which to stream reads.
-     * 
+     *            the file from which this stream reads.
      * @throws FileNotFoundException
-     *             If the <code>file</code> is not found.
-     * 
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
-     * @see java.lang.SecurityManager#checkRead(String)
-     * @see java.lang.SecurityManager#checkRead(String, Object)
+     *             if {@code file} does not exist.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             read request.
      */
     public FileInputStream(File file) throws FileNotFoundException {
         super();
@@ -81,16 +82,17 @@
     }
 
     /**
-     * Constructs a new FileInputStream on the FileDescriptor <code>fd</code>.
-     * The file must already be open, therefore no
-     * <code>FileNotFoundException</code> will be thrown.
+     * Constructs a new {@code FileInputStream} on the {@link FileDescriptor}
+     * {@code fd}. The file must already be open, therefore no
+     * {@code FileNotFoundException} will be thrown.
      * 
      * @param fd
-     *            the FileDescriptor on which to stream reads.
-     * 
-     * @see java.lang.SecurityManager#checkRead(FileDescriptor)
-     * @see java.lang.SecurityManager#checkRead(String)
-     * @see java.lang.SecurityManager#checkRead(String, Object)
+     *            the FileDescriptor from which this stream reads.
+     * @throws NullPointerException
+     *             if {@code fd} is {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             read request.
      */
     public FileInputStream(FileDescriptor fd) {
         super();
@@ -108,30 +110,30 @@
     }
 
     /**
-     * Constructs a new FileInputStream on the file named <code>fileName</code>.
-     * If the file does not exist, the <code>FileNotFoundException</code> is
-     * thrown. The <code>fileName</code> may be absolute or relative to the
-     * System property <code>"user.dir"</code>.
+     * Constructs a new {@code FileInputStream} on the file named
+     * {@code fileName}. The path of {@code fileName} may be absolute or
+     * relative to the system property {@code "user.dir"}.
      * 
      * @param fileName
-     *            the file on which to stream reads.
-     * 
+     *            the path and name of the file from which this stream reads.
      * @throws FileNotFoundException
-     *             If the <code>fileName</code> is not found.
+     *             if there is no file named {@code fileName}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             read request.
      */
     public FileInputStream(String fileName) throws FileNotFoundException {
         this(null == fileName ? (File) null : new File(fileName));
     }
 
     /**
-     * Answers a int representing then number of bytes that are available before
-     * this InputStream will block. This method always returns the size of the
-     * file minus the current position.
+     * Returns the number of bytes that are available before this stream will
+     * block. This method always returns the size of the file minus the current
+     * position.
      * 
      * @return the number of bytes available before blocking.
-     * 
      * @throws IOException
-     *             If an error occurs in this stream.
+     *             if an error occurs in this stream.
      */
     @Override
     public int available() throws IOException {
@@ -153,10 +155,10 @@
     }
 
     /**
-     * Close the FileInputStream.
+     * Closes this stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this FileInputStream.
+     *             if an error occurs attempting to close this stream.
      */
     @Override
     public void close() throws IOException {
@@ -181,12 +183,11 @@
     }
 
     /**
-     * This method ensures that all resources for this file are released when it
-     * is about to be garbage collected.
+     * Ensures that all resources for this stream are released when it is about
+     * to be garbage collected.
      * 
      * @throws IOException
-     *             If an error occurs attempting to finalize this
-     *             FileInputStream.
+     *             if an error occurs attempting to finalize this stream.
      */
     @Override
     protected void finalize() throws IOException {
@@ -194,44 +195,40 @@
     }
 
     /**
-     * Answers the FileChannel equivalent to this input stream.
+     * Returns the {@link FileChannel} equivalent to this input stream.
      * <p>
      * The file channel is read-only and has an initial position within the file
-     * that is the same as the current position of the FileInputStream within
-     * the file. All changes made to the underlying file descriptor state via
-     * the channel are visible by the input stream and vice versa.
-     * </p>
-     * 
-     * @return the file channel representation for this FileInputStream.
+     * that is the same as the current position of this stream within the file.
+     * All changes made to the underlying file descriptor state via the channel
+     * are visible by the input stream and vice versa.
+     *
+     * @return the file channel for this stream.
      */
     public FileChannel getChannel() {
         return channel;
     }
 
     /**
-     * Answers the FileDescriptor representing the operating system resource for
-     * this FileInputStream.
-     * 
-     * @return the FileDescriptor for this FileInputStream.
+     * Returns the {@link FileDescriptor} representing the operating system
+     * resource for this stream.
      * 
+     * @return the {@code FileDescriptor} for this stream.
      * @throws IOException
-     *             If an error occurs attempting to get the FileDescriptor of
-     *             this FileInputStream.
+     *             if an error occurs while getting this stream's
+     *             {@code FileDescriptor}.
      */
     public final FileDescriptor getFD() throws IOException {
         return fd;
     }
 
     /**
-     * Reads a single byte from this FileInputStream and returns the result as
-     * an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered.
-     * 
-     * @return the byte read or -1 if end of stream.
+     * Reads a single byte from this stream and returns it as an integer in the
+     * range from 0 to 255. Returns -1 if the end of this stream has been
+     * reached.
      * 
+     * @return the byte read or -1 if the end of this stream has been reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     @Override
     public int read() throws IOException {
@@ -241,17 +238,15 @@
     }
 
     /**
-     * Reads bytes from the FileInputStream and stores them in byte array
-     * <code>buffer</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered.
+     * Reads bytes from this stream and stores them in the byte array
+     * {@code buffer}.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     *            the byte array in which to store the bytes read.
+     * @return the number of bytes actually read or -1 if the end of the stream
+     *         has been reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     @Override
     public int read(byte[] buffer) throws IOException {
@@ -259,22 +254,24 @@
     }
 
     /**
-     * Reads at most <code>count</code> bytes from the FileInputStream and
-     * stores them in byte array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered.
+     * Reads at most {@code count} bytes from this stream and stores them in the
+     * byte array {@code buffer} starting at {@code offset}.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the byte array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code buffer} to store the bytes read
+     *            from this stream.
      * @param count
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes actually read or -1 if the end of the stream
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is greater than the size of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if the stream is closed or another IOException occurs.
      */
     @Override
     public int read(byte[] buffer, int offset, int count) throws IOException {
@@ -295,18 +292,16 @@
     }
 
     /**
-     * Skips <code>count</code> number of bytes in this FileInputStream.
-     * Subsequent <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used. This method may perform multiple reads to
-     * read <code>count</code> bytes.
+     * Skips {@code count} number of bytes in this stream. Subsequent
+     * {@code read()}'s will not return these bytes unless {@code reset()} is
+     * used. This method may perform multiple reads to read {@code count} bytes.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if {@code count < 0}, this stream is closed or another
+     *             IOException occurs.
      */
     @Override
     public long skip(long count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java Fri May  1 08:08:59 2009
@@ -18,26 +18,26 @@
 package java.io;
 
 /**
- * This IO exception is thrown when a file specified by a program cannot be
- * found.
+ * Thrown when a file specified by a program cannot be found.
  */
 public class FileNotFoundException extends IOException {
 
     private static final long serialVersionUID = -897856973823710492L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code FileNotFoundException} with its stack trace
+     * filled in.
      */
     public FileNotFoundException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code FileNotFoundException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public FileNotFoundException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java Fri May  1 08:08:59 2009
@@ -25,15 +25,14 @@
 import org.apache.harmony.nio.FileChannelFactory;
 
 /**
- * FileOutputStream is a class whose underlying stream is represented by a file
- * in the operating system. The bytes that are written to this stream are passed
- * directly to the underlying operating system equivalent function. Since
- * overhead may be high in writing to the OS, FileOutputStreams are usually
- * wrapped with a BufferedOutputStream to reduce the number of times the OS is
- * called.
- * <p>
- * <code>BufferedOutputStream buf = new BufferedOutputStream(new FileOutputStream("aFile.txt"));</code>
+ * A specialized {@link OutputStream} that writes to a file in the file system.
+ * All write requests made by calling methods in this class are directly
+ * forwarded to the equivalent function of the underlying operating system.
+ * Since this may induce some performance penalty, in particular if many small
+ * write requests are made, a FileOutputStream is often wrapped by a
+ * BufferedOutputStream.
  * 
+ * @see BufferedOutputStream
  * @see FileInputStream
  */
 public class FileOutputStream extends OutputStream implements Closeable {
@@ -52,16 +51,16 @@
     private IFileSystem fileSystem = Platform.getFileSystem();
 
     /**
-     * Constructs a new FileOutputStream on the File <code>file</code>. If
-     * the file exists, it is written over. See the constructor which can append
-     * to the file if so desired.
+     * Constructs a new FileOutputStream on the File {@code file}. If the file
+     * exists, it is overwritten.
      * 
      * @param file
-     *            the File on which to stream reads.
-     * 
+     *            the file to which this stream writes.
      * @throws FileNotFoundException
-     *             If the <code>file</code> cannot be opened for writing.
-     * 
+     *             if {@code file} cannot be opened for writing.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
      */
     public FileOutputStream(File file) throws FileNotFoundException {
@@ -69,20 +68,19 @@
     }
 
     /**
-     * Constructs a new FileOutputStream on the File <code>file</code>. If
-     * the file exists, it is written over. The parameter <code>append</code>
-     * determines whether or not the file is opened and appended to or just
-     * opened empty.
+     * Constructs a new FileOutputStream on the File {@code file}. The
+     * parameter {@code append} determines whether or not the file is opened and
+     * appended to or just opened and overwritten.
      * 
      * @param file
-     *            the File on which to stream reads.
+     *            the file to which this stream writes.
      * @param append
-     *            a boolean indicating whether or not to append to an existing
-     *            file.
-     * 
+     *            indicates whether or not to append to an existing file.
      * @throws FileNotFoundException
-     *             If the <code>file</code> cannot be opened for writing.
-     * 
+     *             if the {@code file} cannot be opened for writing.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
      * @see java.lang.SecurityManager#checkWrite(String)
      */
@@ -102,13 +100,17 @@
     }
 
     /**
-     * Constructs a new FileOutputStream on the FileDescriptor <code>fd</code>.
-     * The file must already be open, therefore no <code>FileIOException</code>
+     * Constructs a new FileOutputStream on the FileDescriptor {@code fd}. The
+     * file must already be open, therefore no {@code FileNotFoundException}
      * will be thrown.
      * 
      * @param fd
-     *            the FileDescriptor on which to stream writes.
-     * 
+     *            the FileDescriptor to which this stream writes.
+     * @throws NullPointerException
+     *             if {@code fd} is {@code null}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
      */
     public FileOutputStream(FileDescriptor fd) {
@@ -127,36 +129,37 @@
     }
 
     /**
-     * Constructs a new FileOutputStream on the file named <code>fileName</code>.
-     * If the file exists, it is written over. See the constructor which can
-     * append to the file if so desired. The <code>fileName</code> may be
-     * absolute or relative to the System property <code>"user.dir"</code>.
+     * Constructs a new FileOutputStream on the file named {@code filename}. If
+     * the file exists, it is overwritten. The {@code filename} may be absolute
+     * or relative to the system property {@code "user.dir"}.
      * 
      * @param filename
-     *            the file on which to stream writes.
-     * 
+     *            the name of the file to which this stream writes.
      * @throws FileNotFoundException
-     *             If the <code>filename</code> cannot be opened for writing.
+     *             if the file cannot be opened for writing.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      */
     public FileOutputStream(String filename) throws FileNotFoundException {
         this(filename, false);
     }
 
     /**
-     * Constructs a new FileOutputStream on the file named <code>filename</code>.
-     * If the file exists, it is written over. The parameter <code>append</code>
-     * determines whether or not the file is opened and appended to or just
-     * opened empty. The <code>filename</code> may be absolute or relative to
-     * the System property <code>"user.dir"</code>.
+     * Constructs a new FileOutputStream on the file named {@code filename}.
+     * The parameter {@code append} determines whether or not the file is opened
+     * and appended to or just opened and overwritten. The {@code filename} may
+     * be absolute or relative to the system property {@code "user.dir"}.
      * 
      * @param filename
-     *            the file on which to stream writes.
+     *            the name of the file to which this stream writes.
      * @param append
-     *            a boolean indicating whether or not to append to an existing
-     *            file.
-     * 
+     *            indicates whether or not to append to an existing file.
      * @throws FileNotFoundException
-     *             If the <code>filename</code> cannot be opened for writing.
+     *             if the file cannot be opened for writing.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies the
+     *             write request.
      */
     public FileOutputStream(String filename, boolean append)
             throws FileNotFoundException {
@@ -164,11 +167,11 @@
     }
 
     /**
-     * Close the FileOutputStream. This implementation closes the underlying OS
-     * resources allocated to represent this stream.
+     * Closes this stream. This implementation closes the underlying operating
+     * system resources allocated to represent this stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this FileOutputStream.
+     *             if an error occurs attempting to close this stream.
      */
     @Override
     public void close() throws IOException {
@@ -195,13 +198,11 @@
     }
 
     /**
-     * Frees any resources allocated to represent this FileOutputStream before
-     * it is garbage collected. This method is called from the Java Virtual
-     * Machine.
+     * Frees any resources allocated for this stream before it is garbage
+     * collected. This method is called from the Java Virtual Machine.
      * 
      * @throws IOException
-     *             If an error occurs attempting to finalize this
-     *             FileOutputStream.
+     *             if an error occurs attempting to finalize this stream.
      */
     @Override
     protected void finalize() throws IOException {
@@ -209,44 +210,41 @@
     }
 
     /**
-     * Answers the FileChannel equivalent to this output stream.
+     * Returns the FileChannel equivalent to this output stream.
      * <p>
      * The file channel is write-only and has an initial position within the
-     * file that is the same as the current position of this FileOutputStream
-     * within the file. All changes made to the underlying file descriptor state
-     * via the channel are visible by the output stream and vice versa.
-     * </p>
-     * 
-     * @return the file channel representation for this FileOutputStream.
+     * file that is the same as the current position of this stream within the
+     * file. All changes made to the underlying file descriptor state via the
+     * channel are visible by the output stream and vice versa.
+     *
+     * @return the file channel representation for this stream.
      */
     public FileChannel getChannel() {
         return channel;
     }
 
     /**
-     * Answers a FileDescriptor which represents the lowest level representation
-     * of a OS stream resource.
-     * 
-     * @return a FileDescriptor representing this FileOutputStream.
+     * Returns a FileDescriptor which represents the lowest level representation
+     * of an operating system stream resource.
      * 
+     * @return a FileDescriptor representing this stream.
      * @throws IOException
-     *             If the Stream is already closed and there is no
-     *             FileDescriptor.
+     *             if an error occurs attempting to get the FileDescriptor of
+     *             this stream.
      */
     public final FileDescriptor getFD() throws IOException {
         return fd;
     }
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this FileOutputStream.
+     * Writes the entire contents of the byte array {@code buffer} to this
+     * stream.
      * 
      * @param buffer
-     *            the buffer to be written
-     * 
+     *            the buffer to be written to the file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             FileOutputStream.
+     *             if this stream is closed or an error occurs attempting to
+     *             write to this stream.
      */
     @Override
     public void write(byte[] buffer) throws IOException {
@@ -254,24 +252,24 @@
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at <code>offset</code> to this
-     * FileOutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * {@code offset} to this stream.
      * 
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to write to this stream.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the index of the first byte in {@code buffer} to write.
      * @param count
-     *            number of bytes in buffer to write
-     * 
-     * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             FileOutputStream.
+     *            the number of bytes from {@code buffer} to write.
      * @throws IndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if {@code count < 0} or {@code offset < 0}, or if
+     *             {@code count + offset} is greater than the length of
+     *             {@code buffer}.
+     * @throws IOException
+     *             if this stream is closed or an error occurs attempting to
+     *             write to this stream.
      * @throws NullPointerException
-     *             If buffer is <code>null</code>.
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public void write(byte[] buffer, int offset, int count) throws IOException {
@@ -292,16 +290,14 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this
-     * FileOutputStream. Only the low order byte of <code>oneByte</code> is
-     * written.
+     * Writes the specified byte {@code oneByte} to this stream. Only the low
+     * order byte of the integer {@code oneByte} is written.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             FileOutputStream.
+     *             if this stream is closed an error occurs attempting to write
+     *             to this stream.
      */
     @Override
     public void write(int oneByte) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java Fri May  1 08:08:59 2009
@@ -25,16 +25,26 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * The class FilePermission is responsible for granting access to files or
- * directories. The FilePermission is made up of a pathname and a set of actions
- * which are valid for the pathname.
- * <P>
- * The <code>File.separatorChar</code> must be used in all pathnames when
+ * A permission for accessing a file or directory. The FilePermission is made up
+ * of a pathname and a set of actions which are valid for the pathname.
+ * <p>
+ * The {@code File.separatorChar} must be used in all pathnames when
  * constructing a FilePermission. The following descriptions will assume the
- * char is </code>/</code>. A pathname which ends in "/*", implies all the
- * files and directories contained in that directory. If the pathname ends in
- * "/-", it indicates all the files and directories in that directory
- * <b>recursively</b>.
+ * char is {@code /}. A pathname that ends in {@code /*} includes all the files
+ * and directories contained in that directory. If the pathname
+ * ends in {@code /-}, it includes all the files and directories in that
+ * directory <i>recursively</i>. The following pathnames have a special meaning:
+ * <ul>
+ *   <li>
+ *     "*": all files in the current directory;
+ *   </li>
+ *   <li>
+ *     "-": recursively all files and directories in the current directory;
+ *   </li>
+ *   <li>
+ *     "&lt;&lt;ALL FILES&gt;&gt;": any file and directory in the file system.
+ *   </li>
+ * </ul>
  */
 public final class FilePermission extends Permission implements Serializable {
     
@@ -65,10 +75,16 @@
      * Constructs a new FilePermission with the path and actions specified.
      * 
      * @param path
-     *            the path to apply the actions to.
+     *            the pathname of the file or directory to apply the actions to.
      * @param actions
-     *            the actions for the <code>path<code>. May be any
-     *							combination of read, write, execute, or delete.
+     *            the actions for the {@code path}. May be any combination of
+     *            "read", "write", "execute" and "delete".
+     * @throws IllegalArgumentException
+     *             if {@code actions} is {@code null} or an empty string, or if
+     *             it contains a string other than "read", "write", "execute"
+     *             and "delete".
+     * @throws NullPointerException
+     *             if {@code path} is null.
      */
     public FilePermission(String path, String actions) {
         super(path);
@@ -107,7 +123,7 @@
     }
 
     /**
-     * Answer the string representing this permissions actions. It must be of
+     * Returns the string representing this permission's actions. It must be of
      * the form "read,write,execute,delete", all lower case and in the correct
      * order if there is more than one action.
      * 
@@ -144,7 +160,7 @@
     }
 
     /**
-     * Answers the numerical representation of the argument.
+     * Returns the numerical representation of the argument.
      * 
      * @param actionNames
      *            the action names
@@ -174,9 +190,9 @@
     }
 
     /**
-     * Answers the actions associated with the receiver.
+     * Returns the actions associated with this file permission.
      * 
-     * @return the actions associated with the receiver.
+     * @return the actions associated with this file permission.
      */
     @Override
     public String getActions() {
@@ -184,14 +200,14 @@
     }
 
     /**
-     * Check to see if this permission is equal to another. The two are equal if
-     * <code>obj</code> is a FilePermission, they have the same path, and they
+     * Indicates if this file permission is equal to another. The two are equal
+     * if {@code obj} is a FilePermission, they have the same path, and they
      * have the same actions.
      * 
      * @param obj
      *            the object to check equality with.
-     * @return <code>true</code> if the two are equal, <code>false</code>
-     *         otherwise.
+     * @return {@code true} if this file permission is equal to {@code obj},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object obj) {
@@ -213,12 +229,16 @@
     }
 
     /**
-     * Indicates whether the argument permission is implied by the receiver.
+     * Indicates whether the permission {@code p} is implied by this file
+     * permission. This is the case if {@code p} is an instance of
+     * {@code FilePermission}, if {@code p}'s actions are a subset of this
+     * file permission's actions and if {@code p}'s path is implied by this
+     * file permission's path.
      * 
      * @param p
-     *            java.security.Permission the permission to check.
-     * @return <code>true</code> if the argument permission is implied by the
-     *         receiver, and <code>false</code> if it is not.
+     *            the permission to check.
+     * @return {@code true} if the argument permission is implied by the
+     *         receiver, and {@code false} if it is not.
      */
     @Override
     public boolean implies(Permission p) {
@@ -227,7 +247,7 @@
     }
 
     /**
-     * Answers an int describing what masks are implied by a specific
+     * Returns an int describing what masks are implied by a specific
      * permission.
      * 
      * @param p
@@ -329,11 +349,11 @@
     }
 
     /**
-     * Answers a new PermissionCollection in which to place FilePermission
-     * Objects.
+     * Returns a new PermissionCollection in which to place FilePermission
+     * objects.
      * 
-     * @return A new PermissionCollection suitable for storing FilePermission
-     *         objects.
+     * @return A new PermissionCollection object suitable for storing
+     *         FilePermission objects.
      */
     @Override
     public PermissionCollection newPermissionCollection() {
@@ -341,9 +361,9 @@
     }
 
     /**
-     * Answers an int representing the hash code value for this FilePermission.
+     * Calculates the hash code value for this file permission.
      * 
-     * @return int the hash code value for this FilePermission.
+     * @return the hash code value for this file permission.
      */
     @Override
     public int hashCode() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java Fri May  1 08:08:59 2009
@@ -23,9 +23,8 @@
 import java.util.Vector;
 
 /**
- * FilePermissionCollection is a class which holds a collection of
- * FilePermission objects and can answer a boolean indicating whether or not a
- * specific permissions is implied by a FilePermissionCollection.
+ * Collects {@link FilePermission} objects and allows to query whether a
+ * particular permission is implied by it.
  */
 final class FilePermissionCollection extends PermissionCollection implements
         Serializable {
@@ -35,15 +34,22 @@
     Vector<Permission> permissions = new Vector<Permission>();
 
     /**
-     * Construct a new FilePermissionCollection.
+     * Construct a new FilePermissionCollection
      */
     public FilePermissionCollection() {
         super();
     }
 
     /**
-     * Add a permission Object to the permission collection.
+     * Add a permission object to the permission collection.
      * 
+     * @param permission
+     *            the FilePermission object to add to the collection.
+     * @throws IllegalArgumentException
+     *             if {@code permission} is not an instance of
+     *             {@code FilePermission}.
+     * @throws IllegalStateException
+     *             if this collection is read-only.
      * @see java.security.PermissionCollection#add(java.security.Permission)
      */
     @Override
@@ -59,8 +65,9 @@
     }
 
     /**
-     * Answers an enumeration for the collection of permissions.
+     * Returns an enumeration for the collection of permissions.
      * 
+     * @return a permission enumeration for this permission collection.
      * @see java.security.PermissionCollection#elements()
      */
     @Override
@@ -69,9 +76,11 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this permissions collection
-     * implies a specific <code>permission</code>.
+     * Indicates whether this permissions collection implies a specific
+     * {@code permission}.
      * 
+     * @param permission
+     *            the permission to check.
      * @see java.security.PermissionCollection#implies(java.security.Permission)
      */
     @Override

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java Fri May  1 08:08:59 2009
@@ -18,34 +18,34 @@
 package java.io;
 
 /**
- * FileReader is class for turning a file into a character Stream. Data read
- * from the source is converted into characters. The encoding is assumed to
- * 8859_1. The FileReader contains a buffer of bytes read from the source and
- * converts these into characters as needed. The buffer size is 8K.
+ * A specialized {@link Reader} that reads from a file in the file system.
+ * All read requests made by calling methods in this class are directly
+ * forwarded to the equivalent function of the underlying operating system.
+ * Since this may induce some performance penalty, in particular if many small
+ * read requests are made, a FileReader is often wrapped by a
+ * BufferedReader.
  * 
+ * @see BufferedReader
  * @see FileWriter
  */
 public class FileReader extends InputStreamReader {
 
     /**
-     * Construct a new FileReader on the given File <code>file</code>. If the
-     * <code>file</code> specified cannot be found, throw a
-     * FileNotFoundException.
+     * Constructs a new FileReader on the given {@code file}.
      * 
      * @param file
      *            a File to be opened for reading characters from.
-     * 
      * @throws FileNotFoundException
-     *             if the file cannot be opened for reading.
+     *             if {@code file} does not exist.
      */
     public FileReader(File file) throws FileNotFoundException {
         super(new FileInputStream(file));
     }
 
     /**
-     * Construct a new FileReader on the given FileDescriptor <code>fd</code>.
-     * Since a previously opened FileDescriptor is passed as an argument, no
-     * FileNotFoundException is thrown.
+     * Construct a new FileReader on the given FileDescriptor {@code fd}. Since
+     * a previously opened FileDescriptor is passed as an argument, no
+     * FileNotFoundException can be thrown.
      * 
      * @param fd
      *            the previously opened file descriptor.
@@ -55,15 +55,12 @@
     }
 
     /**
-     * Construct a new FileReader on the given file named <code>filename</code>.
-     * If the <code>filename</code> specified cannot be found, throw a
-     * FileNotFoundException.
+     * Construct a new FileReader on the given file named {@code filename}.
      * 
      * @param filename
      *            an absolute or relative path specifying the file to open.
-     * 
      * @throws FileNotFoundException
-     *             if the filename cannot be opened for reading.
+     *             if there is no file named {@code filename}.
      */
     public FileReader(String filename) throws FileNotFoundException {
         super(new FileInputStream(filename));



Mime
View raw message