rev 17661 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: XXX

   1 /*
   2  * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import java.util.function.Predicate;
  29 import java.util.stream.Stream;
  30 import java.util.stream.StreamSupport;
  31 
  32 /**
  33  * The root interface in the <i>collection hierarchy</i>.  A collection
  34  * represents a group of objects, known as its <i>elements</i>.  Some
  35  * collections allow duplicate elements and others do not.  Some are ordered
  36  * and others unordered.  The JDK does not provide any <i>direct</i>
  37  * implementations of this interface: it provides implementations of more
  38  * specific subinterfaces like {@code Set} and {@code List}.  This interface
  39  * is typically used to pass collections around and manipulate them where
  40  * maximum generality is desired.
  41  *
  42  * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
  43  * duplicate elements) should implement this interface directly.
  44  *
  45  * <p>All general-purpose {@code Collection} implementation classes (which
  46  * typically implement {@code Collection} indirectly through one of its
  47  * subinterfaces) should provide two "standard" constructors: a void (no
  48  * arguments) constructor, which creates an empty collection, and a
  49  * constructor with a single argument of type {@code Collection}, which
  50  * creates a new collection with the same elements as its argument.  In
  51  * effect, the latter constructor allows the user to copy any collection,
  52  * producing an equivalent collection of the desired implementation type.
  53  * There is no way to enforce this convention (as interfaces cannot contain
  54  * constructors) but all of the general-purpose {@code Collection}
  55  * implementations in the Java platform libraries comply.
  56  *
  57  * <p>Certain methods are specified to be
  58  * <i>optional</i>. If a collection implementation doesn't implement a
  59  * particular operation, it should define the corresponding method to throw
  60  * {@code UnsupportedOperationException}. Such methods are marked "optional
  61  * operation" in method specifications of the collections interfaces.
  62  *
  63  * <p><a id="optional-restrictions"></a>Some collection implementations
  64  * have restrictions on the elements that they may contain.
  65  * For example, some implementations prohibit null elements,




  66  * and some have restrictions on the types of their elements.  Attempting to
  67  * add an ineligible element throws an unchecked exception, typically
  68  * {@code NullPointerException} or {@code ClassCastException}.  Attempting
  69  * to query the presence of an ineligible element may throw an exception,
  70  * or it may simply return false; some implementations will exhibit the former
  71  * behavior and some will exhibit the latter.  More generally, attempting an
  72  * operation on an ineligible element whose completion would not result in
  73  * the insertion of an ineligible element into the collection may throw an
  74  * exception or it may succeed, at the option of the implementation.
  75  * Such exceptions are marked as "optional" in the specification for this
  76  * interface.
  77  *
  78  * <p>It is up to each collection to determine its own synchronization
  79  * policy.  In the absence of a stronger guarantee by the
  80  * implementation, undefined behavior may result from the invocation
  81  * of any method on a collection that is being mutated by another
  82  * thread; this includes direct invocations, passing the collection to
  83  * a method that might perform invocations, and using an existing
  84  * iterator to examine the collection.
  85  *
  86  * <p>Many methods in Collections Framework interfaces are defined in
  87  * terms of the {@link Object#equals(Object) equals} method.  For example,
  88  * the specification for the {@link #contains(Object) contains(Object o)}
  89  * method says: "returns {@code true} if and only if this collection
  90  * contains at least one element {@code e} such that
  91  * {@code (o==null ? e==null : o.equals(e))}."  This specification should
  92  * <i>not</i> be construed to imply that invoking {@code Collection.contains}
  93  * with a non-null argument {@code o} will cause {@code o.equals(e)} to be
  94  * invoked for any element {@code e}.  Implementations are free to implement
  95  * optimizations whereby the {@code equals} invocation is avoided, for
  96  * example, by first comparing the hash codes of the two elements.  (The
  97  * {@link Object#hashCode()} specification guarantees that two objects with
  98  * unequal hash codes cannot be equal.)  More generally, implementations of
  99  * the various Collections Framework interfaces are free to take advantage of
 100  * the specified behavior of underlying {@link Object} methods wherever the
 101  * implementor deems it appropriate.
 102  *
 103  * <p>Some collection operations which perform recursive traversal of the
 104  * collection may fail with an exception for self-referential instances where
 105  * the collection directly or indirectly contains itself. This includes the
 106  * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
 107  * methods. Implementations may optionally handle the self-referential scenario,
 108  * however most current implementations do not do so.
 109  *
 110  * <p><a id="view"><b>View collections.</b></a>
 111  * Most collections contain elements themselves. By contrast, <i>view collections</i>
 112  * themselves do not contain elements, but instead rely on a backing collection to
 113  * store the actual elements. Operations that are not handled by the view
 114  * collection itself are delegated to the backing collection. Examples of
 115  * view collections include the wrapper collections returned by methods such as
 116  * {@link unmodifiableCollection},
 117  * {@link checkedCollection}, and
 118  * {@link synchronizedCollection}.
 119  * Other examples of view collections include collections that provide a
 120  * different representation of the same elements, for example, as
 121  * provided by {@link List.subList}, {@link NavigableSet.subSet}, or
 122  * {@link Map.entrySet}. Any changes made to the backing collection are
 123  * visible in the view collection. Correspondingly, any changes made to
 124  * the view collection are written through to the backing collection.
 125  * Although they technically aren't collections, instances of
 126  * {@link Iterator} and {@link ListIterator} can also allow modifications
 127  * to be written through to the backing collection, and in some cases,
 128  * modifications to the backing collection will be visible to the Iterator
 129  * during iteration.
 130  *
 131  * <p><a id="unmodifiable"><b>Unmodifiable collections.</b></a>
 132  * Certain methods of this interface are considered "destructive" and are called
 133  * "mutator" methods in that they modify the group of objects contained within
 134  * the collection on which they operate. They can be specified to throw
 135  * {@code UnsupportedOperationException} if this collection implementation
 136  * does not support the operation. Such methods should (but are not required
 137  * to) throw an {@code UnsupportedOperationException} if the invocation would
 138  * have no effect on the collection. For example, invoking the
 139  * {@link #addAll addAll} method on a collection that does not support
 140  * the {@link #add add} operation should throw the exception if
 141  * the collection passed as an argument is empty. It is recommended
 142  * that such methods always throw the exception unconditionally, as
 143  * throwing only in certain cases can lead to programming errors.
 144  *
 145  * <p>An <i>unmodifiable collection</i> is a collection, all of whose
 146  * mutator methods (as defined above) are specified to throw
 147  * {@code UnsupportedOperationException}. Such a collection thus cannot be
 148  * modified by calling any methods on it. For a collection to be properly
 149  * unmodifiable, any view collections derived from it must also be unmodifiable.
 150  * For example, if a List is unmodifiable, the List returned by
 151  * {@link List.subList} should also be unmodifiable.
 152  *
 153  * <p>An unmodifiable collection is not necessarily immutable. If the
 154  * contained elements are mutable, the entire collection is clearly
 155  * mutable, even though it might be unmodifiable. For example, consider
 156  * two unmodifiable lists containing mutable elements. The result of calling
 157  * {@code list1.equals(list2)} might differ from one call to the next if
 158  * the elements had been mutated, even though both lists are unmodifiable.
 159  * However, if an unmodifiable collection contains all immutable elements,
 160  * it can be considered effectively immutable.
 161  *
 162  * <p><a id="unmodview"><b>Unmodifiable view collections.</b></a>
 163  * An unmodifiable view is a collection that is unmodifiable and that is
 164  * a view onto a backing collection. Mutator methods throw
 165  * {@code UnsupportedOperationException}, as described above, while
 166  * reading and querying methods are delegated to the backing collection.
 167  * The effect is to provide read-only access to the backing collection.
 168  * This is useful for a component to provide users with read access to
 169  * an internal collection, while preventing them from modifying such
 170  * collections unexpectedly.
 171  *
 172  * <p>Note that changes to the backing collection might still be possible,
 173  * and if they occur, they are visible through the unmodifiable view. As
 174  * above, an unmodifiable view collection is not necessarily immutable.
 175  * However, if the backing collection of an unmodifiable view is effectively
 176  * immutable, or if the only reference to the backing collection is through
 177  * an unmodifiable view, the view can be considered effectively immutable.
 178  *
 179  * <p>This interface is a member of the
 180  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
 181  * Java Collections Framework</a>.
 182  *
 183  * @implSpec
 184  * The default method implementations (inherited or otherwise) do not apply any
 185  * synchronization protocol.  If a {@code Collection} implementation has a
 186  * specific synchronization protocol, then it must override default
 187  * implementations to apply that protocol.
 188  *
 189  * @param <E> the type of elements in this collection
 190  *
 191  * @author  Josh Bloch
 192  * @author  Neal Gafter
 193  * @see     Set
 194  * @see     List
 195  * @see     Map
 196  * @see     SortedSet
 197  * @see     SortedMap
 198  * @see     HashSet
 199  * @see     TreeSet
 200  * @see     ArrayList
 201  * @see     LinkedList
 202  * @see     Vector
 203  * @see     Collections
 204  * @see     Arrays
 205  * @see     AbstractCollection
 206  * @since 1.2
 207  */
 208 
 209 public interface Collection<E> extends Iterable<E> {
 210     // Query Operations
 211 
 212     /**
 213      * Returns the number of elements in this collection.  If this collection
 214      * contains more than {@code Integer.MAX_VALUE} elements, returns
 215      * {@code Integer.MAX_VALUE}.
 216      *
 217      * @return the number of elements in this collection
 218      */
 219     int size();
 220 
 221     /**
 222      * Returns {@code true} if this collection contains no elements.
 223      *
 224      * @return {@code true} if this collection contains no elements
 225      */
 226     boolean isEmpty();
 227 
 228     /**
 229      * Returns {@code true} if this collection contains the specified element.
 230      * More formally, returns {@code true} if and only if this collection
 231      * contains at least one element {@code e} such that
 232      * {@code Objects.equals(o, e)}.
 233      *
 234      * @param o element whose presence in this collection is to be tested
 235      * @return {@code true} if this collection contains the specified
 236      *         element
 237      * @throws ClassCastException if the type of the specified element
 238      *         is incompatible with this collection
 239      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 240      * @throws NullPointerException if the specified element is null and this
 241      *         collection does not permit null elements
 242      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 243      */
 244     boolean contains(Object o);
 245 
 246     /**
 247      * Returns an iterator over the elements in this collection.  There are no
 248      * guarantees concerning the order in which the elements are returned
 249      * (unless this collection is an instance of some class that provides a
 250      * guarantee).
 251      *
 252      * @return an {@code Iterator} over the elements in this collection
 253      */
 254     Iterator<E> iterator();
 255 
 256     /**
 257      * Returns an array containing all of the elements in this collection.
 258      * If this collection makes any guarantees as to what order its elements
 259      * are returned by its iterator, this method must return the elements in
 260      * the same order.
 261      *
 262      * <p>The returned array will be "safe" in that no references to it are
 263      * maintained by this collection.  (In other words, this method must
 264      * allocate a new array even if this collection is backed by an array).
 265      * The caller is thus free to modify the returned array.
 266      *
 267      * <p>This method acts as bridge between array-based and collection-based
 268      * APIs.
 269      *
 270      * @return an array containing all of the elements in this collection
 271      */
 272     Object[] toArray();
 273 
 274     /**
 275      * Returns an array containing all of the elements in this collection;
 276      * the runtime type of the returned array is that of the specified array.
 277      * If the collection fits in the specified array, it is returned therein.
 278      * Otherwise, a new array is allocated with the runtime type of the
 279      * specified array and the size of this collection.
 280      *
 281      * <p>If this collection fits in the specified array with room to spare
 282      * (i.e., the array has more elements than this collection), the element
 283      * in the array immediately following the end of the collection is set to
 284      * {@code null}.  (This is useful in determining the length of this
 285      * collection <i>only</i> if the caller knows that this collection does
 286      * not contain any {@code null} elements.)
 287      *
 288      * <p>If this collection makes any guarantees as to what order its elements
 289      * are returned by its iterator, this method must return the elements in
 290      * the same order.
 291      *
 292      * <p>Like the {@link #toArray()} method, this method acts as bridge between
 293      * array-based and collection-based APIs.  Further, this method allows
 294      * precise control over the runtime type of the output array, and may,
 295      * under certain circumstances, be used to save allocation costs.
 296      *
 297      * <p>Suppose {@code x} is a collection known to contain only strings.
 298      * The following code can be used to dump the collection into a newly
 299      * allocated array of {@code String}:
 300      *
 301      * <pre>
 302      *     String[] y = x.toArray(new String[0]);</pre>
 303      *
 304      * Note that {@code toArray(new Object[0])} is identical in function to
 305      * {@code toArray()}.
 306      *
 307      * @param <T> the runtime type of the array to contain the collection
 308      * @param a the array into which the elements of this collection are to be
 309      *        stored, if it is big enough; otherwise, a new array of the same
 310      *        runtime type is allocated for this purpose.
 311      * @return an array containing all of the elements in this collection
 312      * @throws ArrayStoreException if the runtime type of the specified array
 313      *         is not a supertype of the runtime type of every element in
 314      *         this collection
 315      * @throws NullPointerException if the specified array is null
 316      */
 317     <T> T[] toArray(T[] a);
 318 
 319     // Modification Operations
 320 
 321     /**
 322      * Ensures that this collection contains the specified element (optional
 323      * operation).  Returns {@code true} if this collection changed as a
 324      * result of the call.  (Returns {@code false} if this collection does
 325      * not permit duplicates and already contains the specified element.)<p>
 326      *
 327      * Collections that support this operation may place limitations on what
 328      * elements may be added to this collection.  In particular, some
 329      * collections will refuse to add {@code null} elements, and others will
 330      * impose restrictions on the type of elements that may be added.
 331      * Collection classes should clearly specify in their documentation any
 332      * restrictions on what elements may be added.<p>
 333      *
 334      * If a collection refuses to add a particular element for any reason
 335      * other than that it already contains the element, it <i>must</i> throw
 336      * an exception (rather than returning {@code false}).  This preserves
 337      * the invariant that a collection always contains the specified element
 338      * after this call returns.
 339      *
 340      * @param e element whose presence in this collection is to be ensured
 341      * @return {@code true} if this collection changed as a result of the
 342      *         call
 343      * @throws UnsupportedOperationException if the {@code add} operation
 344      *         is not supported by this collection
 345      * @throws ClassCastException if the class of the specified element
 346      *         prevents it from being added to this collection
 347      * @throws NullPointerException if the specified element is null and this
 348      *         collection does not permit null elements
 349      * @throws IllegalArgumentException if some property of the element
 350      *         prevents it from being added to this collection
 351      * @throws IllegalStateException if the element cannot be added at this
 352      *         time due to insertion restrictions
 353      */
 354     boolean add(E e);
 355 
 356     /**
 357      * Removes a single instance of the specified element from this
 358      * collection, if it is present (optional operation).  More formally,
 359      * removes an element {@code e} such that
 360      * {@code Objects.equals(o, e)}, if
 361      * this collection contains one or more such elements.  Returns
 362      * {@code true} if this collection contained the specified element (or
 363      * equivalently, if this collection changed as a result of the call).
 364      *
 365      * @param o element to be removed from this collection, if present
 366      * @return {@code true} if an element was removed as a result of this call
 367      * @throws ClassCastException if the type of the specified element
 368      *         is incompatible with this collection
 369      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 370      * @throws NullPointerException if the specified element is null and this
 371      *         collection does not permit null elements
 372      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 373      * @throws UnsupportedOperationException if the {@code remove} operation
 374      *         is not supported by this collection
 375      */
 376     boolean remove(Object o);
 377 
 378 
 379     // Bulk Operations
 380 
 381     /**
 382      * Returns {@code true} if this collection contains all of the elements
 383      * in the specified collection.
 384      *
 385      * @param  c collection to be checked for containment in this collection
 386      * @return {@code true} if this collection contains all of the elements
 387      *         in the specified collection
 388      * @throws ClassCastException if the types of one or more elements
 389      *         in the specified collection are incompatible with this
 390      *         collection
 391      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 392      * @throws NullPointerException if the specified collection contains one
 393      *         or more null elements and this collection does not permit null
 394      *         elements
 395      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
 396      *         or if the specified collection is null.
 397      * @see    #contains(Object)
 398      */
 399     boolean containsAll(Collection<?> c);
 400 
 401     /**
 402      * Adds all of the elements in the specified collection to this collection
 403      * (optional operation).  The behavior of this operation is undefined if
 404      * the specified collection is modified while the operation is in progress.
 405      * (This implies that the behavior of this call is undefined if the
 406      * specified collection is this collection, and this collection is
 407      * nonempty.)
 408      *
 409      * @param c collection containing elements to be added to this collection
 410      * @return {@code true} if this collection changed as a result of the call
 411      * @throws UnsupportedOperationException if the {@code addAll} operation
 412      *         is not supported by this collection
 413      * @throws ClassCastException if the class of an element of the specified
 414      *         collection prevents it from being added to this collection
 415      * @throws NullPointerException if the specified collection contains a
 416      *         null element and this collection does not permit null elements,
 417      *         or if the specified collection is null
 418      * @throws IllegalArgumentException if some property of an element of the
 419      *         specified collection prevents it from being added to this
 420      *         collection
 421      * @throws IllegalStateException if not all the elements can be added at
 422      *         this time due to insertion restrictions
 423      * @see #add(Object)
 424      */
 425     boolean addAll(Collection<? extends E> c);
 426 
 427     /**
 428      * Removes all of this collection's elements that are also contained in the
 429      * specified collection (optional operation).  After this call returns,
 430      * this collection will contain no elements in common with the specified
 431      * collection.
 432      *
 433      * @param c collection containing elements to be removed from this collection
 434      * @return {@code true} if this collection changed as a result of the
 435      *         call
 436      * @throws UnsupportedOperationException if the {@code removeAll} method
 437      *         is not supported by this collection
 438      * @throws ClassCastException if the types of one or more elements
 439      *         in this collection are incompatible with the specified
 440      *         collection
 441      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 442      * @throws NullPointerException if this collection contains one or more
 443      *         null elements and the specified collection does not support
 444      *         null elements
 445      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
 446      *         or if the specified collection is null
 447      * @see #remove(Object)
 448      * @see #contains(Object)
 449      */
 450     boolean removeAll(Collection<?> c);
 451 
 452     /**
 453      * Removes all of the elements of this collection that satisfy the given
 454      * predicate.  Errors or runtime exceptions thrown during iteration or by
 455      * the predicate are relayed to the caller.
 456      *
 457      * @implSpec
 458      * The default implementation traverses all elements of the collection using
 459      * its {@link #iterator}.  Each matching element is removed using
 460      * {@link Iterator#remove()}.  If the collection's iterator does not
 461      * support removal then an {@code UnsupportedOperationException} will be
 462      * thrown on the first matching element.
 463      *
 464      * @param filter a predicate which returns {@code true} for elements to be
 465      *        removed
 466      * @return {@code true} if any elements were removed
 467      * @throws NullPointerException if the specified filter is null
 468      * @throws UnsupportedOperationException if elements cannot be removed
 469      *         from this collection.  Implementations may throw this exception if a
 470      *         matching element cannot be removed or if, in general, removal is not
 471      *         supported.
 472      * @since 1.8
 473      */
 474     default boolean removeIf(Predicate<? super E> filter) {
 475         Objects.requireNonNull(filter);
 476         boolean removed = false;
 477         final Iterator<E> each = iterator();
 478         while (each.hasNext()) {
 479             if (filter.test(each.next())) {
 480                 each.remove();
 481                 removed = true;
 482             }
 483         }
 484         return removed;
 485     }
 486 
 487     /**
 488      * Retains only the elements in this collection that are contained in the
 489      * specified collection (optional operation).  In other words, removes from
 490      * this collection all of its elements that are not contained in the
 491      * specified collection.
 492      *
 493      * @param c collection containing elements to be retained in this collection
 494      * @return {@code true} if this collection changed as a result of the call
 495      * @throws UnsupportedOperationException if the {@code retainAll} operation
 496      *         is not supported by this collection
 497      * @throws ClassCastException if the types of one or more elements
 498      *         in this collection are incompatible with the specified
 499      *         collection
 500      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
 501      * @throws NullPointerException if this collection contains one or more
 502      *         null elements and the specified collection does not permit null
 503      *         elements
 504      *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
 505      *         or if the specified collection is null
 506      * @see #remove(Object)
 507      * @see #contains(Object)
 508      */
 509     boolean retainAll(Collection<?> c);
 510 
 511     /**
 512      * Removes all of the elements from this collection (optional operation).
 513      * The collection will be empty after this method returns.
 514      *
 515      * @throws UnsupportedOperationException if the {@code clear} operation
 516      *         is not supported by this collection
 517      */
 518     void clear();
 519 
 520 
 521     // Comparison and hashing
 522 
 523     /**
 524      * Compares the specified object with this collection for equality. <p>
 525      *
 526      * While the {@code Collection} interface adds no stipulations to the
 527      * general contract for the {@code Object.equals}, programmers who
 528      * implement the {@code Collection} interface "directly" (in other words,
 529      * create a class that is a {@code Collection} but is not a {@code Set}
 530      * or a {@code List}) must exercise care if they choose to override the
 531      * {@code Object.equals}.  It is not necessary to do so, and the simplest
 532      * course of action is to rely on {@code Object}'s implementation, but
 533      * the implementor may wish to implement a "value comparison" in place of
 534      * the default "reference comparison."  (The {@code List} and
 535      * {@code Set} interfaces mandate such value comparisons.)<p>
 536      *
 537      * The general contract for the {@code Object.equals} method states that
 538      * equals must be symmetric (in other words, {@code a.equals(b)} if and
 539      * only if {@code b.equals(a)}).  The contracts for {@code List.equals}
 540      * and {@code Set.equals} state that lists are only equal to other lists,
 541      * and sets to other sets.  Thus, a custom {@code equals} method for a
 542      * collection class that implements neither the {@code List} nor
 543      * {@code Set} interface must return {@code false} when this collection
 544      * is compared to any list or set.  (By the same logic, it is not possible
 545      * to write a class that correctly implements both the {@code Set} and
 546      * {@code List} interfaces.)
 547      *
 548      * @param o object to be compared for equality with this collection
 549      * @return {@code true} if the specified object is equal to this
 550      * collection
 551      *
 552      * @see Object#equals(Object)
 553      * @see Set#equals(Object)
 554      * @see List#equals(Object)
 555      */
 556     boolean equals(Object o);
 557 
 558     /**
 559      * Returns the hash code value for this collection.  While the
 560      * {@code Collection} interface adds no stipulations to the general
 561      * contract for the {@code Object.hashCode} method, programmers should
 562      * take note that any class that overrides the {@code Object.equals}
 563      * method must also override the {@code Object.hashCode} method in order
 564      * to satisfy the general contract for the {@code Object.hashCode} method.
 565      * In particular, {@code c1.equals(c2)} implies that
 566      * {@code c1.hashCode()==c2.hashCode()}.
 567      *
 568      * @return the hash code value for this collection
 569      *
 570      * @see Object#hashCode()
 571      * @see Object#equals(Object)
 572      */
 573     int hashCode();
 574 
 575     /**
 576      * Creates a {@link Spliterator} over the elements in this collection.
 577      *
 578      * Implementations should document characteristic values reported by the
 579      * spliterator.  Such characteristic values are not required to be reported
 580      * if the spliterator reports {@link Spliterator#SIZED} and this collection
 581      * contains no elements.
 582      *
 583      * <p>The default implementation should be overridden by subclasses that
 584      * can return a more efficient spliterator.  In order to
 585      * preserve expected laziness behavior for the {@link #stream()} and
 586      * {@link #parallelStream()} methods, spliterators should either have the
 587      * characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
 588      * <em><a href="Spliterator.html#binding">late-binding</a></em>.
 589      * If none of these is practical, the overriding class should describe the
 590      * spliterator's documented policy of binding and structural interference,
 591      * and should override the {@link #stream()} and {@link #parallelStream()}
 592      * methods to create streams using a {@code Supplier} of the spliterator,
 593      * as in:
 594      * <pre>{@code
 595      *     Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
 596      * }</pre>
 597      * <p>These requirements ensure that streams produced by the
 598      * {@link #stream()} and {@link #parallelStream()} methods will reflect the
 599      * contents of the collection as of initiation of the terminal stream
 600      * operation.
 601      *
 602      * @implSpec
 603      * The default implementation creates a
 604      * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
 605      * from the collection's {@code Iterator}.  The spliterator inherits the
 606      * <em>fail-fast</em> properties of the collection's iterator.
 607      * <p>
 608      * The created {@code Spliterator} reports {@link Spliterator#SIZED}.
 609      *
 610      * @implNote
 611      * The created {@code Spliterator} additionally reports
 612      * {@link Spliterator#SUBSIZED}.
 613      *
 614      * <p>If a spliterator covers no elements then the reporting of additional
 615      * characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED},
 616      * does not aid clients to control, specialize or simplify computation.
 617      * However, this does enable shared use of an immutable and empty
 618      * spliterator instance (see {@link Spliterators#emptySpliterator()}) for
 619      * empty collections, and enables clients to determine if such a spliterator
 620      * covers no elements.
 621      *
 622      * @return a {@code Spliterator} over the elements in this collection
 623      * @since 1.8
 624      */
 625     @Override
 626     default Spliterator<E> spliterator() {
 627         return Spliterators.spliterator(this, 0);
 628     }
 629 
 630     /**
 631      * Returns a sequential {@code Stream} with this collection as its source.
 632      *
 633      * <p>This method should be overridden when the {@link #spliterator()}
 634      * method cannot return a spliterator that is {@code IMMUTABLE},
 635      * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
 636      * for details.)
 637      *
 638      * @implSpec
 639      * The default implementation creates a sequential {@code Stream} from the
 640      * collection's {@code Spliterator}.
 641      *
 642      * @return a sequential {@code Stream} over the elements in this collection
 643      * @since 1.8
 644      */
 645     default Stream<E> stream() {
 646         return StreamSupport.stream(spliterator(), false);
 647     }
 648 
 649     /**
 650      * Returns a possibly parallel {@code Stream} with this collection as its
 651      * source.  It is allowable for this method to return a sequential stream.
 652      *
 653      * <p>This method should be overridden when the {@link #spliterator()}
 654      * method cannot return a spliterator that is {@code IMMUTABLE},
 655      * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
 656      * for details.)
 657      *
 658      * @implSpec
 659      * The default implementation creates a parallel {@code Stream} from the
 660      * collection's {@code Spliterator}.
 661      *
 662      * @return a possibly parallel {@code Stream} over the elements in this
 663      * collection
 664      * @since 1.8
 665      */
 666     default Stream<E> parallelStream() {
 667         return StreamSupport.stream(spliterator(), true);
 668     }
 669 }
--- EOF ---