src/java.base/share/classes/java/util/Collection.java

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

*** 52,74 ****
   * producing an equivalent collection of the desired implementation type.
   * There is no way to enforce this convention (as interfaces cannot contain
   * constructors) but all of the general-purpose {@code Collection}
   * implementations in the Java platform libraries comply.
   *
!  * <p>The "destructive" methods contained in this interface, that is, the
!  * methods that modify the collection on which they operate, are specified to
!  * throw {@code UnsupportedOperationException} if this collection does not
!  * support the operation.  If this is the case, these methods may, but are not
!  * required to, throw an {@code UnsupportedOperationException} if the
!  * invocation would have no effect on the collection.  For example, invoking
!  * the {@link #addAll(Collection)} method on an unmodifiable collection may,
!  * but is not required to, throw the exception if the collection to be added
!  * is empty.
!  *
!  * <p><a id="optional-restrictions">
!  * Some collection implementations have restrictions on the elements that
!  * they may contain.</a>  For example, some implementations prohibit null elements,
   * and some have restrictions on the types of their elements.  Attempting to
   * add an ineligible element throws an unchecked exception, typically
   * {@code NullPointerException} or {@code ClassCastException}.  Attempting
   * to query the presence of an ineligible element may throw an exception,
   * or it may simply return false; some implementations will exhibit the former
--- 52,70 ----
   * producing an equivalent collection of the desired implementation type.
   * There is no way to enforce this convention (as interfaces cannot contain
   * constructors) but all of the general-purpose {@code Collection}
   * implementations in the Java platform libraries comply.
   *
!  * <p>Certain methods are specified to be
!  * <i>optional</i>. If a collection implementation doesn't implement a
!  * particular operation, it should define the corresponding method to throw
!  * {@code UnsupportedOperationException}. Such methods are marked "optional
!  * operation" in method specifications of the collections interfaces.
!  *
!  * <p><a id="optional-restrictions"></a>Some collection implementations
!  * have restrictions on the elements that they may contain.
!  * For example, some implementations prohibit null elements,
   * and some have restrictions on the types of their elements.  Attempting to
   * add an ineligible element throws an unchecked exception, typically
   * {@code NullPointerException} or {@code ClassCastException}.  Attempting
   * to query the presence of an ineligible element may throw an exception,
   * or it may simply return false; some implementations will exhibit the former
*** 109,118 ****
--- 105,183 ----
   * the collection directly or indirectly contains itself. This includes the
   * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
   * methods. Implementations may optionally handle the self-referential scenario,
   * however most current implementations do not do so.
   *
+  * <p><a id="view"><b>View collections.</b></a>
+  * Most collections contain elements themselves. By contrast, <i>view collections</i>
+  * themselves do not contain elements, but instead rely on a backing collection to
+  * store the actual elements. Operations that are not handled by the view
+  * collection itself are delegated to the backing collection. Examples of
+  * view collections include the wrapper collections returned by methods such as
+  * {@link unmodifiableCollection},
+  * {@link checkedCollection}, and
+  * {@link synchronizedCollection}.
+  * Other examples of view collections include collections that provide a
+  * different representation of the same elements, for example, as
+  * provided by {@link List.subList}, {@link NavigableSet.subSet}, or
+  * {@link Map.entrySet}. Any changes made to the backing collection are
+  * visible in the view collection. Correspondingly, any changes made to
+  * the view collection are written through to the backing collection.
+  * Although they technically aren't collections, instances of
+  * {@link Iterator} and {@link ListIterator} can also allow modifications
+  * to be written through to the backing collection, and in some cases,
+  * modifications to the backing collection will be visible to the Iterator
+  * during iteration.
+  *
+  * <p><a id="unmodifiable"><b>Unmodifiable collections.</b></a>
+  * Certain methods of this interface are considered "destructive" and are called
+  * "mutator" methods in that they modify the group of objects contained within
+  * the collection on which they operate. They can be specified to throw
+  * {@code UnsupportedOperationException} if this collection implementation
+  * does not support the operation. Such methods should (but are not required
+  * to) throw an {@code UnsupportedOperationException} if the invocation would
+  * have no effect on the collection. For example, invoking the
+  * {@link #addAll addAll} method on a collection that does not support
+  * the {@link #add add} operation should throw the exception if
+  * the collection passed as an argument is empty. It is recommended
+  * that such methods always throw the exception unconditionally, as
+  * throwing only in certain cases can lead to programming errors.
+  *
+  * <p>An <i>unmodifiable collection</i> is a collection, all of whose
+  * mutator methods (as defined above) are specified to throw
+  * {@code UnsupportedOperationException}. Such a collection thus cannot be
+  * modified by calling any methods on it. For a collection to be properly
+  * unmodifiable, any view collections derived from it must also be unmodifiable.
+  * For example, if a List is unmodifiable, the List returned by
+  * {@link List.subList} should also be unmodifiable.
+  *
+  * <p>An unmodifiable collection is not necessarily immutable. If the
+  * contained elements are mutable, the entire collection is clearly
+  * mutable, even though it might be unmodifiable. For example, consider
+  * two unmodifiable lists containing mutable elements. The result of calling
+  * {@code list1.equals(list2)} might differ from one call to the next if
+  * the elements had been mutated, even though both lists are unmodifiable.
+  * However, if an unmodifiable collection contains all immutable elements,
+  * it can be considered effectively immutable.
+  *
+  * <p><a id="unmodview"><b>Unmodifiable view collections.</b></a>
+  * An unmodifiable view is a collection that is unmodifiable and that is
+  * a view onto a backing collection. Mutator methods throw
+  * {@code UnsupportedOperationException}, as described above, while
+  * reading and querying methods are delegated to the backing collection.
+  * The effect is to provide read-only access to the backing collection.
+  * This is useful for a component to provide users with read access to
+  * an internal collection, while preventing them from modifying such
+  * collections unexpectedly.
+  *
+  * <p>Note that changes to the backing collection might still be possible,
+  * and if they occur, they are visible through the unmodifiable view. As
+  * above, an unmodifiable view collection is not necessarily immutable.
+  * However, if the backing collection of an unmodifiable view is effectively
+  * immutable, or if the only reference to the backing collection is through
+  * an unmodifiable view, the view can be considered effectively immutable.
+  *
   * <p>This interface is a member of the
   * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
   * Java Collections Framework</a>.
   *
   * @implSpec