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

[Brian Burkhalter-3]

Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.

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

Commit messages:
 - 6245663: (spec) File.renameTo(File) changes the file-system object, not the File instance

Changes: https://git.openjdk.java.net/jdk/pull/2618/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-6245663
  Stats: 4 lines in 1 file changed: 3 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2618.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2618/head:pull/2618

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.

Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:

  6245663: Mention 'dest' parameter in the added doc

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/2618/files
  - new: https://git.openjdk.java.net/jdk/pull/2618/files/a8e2cb1e..43e46a38

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=00-01

  Stats: 2 lines in 1 file changed: 1 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2618.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2618/head:pull/2618

PR: https://git.openjdk.java.net/jdk/pull/2618

[Roger Riggs-2]

On Wed, 17 Feb 2021 22:08:47 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Mention 'dest' parameter in the added doc

src/java.base/share/classes/java/io/File.java line 1383:

> 1381:      * object does not itself change although the filesystem object it denoted
> 1382:      * might have moved.
> 1383:      *

Is there a way to mix in a mention of the {@ code "dest"} argument.
"might have moved to the abstract pathname provided in the dest argument".

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

On Wed, 17 Feb 2021 22:04:38 GMT, Roger Riggs <[hidden email]> wrote:

>> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>>
>>   6245663: Mention 'dest' parameter in the added doc
>
> src/java.base/share/classes/java/io/File.java line 1383:
>
>> 1381:      * object does not itself change although the filesystem object it denoted
>> 1382:      * might have moved.
>> 1383:      *
>
> Is there a way to mix in a mention of the {@ code "dest"} argument.
> "might have moved to the abstract pathname provided in the dest argument".

Good idea.

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Naoto Sato-2]

On Wed, 17 Feb 2021 22:12:06 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Mention 'dest' parameter in the added doc

src/java.base/share/classes/java/io/File.java line 1381:

> 1379:      * that the rename operation was successful.  As instances of {@code File}
> 1380:      * are immutable, the abstract pathname represented by this {@code File}
> 1381:      * object does not itself change although the filesystem object it denoted

I guess you meant `file` object here, instead of `filesystem`?

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

On Wed, 17 Feb 2021 22:24:53 GMT, Naoto Sato <[hidden email]> wrote:

>> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>>
>>   6245663: Mention 'dest' parameter in the added doc
>
> src/java.base/share/classes/java/io/File.java line 1381:
>
>> 1379:      * that the rename operation was successful.  As instances of {@code File}
>> 1380:      * are immutable, the abstract pathname represented by this {@code File}
>> 1381:      * object does not itself change although the filesystem object it denoted
>
> I guess you meant `file` object here, instead of `filesystem`?

No, I intended `filesystem` but in the sense of "object in the filesystem" but it does seem awkward.

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Roger Riggs-2]

On Wed, 17 Feb 2021 22:12:06 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Mention 'dest' parameter in the added doc

Marked as reviewed by rriggs (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.

Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:

  6245663: Update copyright year.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/2618/files
  - new: https://git.openjdk.java.net/jdk/pull/2618/files/43e46a38..e7ff82d2

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=01-02

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2618.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2618/head:pull/2618

PR: https://git.openjdk.java.net/jdk/pull/2618

[Naoto Sato-2]

On Wed, 17 Feb 2021 23:10:57 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Update copyright year.

Thanks. Looks good.

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

Marked as reviewed by naoto (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/2618

[Alan Bateman-2]

On Wed, 17 Feb 2021 22:28:11 GMT, Brian Burkhalter <[hidden email]> wrote:

>> src/java.base/share/classes/java/io/File.java line 1381:
>>
>>> 1379:      * that the rename operation was successful.  As instances of {@code File}
>>> 1380:      * are immutable, the abstract pathname represented by this {@code File}
>>> 1381:      * object does not itself change although the filesystem object it denoted
>>
>> I guess you meant `file` object here, instead of `filesystem`?
>
> No, I intended `filesystem` but in the sense of "object in the filesystem" but it does seem awkward.

It might be clearer if the end of the sentence were changed to something like "... this File object is not changed to name destination file or directory".

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

On Thu, 18 Feb 2021 09:24:06 GMT, Alan Bateman <[hidden email]> wrote:

>> No, I intended `filesystem` but in the sense of "object in the filesystem" but it does seem awkward.
>
> It might be clearer if the end of the sentence were changed to something like "... this File object is not changed to name destination file or directory".

Like so?
--- a/src/java.base/share/classes/java/io/File.java
+++ b/src/java.base/share/classes/java/io/File.java
@@ -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

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Alan Bateman-2]

On Thu, 18 Feb 2021 16:43:09 GMT, Brian Burkhalter <[hidden email]> wrote:

>> It might be clearer if the end of the sentence were changed to something like "... this File object is not changed to name destination file or directory".
>
> Like so?
> --- a/src/java.base/share/classes/java/io/File.java
> +++ b/src/java.base/share/classes/java/io/File.java
> @@ -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

yes, I think that works.

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.

Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:

  6245663: Simplify new verbiage

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/2618/files
  - new: https://git.openjdk.java.net/jdk/pull/2618/files/e7ff82d2..e6a23ab4

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=03
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=2618&range=02-03

  Stats: 4 lines in 1 file changed: 0 ins; 2 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2618.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2618/head:pull/2618

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

On Thu, 18 Feb 2021 16:59:54 GMT, Alan Bateman <[hidden email]> wrote:

>> Like so?
>> --- a/src/java.base/share/classes/java/io/File.java
>> +++ b/src/java.base/share/classes/java/io/File.java
>> @@ -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
>
> yes, I think that works.

[CSR](https://bugs.openjdk.java.net/browse/JDK-8261935) also so updated.

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Alan Bateman-2]

On Thu, 18 Feb 2021 17:34:04 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Simplify new verbiage

Marked as reviewed by alanb (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Roger Riggs-2]

On Thu, 18 Feb 2021 17:34:04 GMT, Brian Burkhalter <[hidden email]> wrote:

>> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>
>   6245663: Simplify new verbiage

Marked as reviewed by rriggs (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/2618

[Brian Burkhalter-3]

On Wed, 17 Feb 2021 21:48:16 GMT, Brian Burkhalter <[hidden email]> wrote:

> Please review this minor specification update to highlight that `File.renameTo(File)` does not modify the `File` instance on which the method is invoked.

This pull request has now been integrated.

Changeset: 851b2e31
Author:    Brian Burkhalter <[hidden email]>
URL:       https://git.openjdk.java.net/jdk/commit/851b2e31
Stats:     4 lines in 1 file changed: 2 ins; 0 del; 2 mod

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

Reviewed-by: rriggs, naoto, alanb

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

PR: https://git.openjdk.java.net/jdk/pull/2618