changeset 7643:36ec39aecf66

Api note explaining the dangers of not developing the right kind of spliterator.
author psandoz
date Thu, 14 Mar 2013 16:58:04 +0100
parents e344f9213d0c
children 3981ddbd7b5f
files src/share/classes/java/util/Spliterator.java
diffstat 1 files changed, 32 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterator.java	Thu Mar 14 11:05:33 2013 -0400
+++ b/src/share/classes/java/util/Spliterator.java	Thu Mar 14 16:58:04 2013 +0100
@@ -191,6 +191,38 @@
  *   }
  * }}</pre>
  *
+ * @apiNote
+ * Spliterators will be used for traversing the elements of a source.  For
+ * mutable sources, arbitrary, non-deterministic behavior may occur if the
+ * source is structurally interfered with (element added, replaced, or removed)
+ * between the time that the Spliterator is constructed and the end of
+ * traversal.  For example, such interference will produce arbitrary,
+ * non-deterministic results when using the Stream API.
+ *
+ * <p>Structural interference of a source can be managed in the following ways:
+ * <ul>
+ * <li>The source cannot be structurally interfered with.  For example, an
+ * instance of {@link java.util.concurrent.CopyOnWriteArrayList} is an immutable
+ * source.  A Spliterator created from the source reports a characteristic of
+ * {@code IMMUTABLE}.</li>
+ * <li>The source manages concurrent modifications.  For example,  a key set of
+ * a {@link java.util.concurrent.ConcurrentHashMap} is a concurrent source.  A
+ * Spliterator created from the source reports a characteristic of
+ * {@code CONCURRENT}.</li>
+ * <li>The mutable source detects, on a best-effort basis, that structural
+ * interference has occurred after traversal has commenced and throws
+ * {@link ConcurrentModificationException}.  For example, an
+ * instance of {@link ArrayList} is such a source.  A Spliterator created from
+ * the source is <em>late-binding</em> and <em>fail-fast</em>.  Creating other
+ * types of Spliterator will increase the risk of error when the Spliterator is
+ * traversed.  A non-<em>fail-fast</em> Spliterator risks arbitrary,
+ * non-deterministic behavior at an undetermined time in the future.  An
+ * <em>early-binding</em> and non-<em>fail-fast</em>Spliterator increases that
+ * risk.  An <em>early-binding</em> and <em>fail-fast</em>Spliterator increases
+ * the likelihood of that Spliterator throwing
+ * {@code ConcurrentModificationException}.</li>
+ * </ul>
+ *
  * @see Collection
  * @since 1.8
  */