changeset 7716:966eb5cf1944

Docs.
author psandoz
date Fri, 22 Mar 2013 17:54:38 +0100
parents 6411a88d1a48
children b1c63d3d9f23
files src/share/classes/java/util/Collection.java src/share/classes/java/util/List.java src/share/classes/java/util/Set.java src/share/classes/java/util/SortedSet.java
diffstat 4 files changed, 100 insertions(+), 56 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Collection.java	Fri Mar 22 09:07:53 2013 -0700
+++ b/src/share/classes/java/util/Collection.java	Fri Mar 22 17:54:38 2013 +0100
@@ -371,6 +371,37 @@
     boolean removeAll(Collection<?> c);
 
     /**
+     * Removes all of the elements of this collection which match the provided
+     * predicate.  Exceptions thrown by the predicate are relayed to the caller.
+     *
+     * @implSpec
+     * The default implementation traverses all elements of the collection using
+     * it's {@link #iterator}.  Each matching element is removed using
+     * {@link Iterator#remove()}.  If the collection's iterator does not
+     * support removal then an {@code UnsupportOperationException} will be
+     * thrown on the first matching element.
+     *
+     * @param filter a predicate which returns {@code true} for elements to be
+     *        removed
+     * @return {@code true} if any elements were removed
+     * @throws UnsupportedOperationException if the <code>removeAll</code>
+     *         method is not supported by this collection
+     * @since 1.8
+     */
+    default boolean removeAll(Predicate<? super E> filter) {
+        boolean removed = false;
+        Iterator<E> each = iterator();
+        while (each.hasNext()) {
+            if (filter.test(each.next())) {
+                each.remove();
+                removed = true;
+            }
+        }
+
+        return removed;
+    }
+
+    /**
      * Retains only the elements in this collection that are contained in the
      * specified collection (optional operation).  In other words, removes from
      * this collection all of its elements that are not contained in the
@@ -459,28 +490,6 @@
     int hashCode();
 
     /**
-     * Removes all of the elements of this collection which match the provided
-     * predicate.
-     *
-     * @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;
-        Iterator<E> each = iterator();
-        while (each.hasNext()) {
-            if (filter.test(each.next())) {
-                each.remove();
-                removed = true;
-            }
-        }
-
-        return removed;
-    }
-
-    /**
      * Creates a {@link Spliterator}, over the elements in this collection, that
      * reports the spliterator characteristic {@code SIZED}.  Overriding
      * implementations should document if the {@code Spliterator} reports any
@@ -504,8 +513,8 @@
      * collection as of the beginning of the terminal stream operation.
      *
      * @implSpec
-     * This implementation creates a <em>late-binding</em> spliterator from
-     * the collection's {@code Iterator}.
+     * The default implementation creates a <em>late-binding</em> spliterator
+     * from the collections's {@code Iterator}.
      *
      * @return a {@code Spliterator} over the elements in this collection
      * @since 1.8
@@ -515,7 +524,7 @@
     }
 
     /**
-     * Creates a sequential {@code Stream} over the elements in this collection.
+     * Creates a sequential {@code Stream} with this collection as its source.
      *
      * <p>This method should be overridden when the {@link #spliterator()}
      * method cannot return a spliterator that is {@code IMMUTABLE},
@@ -523,7 +532,7 @@
      * for details.)
      *
      * @implSpec
-     * This implementation creates a sequential {@code Stream} from the
+     * The default implementation creates a sequential {@code Stream} from the
      * collection's {@code Spliterator}.
      *
      * @return a sequential {@code Stream} over the elements in this collection
@@ -534,8 +543,8 @@
     }
 
     /**
-     * Creates a parallel {@code Stream} over the elements in this collection.  It is
-     * allowable for this method to return a sequential stream.
+     * Creates a parallel {@code Stream} with this collection as its source.
+     * It is allowable for this method to return a sequential stream.
      *
      * <p>This method should be overridden when the {@link #spliterator()}
      * method cannot return a spliterator that is {@code IMMUTABLE},
@@ -543,7 +552,7 @@
      * for details.)
      *
      * @implSpec
-     * This implementation creates a parallel {@code Stream} from the
+     * The default implementation creates a parallel {@code Stream} from the
      * collection's {@code Spliterator}.
      *
      * @return a parallel {@code Stream} over the elements in this collection
--- a/src/share/classes/java/util/List.java	Fri Mar 22 09:07:53 2013 -0700
+++ b/src/share/classes/java/util/List.java	Fri Mar 22 17:54:38 2013 +0100
@@ -377,6 +377,58 @@
     boolean retainAll(Collection<?> c);
 
     /**
+     * Replaces each element of this list with the result of applying the
+     * operator to that element.  Exceptions thrown by the operator are relayed
+     * to the caller.
+     *
+     * @implSpec
+     * The default implementation is equivalent to, for this {@code list}:
+     * <pre>
+     * final ListIterator<E> li = list.listIterator();
+     * while (li.hasNext()) {
+     *   li.set(operator.apply(li.next()));
+     * }
+     * </pre>
+     * If the list's list-iterator does not support the {@code set} operation
+     * then an {@code UnsupportOperationException} will be thrown when replacing
+     * the first element.
+     *
+     * @param operator the operator to apply to each element
+     * @throws UnsupportedOperationException if the <code>replaceAll</code>
+     *         operation is not supported by this list
+     * @throws NullPointerException if the an element is replaced with a null
+     *         value this list does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * @since 1.8
+     */
+    default void replaceAll(UnaryOperator<E> operator) {
+        final ListIterator<E> li = this.listIterator();
+        while (li.hasNext()) {
+            li.set(operator.apply(li.next()));
+        }
+    }
+
+    /**
+     * Sorts this list using the supplied {@code Comparator} to compare elements.
+     *
+     * @implSpec
+     * The default implementation is equivalent to, for this {@code list}:
+     * <pre>Collections.sort(list, c)</pre>
+     *
+     * @param c the {@code Comparator} used to compare list elements
+     * @since 1.8
+     * @throws ClassCastException if the list contains elements that are not
+     *         <i>mutually comparable</i> using the specified comparator.
+     * @throws UnsupportedOperationException if the list's list-iterator does
+     *         not support the {@code set} operation.
+     * @throws IllegalArgumentException (optional) if the comparator is
+     *         found to violate the {@link Comparator} contract
+     */
+    default void sort(Comparator<? super E> c) {
+        Collections.sort(this, c);
+    }
+
+    /**
      * Removes all of the elements from this list (optional operation).
      * The list will be empty after this call returns.
      *
@@ -601,41 +653,20 @@
     List<E> subList(int fromIndex, int toIndex);
 
     /**
-     * Apply the specified operator to each element of this list, replacing
-     * the element with the result of applying the operator to the current
-     * 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();
-        while (li.hasNext()) {
-            li.set(operator.apply(li.next()));
-        }
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
      * Creates a {@code Spliterator}, over the elements in this list, that
      * reports {@code SIZED} and {@code ORDERED}.  Overriding implementations
      * are expected to document if the {@code Spliterator} reports any
      * additional and relevant characteristic values.
      *
+     * @implSpec
+     * The default implementation creates a <em>late-binding</em> spliterator
+     * from the list's {@code Iterator}.
+     *
      * @return a {@code Spliterator} over the elements in this list
      * @since 1.8
      */
     @Override
-    public default Spliterator<E> spliterator() {
+    default Spliterator<E> spliterator() {
         return Spliterators.spliterator(this, Spliterator.ORDERED);
     }
 }
--- a/src/share/classes/java/util/Set.java	Fri Mar 22 09:07:53 2013 -0700
+++ b/src/share/classes/java/util/Set.java	Fri Mar 22 17:54:38 2013 +0100
@@ -389,6 +389,10 @@
      * are expected to document if the {@code Spliterator} reports any
      * additional and relevant characteristic values.
      *
+     * @implSpec
+     * The default implementation creates a <em>late-binding</em> spliterator
+     * from the set's {@code Iterator}.
+     *
      * @return a {@code Spliterator} over the elements in this set
      * @since 1.8
      */
--- a/src/share/classes/java/util/SortedSet.java	Fri Mar 22 09:07:53 2013 -0700
+++ b/src/share/classes/java/util/SortedSet.java	Fri Mar 22 17:54:38 2013 +0100
@@ -235,7 +235,7 @@
      *
      * @implSpec
      * This implementation creates a <em>late-binding</em> spliterator from the
-     * collection's {@code Iterator}.  The spliterator's comparator is the same
+     * sorted set's {@code Iterator}.  The spliterator's comparator is the same
      * as the sorted set's comparator.
      *
      * @return a {@code Spliterator} over the elements in this sorted set