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

java.io.File.equals contains misleading Javadoc

    XMLWordPrintable

    Details

    • Subcomponent:
    • Resolved In Build:
      b26
    • Verification:
      Verified

      Description

      ADDITIONAL SYSTEM INFORMATION :
      Any, OS independent code is responsible for the choice of lexical comparison.

      A DESCRIPTION OF THE PROBLEM :
      The javaDoc says:

      (...)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. (...)

      The correct sentence is:

      (...)Returns true if and only if the argument is not null and is an abstract pathname is the same as this abstract pathname. (...)

      Notice, I removed the "the same file" as a current implementation (I did inspect source since 1.7 up to
      https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/io/File.java ) is using lexical comparison and is not taking in an account ..\ and .\ up/current folder path elements.

      See also 4143695 and 4787260.

      I'm well aware that changing this behavior is very problematic (touching "cast in stone implementation" can break things), but clarifying a JavaDoc can be done without any harm to existing projects.

      I have no problem with the fact that paths are compared lexically instead of logically, since:

        a.getCanonicalFile().equals(b.getCanonicalFile()) is a doable work-around, IF one knows that is SHOULD be done. Current javadoc comment is missleading.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      Read document, check the source or use examples provided in 4787260

      Reader expects that regardless of how below file is specified:

      current working dir: d:\w\x\y
       d:\w\x\y\z.txt
       d:\w\x\y\x\a\c\..\..\..\z.tx
      .\z.txt
      z.txt

      is actually seen as the same file even tough paths are lexically very, very different, and File.equals() will return true across all those cases.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      Javadoc should describe what the File.equals() really do.

      Reader should expect that all paths in above example are different and File.equals() returns false.
      ACTUAL -
      Javadoc reader is confused. User thinks that it is a bug, but 4143695 was given "Won't fix" ages ago! Why this is STILL in javadoc?

      ---------- BEGIN SOURCE ----------
      see 4787260
      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      Inspect java.io.File.equals source code to figure out what is really done. Be afraid of it, becase if code does something else that specs are saying You never know if in future code will not be fixed to be compilant with the specs. Include unit tests in Your test suites to fire up the "yellow flag" if change in implementation is detected. Avoid using File.equals() whenever possible because an eventual fix may break Your code.

      FREQUENCY : always


        Attachments

          Issue Links

            Activity

              People

              Assignee:
              bpb Brian Burkhalter
              Reporter:
              webbuggrp Webbug Group
              Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: