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

(spec) File.renameTo(File) changes the file-system object, not the File instance

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      This is a doc-only change so no behavioral change.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Append a sentence to the specification of File.renameTo(File dest) to highlight that the File instance on which the method is invoked is immutable and not modified to refer to the abstract pathname provided via dest.

      Problem

      Although stated in its class documentation that a File is immutable, if a developer overlooks this statement, they could easily assume that the pathname representation internal to a File is changed to the pathname to which the entity is renamed.

      Solution

      Append a sentence fo the File.renameTo(File) specification making it explicit that the File instance is not itself modified.

      Specification

      @@ -1376,7 +1376,9 @@ public class File
            * file from one filesystem to another, it might not be atomic, and it
            * might not succeed if a file with the destination abstract pathname
            * already exists.  The return value should always be checked to make sure
      -     * that the rename operation was successful.
      +     * that the rename operation was successful.  As instances of {@code File}
      +     * are immutable, this File object is not changed to name the destination
      +     * file or directory.
            *
            * <p> Note that the {@link java.nio.file.Files} class defines the {@link
            * java.nio.file.Files#move move} method to move or rename a file in a

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              bpb Brian Burkhalter
              Reporter:
              rmandalasunw Ranjith Mandala (Inactive)
              Reviewed By:
              Alan Bateman, Naoto Sato, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: