From 7e585645409b2527440506389687c41e7d137b5d Mon Sep 17 00:00:00 2001
From: Paul Sandoz <psandoz@openjdk.org>
Date: Wed, 30 Nov 2016 17:15:58 -0800
Subject: [PATCH] 8168745: Iterator.forEachRemaining vs. Iterator.remove

Reviewed-by: martin, smarks
---
 .../share/classes/java/lang/Iterable.java     |  9 ++++++---
 .../share/classes/java/util/Iterator.java     | 20 +++++++++++++++----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/jdk/src/java.base/share/classes/java/lang/Iterable.java b/jdk/src/java.base/share/classes/java/lang/Iterable.java
index de91500ce50..89059022905 100644
--- a/jdk/src/java.base/share/classes/java/lang/Iterable.java
+++ b/jdk/src/java.base/share/classes/java/lang/Iterable.java
@@ -53,10 +53,13 @@ public interface Iterable<T> {
     /**
      * Performs the given action for each element of the {@code Iterable}
      * until all elements have been processed or the action throws an
-     * exception.  Unless otherwise specified by the implementing class,
-     * actions are performed in the order of iteration (if an iteration order
-     * is specified).  Exceptions thrown by the action are relayed to the
+     * exception.  Actions are performed in the order of iteration, if that
+     * order is specified.  Exceptions thrown by the action are relayed to the
      * caller.
+     * <p>
+     * The behavior of this method is unspecified if the action performs
+     * side-effects that modify the underlying source of elements, unless an
+     * overriding class has specified a concurrent modification policy.
      *
      * @implSpec
      * <p>The default implementation behaves as if:
diff --git a/jdk/src/java.base/share/classes/java/util/Iterator.java b/jdk/src/java.base/share/classes/java/util/Iterator.java
index ca05cbb8762..7dcb155c63d 100644
--- a/jdk/src/java.base/share/classes/java/util/Iterator.java
+++ b/jdk/src/java.base/share/classes/java/util/Iterator.java
@@ -76,10 +76,15 @@ public interface Iterator<E> {
     /**
      * Removes from the underlying collection the last element returned
      * by this iterator (optional operation).  This method can be called
-     * only once per call to {@link #next}.  The behavior of an iterator
-     * is unspecified if the underlying collection is modified while the
-     * iteration is in progress in any way other than by calling this
-     * method.
+     * only once per call to {@link #next}.
+     * <p>
+     * The behavior of an iterator is unspecified if the underlying collection
+     * is modified while the iteration is in progress in any way other than by
+     * calling this method, unless an overriding class has specified a
+     * concurrent modification policy.
+     * <p>
+     * The behavior of an iterator is unspecified if this method is called
+     * after a call to the {@link #forEachRemaining forEachRemaining} method.
      *
      * @implSpec
      * The default implementation throws an instance of
@@ -102,6 +107,13 @@ public interface Iterator<E> {
      * 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.
+     * <p>
+     * The behavior of an iterator is unspecified if the action modifies the
+     * collection in any way (even by calling the {@link #remove remove} method),
+     * unless an overriding class has specified a concurrent modification policy.
+     * <p>
+     * Subsequent behavior of an iterator is unspecified if the action throws an
+     * exception.
      *
      * @implSpec
      * <p>The default implementation behaves as if: