8029370: (fc) FileChannel javadoc not clear for cases where position == size

[bplb]

Modify the specifications of the java.nio.channels.FileChannel methods transferTo, read(ByteBuffer,long), and write(ByteBuffer,long) to state "greater than or equal to the file's current size" with respect to the given position instead of "greater than the file's current size."

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change requires CSR request JDK-8303141 to be approved

Issues

• JDK-8029370: (fc) FileChannel javadoc not clear for cases where position == size
• JDK-8303141: (fc) FileChannel javadoc not clear for cases where position == size (CSR)

Reviewers

• Lance Andersen (@LanceAndersen - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk pull/12735/head:pull/12735
$ git checkout pull/12735

Update a local copy of the PR:
$ git checkout pull/12735
$ git pull https://git.openjdk.org/jdk pull/12735/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 12735

View PR using the GUI difftool:
$ git pr show -t 12735

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/12735.diff

[bridgekeeper]

👋 Welcome back bpb! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@bplb The following label will be automatically applied to this pull request:

• nio

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 00: Full (19ff3857)

[bplb]

The modified doc lines in this PR are left unwrapped for reviewing clarity. They can be fixed before integration.

[LanceAndersen]

Hi Brian,

The change looks fine.

This probably should have a CSR to go with it (unless you have checked on that already)

[openjdk]

@bplb This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8029370: (fc) FileChannel javadoc not clear for cases where position == size

Reviewed-by: lancea

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 17 new commits pushed to the master branch:

• 2fb1e3b: 8302268: Prefer ArrayList to LinkedList in XEmbeddedFramePeer
• 3a9f491: 8301964: Expensive fillInStackTrace operation in HttpURLConnection.getLastModified when no last-modified in response
• 1dbd18a: 8302120: Prefer ArrayList to LinkedList in AggregatePainter
• 2e78d83: 8302899: Executors.newSingleThreadExecutor can use Cleaner to shutdown executor
• 17e3769: 8302871: Speed up StringLatin1.regionMatchesCI
• b4ea807: 8288912: vmTestbase/nsk/stress/strace/strace002.java fails with Unexpected method name: currentCarrierThread
• ccf3340: 8303083: (bf) Remove private DirectByteBuffer(long, int) constructor before JDK 21 GA
• 83d77b1: 8303072: Memory leak in exeNullCallerTest.cpp
• 7d8b8ba: 8303131: pandoc.exe mangles all processed html files
• 8f7c496: 8302810: NMT gtests don't correctly check for marked ranges
• ... and 7 more: https://git.openjdk.org/jdk/compare/4b6acad0bd7729c39e807cd35c40b0fe4a14783c...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[bplb]

Hi Brian,

The change looks fine.

Thanks, @LanceAndersen .

This probably should have a CSR to go with it (unless you have checked on that already)

I was on the fence about that. I will check on it.

[AlanBateman]

Yes, it should be "greater than or equal to the file's current size". I assume transferFrom needs the same change. The javadoc update technically introduces a new testable assertion so I think a CSR should be created.

[bplb]

Yes, it should be "greater than or equal to the file's current size". I assume transferFrom needs the same change. The javadoc update technically introduces a new testable assertion so I think a CSR should be created.

I thought I checked transferFrom but will look again. A CSR was indeed created.

[bplb]

I thought I checked transferFrom but will look again. A CSR was indeed created.

transferFrom does not need or equal to:

jshell> FileChannel fc = FileChannel.open(Path.of("junk"), StandardOpenOption.READ, StandardOpenOption.WRITE);
fc ==> sun.nio.ch.FileChannelImpl@528931cf

jshell> FileChannel fc2 = FileChannel.open(Path.of("junk"), StandardOpenOption.READ, StandardOpenOption.WRITE);
fc2 ==> sun.nio.ch.FileChannelImpl@1563da5

jshell> fc.size()
$5 ==> 83

jshell> fc.transferFrom(fc2, fc.size(), 8)
$6 ==> 8

jshell> fc.size()
$7 ==> 91

jshell> fc.transferFrom(fc2, fc.size() + 1, 8)
$8 ==> 0

jshell> fc.size()
$9 ==> 91

[AlanBateman]

transferFrom does not need or equal to:

You're right, I forgot thaht transferFrom goes not grow the file like write(src, position), something that might want to re-visited some time.

[bplb]

/integrate

[openjdk]

Going to push as commit 42330d2.
Since your change was applied there have been 31 commits pushed to the master branch:

• a253b46: 8301119: Support for GB18030-2022
• 55e6bb6: 8302685: Some javac unit tests aren't reliably closing open files
• f5a1276: 8262895: [macos_aarch64] runtime/CompressedOops/CompressedClassPointers.java fails with 'Narrow klass base: 0x0000000000000000' missing from stdout/stderr
• 2fe4e5f: 8303169: Remove Windows specific workaround from libdt
• f2b03f9: 8303051: Stop saving 5 chunks in each ChunkPool
• fbc036e: 8303135: JFR: Log periodic events using periodic tag
• dbb5581: 8081474: SwingWorker calls 'done' before the 'doInBackground' is finished
• 306134d: 8300792: Refactor examples in java.net.http to use @snippet
• a2c5a4a: 8302732: sun/net/www/http/HttpClient/MultiThreadTest.java still failing intermittently
• db217c9: 8292583: Comment for ciArrayKlass::make is wrong
• ... and 21 more: https://git.openjdk.org/jdk/compare/4b6acad0bd7729c39e807cd35c40b0fe4a14783c...master

Your commit was automatically rebased without conflicts.

[openjdk]

@bplb Pushed as commit 42330d2.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.