8339574: Behavior of File.is{Directory,File,Hidden} is not documented with respect to symlinks

Reviewed-by: djelinski, alanb

src/java.base/share/classes/java/io/File.java

@@ -79,6 +79,10 @@ import jdk.internal.util.StaticProperty;
  * {@code user.dir}, and is typically the directory in which the Java
  * virtual machine was invoked.
  *
+ * <p> Unless otherwise noted, {@linkplain java.nio.file##links symbolic links}
+ * are automatically redirected to the <i>target</i> of the link, whether they
+ * are provided by a pathname string or via a {@code File} object.
+ *
  * <p> The <em>parent</em> of an abstract pathname may be obtained by invoking
  * the {@link #getParent} method of this class and consists of the pathname's
  * prefix and each name in the pathname's name sequence except for the last.
@@ -904,8 +908,16 @@ public class File
      * Tests whether the file named by this abstract pathname is a hidden
      * file.  The exact definition of <em>hidden</em> is system-dependent.  On
      * UNIX systems, a file is considered to be hidden if its name begins with
-     * a period character ({@code '.'}).  On Microsoft Windows systems, a file is
+     * a period character ({@code '.'}).  On Microsoft Windows systems, a file
-     * considered to be hidden if it has been marked as such in the filesystem.
+     * is considered to be hidden if it has been marked as such in the
+     * filesystem.
+     *
+     *
+     * @implNote
+     * If the file is a symbolic link, then on UNIX system it is considered to
+     * be hidden if the name of the link itself, not that of its target, begins
+     * with a period character.  On Windows systems, a symbolic link is
+     * considered hidden if its target is so marked in the filesystem.
      *
      * @return  {@code true} if and only if the file denoted by this
      *          abstract pathname is hidden according to the conventions of the
@@ -1048,7 +1060,8 @@ public class File
     /**
      * Deletes the file or directory denoted by this abstract pathname.  If
      * this pathname denotes a directory, then the directory must be empty in
-     * order to be deleted.
+     * order to be deleted.  If this pathname denotes a symbolic link, then the
+     * link itself, not its target, will be deleted.
      *
      * <p> Note that the {@link java.nio.file.Files} class defines the {@link
      * java.nio.file.Files#delete(Path) delete} method to throw an {@link IOException}
@@ -1078,6 +1091,8 @@ public class File
     /**
      * Requests that the file or directory denoted by this abstract
      * pathname be deleted when the virtual machine terminates.
+     * If this pathname denotes a symbolic link, then the
+     * link itself, not its target, will be deleted.
      * Files (or directories) are deleted in the reverse order that
      * they are registered. Invoking this method to delete a file or
      * directory that is already registered for deletion has no effect.
@@ -1421,7 +1436,9 @@ public class File
     }
 
     /**
-     * Renames the file denoted by this abstract pathname.
+     * Renames the file denoted by this abstract pathname.  If this pathname
+     * denotes a symbolic link, then the link itself, not its target, will be
+     * renamed.
      *
      * <p> Many aspects of the behavior of this method are inherently
      * platform-dependent: The rename operation might not be able to move a

src/java.base/share/classes/java/io/FileInputStream.java

@@ -85,7 +85,9 @@ public class FileInputStream extends InputStream
      * Creates a {@code FileInputStream} by
      * opening a connection to an actual file,
      * the file named by the path name {@code name}
-     * in the file system.  A new {@code FileDescriptor}
+     * in the file system.  {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@code FileDescriptor}
      * object is created to represent this file
      * connection.
      * <p>
@@ -117,6 +119,8 @@ public class FileInputStream extends InputStream
      * opening a connection to an actual file,
      * the file named by the {@code File}
      * object {@code file} in the file system.
+     * {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
      * A new {@code FileDescriptor} object
      * is created to represent this file connection.
      * <p>

src/java.base/share/classes/java/io/FileOutputStream.java

@@ -97,7 +97,10 @@ public class FileOutputStream extends OutputStream
 
     /**
      * Creates a file output stream to write to the file with the
-     * specified name. A new {@code FileDescriptor} object is
+     * specified name. If the file exists, it is truncated, otherwise a
+     * new file is created. {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@code FileDescriptor} object is
      * created to represent this file connection.
      * <p>
      * First, if there is a security manager, its {@code checkWrite}
@@ -126,8 +129,11 @@ public class FileOutputStream extends OutputStream
 
     /**
      * Creates a file output stream to write to the file with the specified
-     * name.  If the second argument is {@code true}, then
+     * name. If the file exists, it is truncated unless the second
-     * bytes will be written to the end of the file rather than the beginning.
+     * argument is {@code true}, in which case bytes will be written to the
+     * end of the file rather than the beginning. If the file does not exist,
+     * it is created. {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
      * A new {@code FileDescriptor} object is created to represent this
      * file connection.
      * <p>
@@ -158,9 +164,12 @@ public class FileOutputStream extends OutputStream
 
     /**
      * Creates a file output stream to write to the file represented by
-     * the specified {@code File} object. A new
+     * the specified {@code File} object.
-     * {@code FileDescriptor} object is created to represent this
+     * If the file exists, it is truncated, otherwise a
-     * file connection.
+     * new file is created. {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@code FileDescriptor} object is
+     * created to represent this file connection.
      * <p>
      * First, if there is a security manager, its {@code checkWrite}
      * method is called with the path represented by the {@code file}
@@ -187,10 +196,14 @@ public class FileOutputStream extends OutputStream
 
     /**
      * Creates a file output stream to write to the file represented by
-     * the specified {@code File} object. If the second argument is
+     * the specified {@code File} object.
-     * {@code true}, then bytes will be written to the end of the file
+     * If the file exists, it is truncated unless the second
-     * rather than the beginning. A new {@code FileDescriptor} object is
+     * argument is {@code true}, in which case bytes will be written to the
-     * created to represent this file connection.
+     * end of the file rather than the beginning. If the file does not exist,
+     * it is created. {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@code FileDescriptor} object is created to represent this
+     * file connection.
      * <p>
      * First, if there is a security manager, its {@code checkWrite}
      * method is called with the path represented by the {@code file}

src/java.base/share/classes/java/io/RandomAccessFile.java

@@ -101,8 +101,12 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
 
     /**
      * Creates a random access file stream to read from, and optionally
-     * to write to, a file with the specified pathname. A new
+     * to write to, a file with the specified pathname. If the file exists
-     * {@link FileDescriptor} object is created to represent the
+     * it is opened; if it does not exist and write mode is specified, a
+     * new file is created.
+     * {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@link FileDescriptor} object is created to represent the
      * connection to the file.
      *
      * <p> The {@code mode} argument specifies the access mode with which the
@@ -146,9 +150,14 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
     }
 
     /**
-     * Creates a random access file stream to read from, and optionally to
+     * Creates a random access file stream to read from, and optionally
-     * write to, the file specified by the {@link File} argument.  A new {@link
+     * to write to, the file specified by the {@link File} argument. If
-     * FileDescriptor} object is created to represent this file connection.
+     * the file exists it is opened; if it does not exist and write mode
+     * is specified, a new file is created.
+     * {@linkplain java.nio.file##links Symbolic links}
+     * are automatically redirected to the <i>target</i> of the link.
+     * A new {@link FileDescriptor} object is created to represent the
+     * connection to the file.
      *
      * <p>The <a id="mode">{@code mode}</a> argument specifies the access mode
      * in which the file is to be opened.  The permitted values and their