8267939: Clarify the specification of iterator and spliterator forEachRemaining

Reviewed-by: smarks

src/java.base/share/classes/java/util/PrimitiveIterator.java

@@ -68,10 +68,18 @@ import java.util.function.LongConsumer;
 public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
 
     /**
-     * Performs the given action for each remaining element, in the order
+     * Performs the given action for each remaining element until all elements
-     * elements occur when iterating, until all elements have been processed
+     * have been processed or the action throws an exception.  Actions are
-     * or the action throws an exception.  Errors or runtime exceptions
+     * performed in the order of iteration, if that order is specified.
-     * thrown by the action are relayed to the caller.
+     * Exceptions thrown by the action are relayed to the caller.
+     * <p>
+     * The behavior of an iterator is unspecified if the action modifies the
+     * source of elements in any way (even by calling the {@link #remove remove}
+     * method or other mutator methods of {@code Iterator} subtypes),
+     * unless an overriding class has specified a concurrent modification policy.
+     * <p>
+     * Subsequent behavior of an iterator is unspecified if the action throws an
+     * exception.
      *
      * @param action The action to be performed for each element
      * @throws NullPointerException if the specified action is null
@@ -94,20 +102,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
         int nextInt();
 
         /**
-         * Performs the given action for each remaining element until all elements
+         * {@inheritDoc}
-         * have been processed or the action throws an exception.  Actions are
-         * performed in the order of iteration, if that order is specified.
-         * Exceptions thrown by the action are relayed to the caller.
-         *
          * @implSpec
          * <p>The default implementation behaves as if:
          * <pre>{@code
          *     while (hasNext())
          *         action.accept(nextInt());
          * }</pre>
-         *
-         * @param action The action to be performed for each element
-         * @throws NullPointerException if the specified action is null
          */
         default void forEachRemaining(IntConsumer action) {
             Objects.requireNonNull(action);
@@ -168,20 +169,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
         long nextLong();
 
         /**
-         * Performs the given action for each remaining element until all elements
+         * {@inheritDoc}
-         * have been processed or the action throws an exception.  Actions are
-         * performed in the order of iteration, if that order is specified.
-         * Exceptions thrown by the action are relayed to the caller.
-         *
          * @implSpec
          * <p>The default implementation behaves as if:
          * <pre>{@code
          *     while (hasNext())
          *         action.accept(nextLong());
          * }</pre>
-         *
-         * @param action The action to be performed for each element
-         * @throws NullPointerException if the specified action is null
          */
         default void forEachRemaining(LongConsumer action) {
             Objects.requireNonNull(action);
@@ -241,20 +235,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
         double nextDouble();
 
         /**
-         * Performs the given action for each remaining element until all elements
+         * {@inheritDoc}
-         * have been processed or the action throws an exception.  Actions are
-         * performed in the order of iteration, if that order is specified.
-         * Exceptions thrown by the action are relayed to the caller.
-         *
          * @implSpec
          * <p>The default implementation behaves as if:
          * <pre>{@code
          *     while (hasNext())
          *         action.accept(nextDouble());
          * }</pre>
-         *
-         * @param action The action to be performed for each element
-         * @throws NullPointerException if the specified action is null
          */
         default void forEachRemaining(DoubleConsumer action) {
             Objects.requireNonNull(action);

src/java.base/share/classes/java/util/Spliterator.java

@@ -300,6 +300,9 @@ public interface Spliterator<T> {
      * Spliterator is {@link #ORDERED} the action is performed on the
      * next element in encounter order.  Exceptions thrown by the
      * action are relayed to the caller.
+     * <p>
+     * Subsequent behavior of a spliterator is unspecified if the action throws
+     * an exception.
      *
      * @param action The action
      * @return {@code false} if no remaining elements existed
@@ -314,6 +317,9 @@ public interface Spliterator<T> {
      * throws an exception.  If this Spliterator is {@link #ORDERED}, actions
      * are performed in encounter order.  Exceptions thrown by the action
      * are relayed to the caller.
+     * <p>
+     * Subsequent behavior of a spliterator is unspecified if the action throws
+     * an exception.
      *
      * @implSpec
      * The default implementation repeatedly invokes {@link #tryAdvance} until
@@ -613,6 +619,9 @@ public interface Spliterator<T> {
          * Spliterator is {@link #ORDERED} the action is performed on the
          * next element in encounter order.  Exceptions thrown by the
          * action are relayed to the caller.
+         * <p>
+         * Subsequent behavior of a spliterator is unspecified if the action throws
+         * an exception.
          *
          * @param action The action
          * @return {@code false} if no remaining elements existed
@@ -628,6 +637,9 @@ public interface Spliterator<T> {
          * action throws an exception.  If this Spliterator is {@link #ORDERED},
          * actions are performed in encounter order.  Exceptions thrown by the
          * action are relayed to the caller.
+         * <p>
+         * Subsequent behavior of a spliterator is unspecified if the action throws
+         * an exception.
          *
          * @implSpec
          * The default implementation repeatedly invokes {@link #tryAdvance}