Summary

Add verbiage in type-specific buffer classes to clarify the meaning of "optional operation."

Problem

Some methods in java.nio.Buffer and its type-specific subclasses java.nio.$Type$Buffer are specified to be optional operations but the wording describing what this means is only in the parent class, Buffer.

Solution

Add a section further clarifying the meaning of "optional operation" to the class-level specifications of the type-specific subclasses of Buffer.

Specification

--- a/src/java.base/share/classes/java/nio/X-Buffer.java.template
+++ b/src/java.base/share/classes/java/nio/X-Buffer.java.template
@@ -258,6 +258,15 @@ import jdk.internal.util.ArraysSupport;
  * cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
  *
 #end[char]
+ * <h2> Optional operations </h2>
+ * Methods specified as
+ * <i>{@linkplain Buffer##read-only-buffers-heading optional
+ * operations}</i> throw a {@linkplain ReadOnlyBufferException} when invoked
+ * on a {@linkplain java.nio.Buffer#isReadOnly read-only} $Type$Buffer. The
+ * methods {@linkplain #array array} and {@linkplain #arrayOffset arrayOffset}
+ * throw an {@linkplain UnsupportedOperationException} if the $Type$Buffer is
+ * not backed by an {@linkplain Buffer#hasArray accessible $type$ array}
+ * (irrespective of whether the $Type$Buffer is read-only).
  *