Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8267889

java.io.File.equals contains misleading Javadoc

    XMLWordPrintable

Details

    • CSR
    • Status: Closed
    • P4
    • Resolution: Approved
    • 17
    • core-libs
    • None
    • behavioral
    • minimal
    • Minimal compatibility risk as the specification is merely being clarified to match longstanding behavior.
    • Java API
    • SE

    Description

      Summary

      Clarify that equality of two Files is based only on a comparison of their abstract pathnames.

      Problem

      The specification of the method java.io.File.equals includes this statement:

      Returns true if and only if the argument is not null and is an abstract pathname that denotes the same file or directory as this abstract pathname.

      This might lead some to interpret the method as comparing two objects in the file system rather than only two abstract pathnames.

      Solution

      Modify the specification to clarify that only abstract pathnames are compared and there is no accessing of the file system.

      Specification

      --- a/src/java.base/share/classes/java/io/File.java
      +++ b/src/java.base/share/classes/java/io/File.java
      @@ -2196,8 +2196,8 @@ public class File
           /**
            * Compares two abstract pathnames lexicographically.  The ordering
            * defined by this method depends upon the underlying system.  On UNIX
      -     * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
      -     * systems it is not.
      +     * systems, alphabetic case is significant in comparing pathnames; on
      +     * Microsoft Windows systems it is not.
            *
            * @param   pathname  The abstract pathname to be compared to this abstract
            *                    pathname
      @@ -2217,16 +2217,23 @@ public class File
           /**
            * Tests this abstract pathname for equality with the given object.
            * Returns {@code true} if and only if the argument is not
      -     * {@code null} and is an abstract pathname that denotes the same file
      -     * or directory as this abstract pathname.  Whether or not two abstract
      -     * pathnames are equal depends upon the underlying system.  On UNIX
      -     * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
      -     * systems it is not.
      +     * {@code null} and is an abstract pathname that is the same as this
      +     * abstract pathname.  Whether or not two abstract
      +     * pathnames are equal depends upon the underlying operating system.
      +     * On UNIX systems, alphabetic case is significant in comparing pathnames;
      +     * on Microsoft Windows systems it is not.
      +     *
      +     * @apiNote This method only tests whether the abstract pathnames are equal;
      +     *          it does not access the file system and the file is not required
      +     *          to exist.
            *
            * @param   obj   The object to be compared with this abstract pathname
            *
            * @return  {@code true} if and only if the objects are the same;
            *          {@code false} otherwise
      +     *
      +     * @see #compareTo(File)
      +     * @see java.nio.file.Files#isSameFile(Path,Path)
            */
           public boolean equals(Object obj) {

      Attachments

        Issue Links

          Activity

            People

              bpb Brian Burkhalter
              webbuggrp Webbug Group
              Brent Christian, Daniel Fuchs, Lance Andersen
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: