RFR: 8366102: Clarification Needed: Symbolic Link Handling in File API Specifications

[Brian Burkhalter]

On Fri, 29 Aug 2025 15:57:47 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Attempt to improve the verbiage of the `java.io.File` specification to make it clearer whether a given method operates only on an abstract pathname or on the actual file system entry it denotes.
>
> src/java.base/share/classes/java/io/File.java line 85:
> 
>> 83:  * <p> Unless otherwise noted, {@linkplain java.nio.file##links symbolic links}
>> 84:  * are automatically redirected to the <i>target</i> of the link, whether they
>> 85:  * are provided by a pathname string or via a {@code File} object.  Methods
> 
> What would you think about stealing some of the text we have in the java.nio.file package description and leading with that text in this paragraph.  I'm thinking something like this:
> 
> "Many operating systems and file systems have support for *symbolic links*. A symbolic link is a special file that serves as a reference to another file. Unless otherwise specified, symbolic links are transparent to applications and operations on files that are symbolic links are automatically redirected to the *target* of the link.  Methods that only operate on the abstract pathname do not access the file system and thus do not resolve symbolic links."

Sounds reasonable.

> src/java.base/share/classes/java/io/File.java line 1949:
> 
>> 1947:      * @apiNote This method only compares the abstract pathnames;
>> 1948:      *          it does not access the file system and the file is not required
>> 1949:      *          to exist.
> 
> Rather than API note  hen it might be better to take the second part of the proposed note and add it to the first paragraph of the method description. Can you try that and see how it reads?

Probably the same then should be done for the API note of `equals`

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310570047
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310570232