changeset 7641:76a06a20617f

Define early binding and fail-fast spliterator.
author psandoz
date Thu, 14 Mar 2013 15:29:30 +0100
parents 51c110b5fc26
children e344f9213d0c
files src/share/classes/java/util/Arrays.java src/share/classes/java/util/Collection.java src/share/classes/java/util/ConcurrentModificationException.java src/share/classes/java/util/Iterator.java src/share/classes/java/util/List.java src/share/classes/java/util/Set.java src/share/classes/java/util/SortedSet.java src/share/classes/java/util/Spliterator.java src/share/classes/java/util/Spliterators.java
diffstat 9 files changed, 51 insertions(+), 10 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Arrays.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Arrays.java	Thu Mar 14 15:29:30 2013 +0100
@@ -4421,6 +4421,7 @@
      * Checks that the half-open interval from {@code offset} to
      * {@code offset+length} are within the range of valid array indexes, and
      * throws an exception if they aren't.
+     * @since 1.8
      */
     public static void checkOffsetLenBounds(int arrayLength, int offset, int length) throws IndexOutOfBoundsException {
         if (offset < 0 || length < 0 || (offset + length) > arrayLength) {
@@ -4452,6 +4453,7 @@
      * @param <T> The type of the array elements
      * @throws NullPointerException if the specified array is null
      * @return A {@code Spliterator} for the specified array
+     * @since 1.8
      */
     public static <T> Spliterator<T> spliterator(T[] array) {
         return Spliterators.spliterator(array, Spliterator.ORDERED);
@@ -4472,6 +4474,7 @@
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Spliterator} for the desired portion of the specified
      *         array
+     * @since 1.8
      */
     public static <T> Spliterator<T> spliterator(T[] array, int fromIndex, int toIndex) {
         return Spliterators.spliterator(array, fromIndex, toIndex, Spliterator.ORDERED);
@@ -4484,6 +4487,7 @@
      * @param array The array for which to create a {@code Spliterator.OfInt}
      * @throws NullPointerException if the specified array is null
      * @return A {@code Spliterator.OfInt} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfInt spliterator(int[] array) {
         return Spliterators.spliterator(array, Spliterator.ORDERED);
@@ -4502,6 +4506,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Spliterator.OfInt} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfInt spliterator(int[] array, int fromIndex, int toIndex) {
         return Spliterators.spliterator(array, fromIndex, toIndex, Spliterator.ORDERED);
@@ -4513,6 +4518,7 @@
      * @param array The array for which to create a {@code Spliterator.OfLong}
      * @throws NullPointerException if the specified array is null
      * @return A {@code Spliterator.OfLong} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfLong spliterator(long[] array) {
         return Spliterators.spliterator(array, Spliterator.ORDERED);
@@ -4531,6 +4537,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Spliterator.OfLong} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfLong spliterator(long[] array, int fromIndex, int toIndex) {
         return Spliterators.spliterator(array, fromIndex, toIndex, Spliterator.ORDERED);
@@ -4543,6 +4550,7 @@
      * @param array The array for which to create a {@code Spliterator.OfDouble}
      * @throws NullPointerException if the specified array is null
      * @return A {@code Spliterator.OfDouble} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfDouble spliterator(double[] array) {
         return Spliterators.spliterator(array, Spliterator.ORDERED);
@@ -4561,6 +4569,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Spliterator.OfDouble} for the specified array
+     * @since 1.8
      */
     public static Spliterator.OfDouble spliterator(double[] array, int fromIndex, int toIndex) {
         return Spliterators.spliterator(array, fromIndex, toIndex, Spliterator.ORDERED);
@@ -4573,6 +4582,7 @@
      * @param <T> The type of the array elements
      * @throws NullPointerException if the specified array is null
      * @return A {@code Stream} backed by the provided array
+     * @since 1.8
      */
     public static <T> Stream<T> stream(T[] array) {
         return stream(array, 0, array.length);
@@ -4592,6 +4602,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Stream} backed by the provided array
+     * @since 1.8
      */
     public static <T> Stream<T> stream(T[] array, int fromIndex, int toIndex) {
         return Streams.stream(spliterator(array, fromIndex, toIndex));
@@ -4603,6 +4614,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return An {@code IntStream} backed by the provided array
+     * @since 1.8
      */
     public static IntStream stream(int[] array) {
         return stream(array, 0, array.length);
@@ -4621,6 +4633,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return An {@code IntStream} backed by the provided array
+     * @since 1.8
      */
     public static IntStream stream(int[] array, int fromIndex, int toIndex) {
         return Streams.intStream(spliterator(array, fromIndex, toIndex));
@@ -4632,6 +4645,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return A {@code LongStream} backed by the provided array
+     * @since 1.8
      */
     public static LongStream stream(long[] array) {
         return stream(array, 0, array.length);
@@ -4650,6 +4664,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code LongStream} backed by the provided array
+     * @since 1.8
      */
     public static LongStream stream(long[] array, int fromIndex, int toIndex) {
         return Streams.longStream(spliterator(array, fromIndex, toIndex));
@@ -4662,6 +4677,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return A {@code DoubleStream} backed by the provided array
+     * @since 1.8
      */
     public static DoubleStream stream(double[] array) {
         return stream(array, 0, array.length);
@@ -4680,6 +4696,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code DoubleStream} backed by the provided array
+     * @since 1.8
      */
     public static DoubleStream stream(double[] array, int fromIndex, int toIndex) {
         return Streams.doubleStream(spliterator(array, fromIndex, toIndex));
@@ -4692,6 +4709,7 @@
      * @param <T> The type of the array elements
      * @throws NullPointerException if the specified array is null
      * @return A {@code Stream} backed by the provided array
+     * @since 1.8
      */
     public static <T> Stream<T> parallelStream(T[] array) {
         return parallelStream(array, 0, array.length);
@@ -4711,6 +4729,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code Stream} backed by the provided array
+     * @since 1.8
      */
     public static <T> Stream<T> parallelStream(T[] array, int fromIndex, int toIndex) {
         return Streams.parallelStream(spliterator(array, fromIndex, toIndex));
@@ -4722,6 +4741,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return An {@code IntStream} backed by the provided array
+     * @since 1.8
      */
     public static IntStream parallelStream(int[] array) {
         return parallelStream(array, 0, array.length);
@@ -4740,6 +4760,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return An {@code IntStream} backed by the provided array
+     * @since 1.8
      */
     public static IntStream parallelStream(int[] array, int fromIndex, int toIndex) {
         return Streams.intParallelStream(spliterator(array, fromIndex, toIndex));
@@ -4751,6 +4772,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return A {@code LongStream} backed by the provided array
+     * @since 1.8
      */
     public static LongStream parallelStream(long[] array) {
         return parallelStream(array, 0, array.length);
@@ -4769,6 +4791,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code LongStream} backed by the provided array
+     * @since 1.8
      */
     public static LongStream parallelStream(long[] array, int fromIndex, int toIndex) {
         return Streams.longParallelStream(spliterator(array, fromIndex, toIndex));
@@ -4780,6 +4803,7 @@
      * @param array The array containing the stream contents
      * @throws NullPointerException if the specified array is null
      * @return A {@code DoubleStream} backed by the provided array
+     * @since 1.8
      */
     public static DoubleStream parallelStream(double[] array) {
         return parallelStream(array, 0, array.length);
@@ -4798,6 +4822,7 @@
      * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
      *         is less than fromIndex, or toIndex is greater than the array size
      * @return A {@code DoubleStream} backed by the provided array
+     * @since 1.8
      */
     public static DoubleStream parallelStream(double[] array, int fromIndex, int toIndex) {
         return Streams.doubleParallelStream(spliterator(array, fromIndex, toIndex));
--- a/src/share/classes/java/util/Collection.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Collection.java	Thu Mar 14 15:29:30 2013 +0100
@@ -465,6 +465,7 @@
      * @param filter a predicate which returns {@code true} for elements to be
      * removed
      * @return {@code true} if any elements were removed
+     * @since 1.8
      */
     public default boolean removeAll(Predicate<? super E> filter) {
         boolean removed = false;
@@ -507,6 +508,7 @@
      * the collection's {@code Iterator}.
      *
      * @return a {@code Spliterator} over the elements in this collection
+     * @since 1.8
      */
     default Spliterator<E> spliterator() {
         return Spliterators.spliterator(this, 0);
@@ -525,6 +527,7 @@
      * collection's {@code Spliterator}.
      *
      * @return a sequential {@code Stream} over the elements in this collection
+     * @since 1.8
      */
     default Stream<E> stream() {
         return Streams.stream(spliterator());
@@ -544,6 +547,7 @@
      * collection's {@code Spliterator}.
      *
      * @return a parallel {@code Stream} over the elements in this collection
+     * @since 1.8
      */
     default Stream<E> parallelStream() {
         return Streams.parallelStream(spliterator());
--- a/src/share/classes/java/util/ConcurrentModificationException.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/ConcurrentModificationException.java	Thu Mar 14 15:29:30 2013 +0100
@@ -57,6 +57,7 @@
  * @author  Josh Bloch
  * @see     Collection
  * @see     Iterator
+ * @see     Spliterator
  * @see     ListIterator
  * @see     Vector
  * @see     LinkedList
--- a/src/share/classes/java/util/Iterator.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Iterator.java	Thu Mar 14 15:29:30 2013 +0100
@@ -93,6 +93,7 @@
      *         yet been called, or the {@code remove} method has already
      *         been called after the last call to the {@code next}
      *         method
+     * @since 1.8
      */
     public default void remove() {
         throw new UnsupportedOperationException("remove");
--- a/src/share/classes/java/util/List.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/List.java	Thu Mar 14 15:29:30 2013 +0100
@@ -606,6 +606,7 @@
      * element.
      *
      * @param operator the operator to apply to each element
+     * @since 1.8
      */
     public default void replaceAll(UnaryOperator<E> operator) {
         final ListIterator<E> li = this.listIterator();
@@ -618,6 +619,7 @@
      * Sort this list using the supplied {@code Comparator} to compare elements.
      *
      * @param c the {@code Comparator} used to compare list elements
+     * @since 1.8
      */
     public default void sort(Comparator<? super E> c) {
         Collections.<E>sort(this, c);
@@ -630,6 +632,7 @@
      * additional and relevant characteristic values.
      *
      * @return a {@code Spliterator} over the elements in this list
+     * @since 1.8
      */
     @Override
     public default Spliterator<E> spliterator() {
--- a/src/share/classes/java/util/Set.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Set.java	Thu Mar 14 15:29:30 2013 +0100
@@ -390,6 +390,7 @@
      * additional and relevant characteristic values.
      *
      * @return a {@code Spliterator} over the elements in this set
+     * @since 1.8
      */
     @Override
     default Spliterator<E> spliterator() {
--- a/src/share/classes/java/util/SortedSet.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/SortedSet.java	Thu Mar 14 15:29:30 2013 +0100
@@ -239,6 +239,7 @@
      * as the sorted set's comparator.
      *
      * @return a {@code Spliterator} over the elements in this sorted set
+     * @since 1.8
      */
     @Override
     default Spliterator<E> spliterator() {
--- a/src/share/classes/java/util/Spliterator.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Spliterator.java	Thu Mar 14 15:29:30 2013 +0100
@@ -52,19 +52,22 @@
  * be defined in the future, so implementors should not assign
  * meanings to unlisted values.
  *
- * <p> A Spliterator that does not report {@code IMMUTABLE} or
+ * <p><a name="binding"/>A Spliterator that does not report {@code IMMUTABLE} or
  * {@code CONCURRENT} is expected to have a documented policy concerning:
- * <em>binding</em> to the element source; and structural interference of
- * the element source detected during traversal.  A <em>late-binding</em>
- * Spliterator does not bind to the source of elements it covers until
- * traversed, split, or queried for estimated size.  Structural modifications
- * made to the element source prior to binding are reflected in the elements
- * covered when the Spliterator is bound.  Structural interference detected
- * during traversal, due to modifications, after the Spliterator is bound may,
- * for example, result in the throwing of a
+ * late or early <em>binding</em> to the element source; and structural
+ * interference of the element source detected after binding.  A
+ * <em>late-binding</em> Spliterator binds to the source of elements at the
+ * point of first traversal, first split, or first query for estimated size.  An
+ * <em>early-binding</em> Spliterator binds to the source of elements at the
+ * point of construction or first invocation of any method.  Structural
+ * modifications made to the element source prior to binding are reflected in
+ * the elements covered when the Spliterator is bound.  A late or early binding
+ * Spliterator should also be a <em>fail-fast</em> Spliterator.  When structural
+ * interference is detected after binding, on a best-effort basis, a
+ * <em>fail-fast</em> Spliterator should throw
  * {@link ConcurrentModificationException}.
  *
- * <p> To accommodate broad usage, this interface places no further
+ * <p>To accommodate broad usage, this interface places no further
  * absolute demands on Spliterators. However, most default methods are
  * sub-optimal for most Spliterator implementations, and so should be
  * overridden whenever appropriate.
@@ -188,6 +191,7 @@
  *   }
  * }}</pre>
  *
+ * @see Collection
  * @since 1.8
  */
 public interface Spliterator<T> {
--- a/src/share/classes/java/util/Spliterators.java	Thu Mar 14 12:09:10 2013 +0100
+++ b/src/share/classes/java/util/Spliterators.java	Thu Mar 14 15:29:30 2013 +0100
@@ -35,6 +35,7 @@
  * {@link Spliterator.OfInt}, {@link Spliterator.OfLong}, and
  * {@link Spliterator.OfDouble}.
  *
+ * @see Spliterator
  * @since 1.8
  */
 public final class Spliterators {