RFR: JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case [v4]

[Alan Bateman]

On Wed, 3 Feb 2021 11:54:00 GMT, Hamlin Li <mli at openjdk.org> wrote:

>> We'd better put more detailed messages in FileChannel.transferFrom/transferTo that it will not return -1, as we met several cases where developers of framework/program assume that it will return -1 on some error conditions, e.g. EOF of src Channel of transferFrom.
>> 
>> please check more details in JDK-8260486, and discussion in https://mail.openjdk.java.net/pipermail/nio-dev/2021-January/008094.html
>
> Hamlin Li has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case

src/java.base/share/classes/java/nio/channels/FileChannel.java line 646:

> 644:      * and has fewer than {@code count} bytes immediately available in its
> 645:      * input buffer. No bytes are transferred if the source channel has reached
> 646:      * the end-of-stream in which case zero will be returned.

Thanks for dropping the apiNote that mentions -1 and return value.

The update is mostly okay, I might re-word it slightly to "No bytes are transferred, and zero is returned, if the source has reached end-of-stream".

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

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