Summary

Modify the specifications of the write methods in each of the classes GatheringByteChannel and WritableByteChannel in the java.nio.channels package to make it more explicit that an invocation of the method might now write all remaining, requested bytes.

Problem

The specifications of the write methods of GatheringByteChannel and WritableByteChannel state that the methods return the number of bytes written, but it is still insufficiently apparent to some developers that the method might need to be called several times to write all bytes remaining in the the buffer.

Solution

Make the specification verbiage be more emphatic that the indicated write methods might need to be called more than once to achieve the desired result.

Specification

--- a/src/java.base/share/classes/java/nio/channels/GatheringByteChannel.java
+++ b/src/java.base/share/classes/java/nio/channels/GatheringByteChannel.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -76,11 +76,14 @@ public interface GatheringByteChannel
      * the final position of each updated buffer, except the last updated
      * buffer, is guaranteed to be equal to that buffer's limit.
      *
-     * <p> Unless otherwise specified, a write operation will return only after
+     * <p> For many types of channels, a write operation will return only after
      * writing all of the <i>r</i> requested bytes.  Some types of channels,
      * depending upon their state, may write only some of the bytes or possibly
-     * none at all.  A socket channel in non-blocking mode, for example, cannot
-     * write any more bytes than are free in the socket's output buffer.
+     * none at all.  A socket channel in {@linkplain
+     * SelectableChannel#isBlocking non-blocking mode}, for example, cannot
+     * write any more bytes than are free in the socket's output buffer.  The
+     * write method may need to be invoked more than once to ensure that all
+     * {@linkplain ByteBuffer#hasRemaining remaining} bytes are written.
      *
      * <p> This method may be invoked at any time.  If another thread has
      * already initiated a write operation upon this channel, however, then an

--- a/src/java.base/share/classes/java/nio/channels/WritableByteChannel.java
+++ b/src/java.base/share/classes/java/nio/channels/WritableByteChannel.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -65,11 +65,14 @@ public interface WritableByteChannel
      * Upon return the buffer's position will be equal to
      * <i>p</i>&nbsp;{@code +}&nbsp;<i>n</i>; its limit will not have changed.
      *
-     * <p> Unless otherwise specified, a write operation will return only after
+     * <p> For many types of channels, a write operation will return only after
      * writing all of the <i>r</i> requested bytes.  Some types of channels,
      * depending upon their state, may write only some of the bytes or possibly
-     * none at all.  A socket channel in non-blocking mode, for example, cannot
-     * write any more bytes than are free in the socket's output buffer.
+     * none at all.  A socket channel in {@linkplain
+     * SelectableChannel#isBlocking non-blocking mode}, for example, cannot
+     * write any more bytes than are free in the socket's output buffer.  The
+     * write method may need to be invoked more than once to ensure that all
+     * {@linkplain ByteBuffer#hasRemaining remaining} bytes are written.
      *
      * <p> This method may be invoked at any time.  If another thread has
      * already initiated a write operation upon this channel, however, then an