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

[Alan Bateman]

On Tue, 2 Feb 2021 04:30:52 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 refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR.

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

> 592:      * This method only returns the number of bytes that were actually
> 593:      * transferred, it will not return -1.
> 594:      *

The transferTo method is file -> target channel and I think it would be confusing to mention -1 here.
We could add an apiNote to point out that the method returns zero if the given position is greater than the file's current size, and also zero if the target channel is non-blocking and has no bytes free in its output buffer, but I think the javadoc is already clear.

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

> 664:      * transferred, it will not return -1, e.g. in case of EOF of the
> 665:      * {@code src} parameter.
> 666:      *

Looking at this again, I think it may be better if we just add a sentence to the end of the second paragraph of the method description. The second paragraph already covers the case that fewer bytes are transferred. I think it can be something simple like "No bytes are transferred if the source channel has reached end-of-stream". I suggest "end-of-stream" rather than "EOF" because that is the phrase used in the RBC javadoc.

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

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