Stuart and I refined the text to mention a concurrent modification policy (e.g.
fail-fast or weakly consistent) of any overriding class.
Paul.
diff -r c7b932897909 src/java.base/share/classes/java/lang/Iterable.java
--- a/src/java.base/share/classes/java/lang/Iterable.java Wed Nov 23
10:35:44 2016 -0800
+++ b/src/java.base/share/classes/java/lang/Iterable.java Wed Nov 23
10:40:53 2016 -0800
@@ -53,10 +53,13 @@
/**
* 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 -r c7b932897909 src/java.base/share/classes/java/util/Iterator.java
--- a/src/java.base/share/classes/java/util/Iterator.java Wed Nov 23
10:35:44 2016 -0800
+++ b/src/java.base/share/classes/java/util/Iterator.java Wed Nov 23
10:40:53 2016 -0800
@@ -76,10 +76,15 @@
/**
* 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 @@
* 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:
