RFR: 8369854: (ch) Refine specification of behavior of {Gathering,Writable}ByteChannel.write

[Alan Bateman]

On Wed, 15 Oct 2025 22:01:12 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

> Modify the specification of the `write` methods of `WritableByteChannel` and `GatheringByteChannel` in the `java.nio.channels` package to emphasize that each method invocation returns only the number of bytes written in that invocation and that `write` might have to be invoked more than once for all requested bytes to be written.

src/java.base/share/classes/java/nio/channels/GatheringByteChannel.java line 87:

> 85:      * method returns the number of bytes written by its current invocation,
> 86:      * hence it might be necessary to call the write method in a loop until all
> 87:      * <i>r</i> bytes are written.

The `@return` description also makes it clear that it returns the number of bytes written so I think we can drop "by its current invocation". 

I think it would be good if we could link to ByteBuffer::remaining or hasRemaining as this is the number of bytes that were not written.  Maybe "It may be invoke write more than once to ensure that all remaining bytes are written"?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27833#discussion_r2435514164