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. - * - *
- * Some collection implementations have restrictions on the elements that - * they may contain. For example, some implementations prohibit null elements, + *
Certain methods are specified to be + * optional. 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. + * + *
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 @@ -111,6 +107,77 @@ * methods. Implementations may optionally handle the self-referential scenario, * however most current implementations do not do so. * + *
View collections. + * Most collections contain elements themselves. By contrast, view collections + * 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 Collections#checkedCollection Collections.checkedCollection}, + * {@link Collections#synchronizedCollection Collections.synchronizedCollection}, and + * {@link Collections#unmodifiableCollection Collections.unmodifiableCollection}. + * Other examples of view collections include collections that provide a + * different representation of the same elements, for example, as + * provided by {@link List#subList List.subList}, + * {@link NavigableSet#subSet NavigableSet.subSet}, or + * {@link Map#entrySet 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. + * + *
Unmodifiable collections. + * 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. + * + *
An unmodifiable collection 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 List.subList} should also be unmodifiable. + * + *
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. + * + *
Unmodifiable view collections. + * 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. + * + *
Note that changes to the backing collection might still be possible, + * and if they occur, they are visible through the unmodifiable view. Thus, + * 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. + * *
This interface is a member of the * * Java Collections Framework. --- old/src/java.base/share/classes/java/util/Collections.java 2017-10-30 15:33:20.000000000 -0700 +++ new/src/java.base/share/classes/java/util/Collections.java 2017-10-30 15:33:20.000000000 -0700 @@ -989,9 +989,8 @@ // Unmodifiable Wrappers /** - * Returns an unmodifiable view of the specified collection. This method - * allows modules to provide users with "read-only" access to internal - * collections. Query operations on the returned collection "read through" + * Returns an unmodifiable view of the + * specified collection. Query operations on the returned collection "read through" * to the specified collection, and attempts to modify the returned * collection, whether direct or via its iterator, result in an * {@code UnsupportedOperationException}.
@@ -1102,9 +1101,8 @@ } /** - * Returns an unmodifiable view of the specified set. This method allows - * modules to provide users with "read-only" access to internal sets. - * Query operations on the returned set "read through" to the specified + * Returns an unmodifiable view of the + * specified set. Query operations on the returned set "read through" to the specified * set, and attempts to modify the returned set, whether direct or via its * iterator, result in an {@code UnsupportedOperationException}.
* @@ -1132,9 +1130,8 @@ } /** - * Returns an unmodifiable view of the specified sorted set. This method - * allows modules to provide users with "read-only" access to internal - * sorted sets. Query operations on the returned sorted set "read + * Returns an unmodifiable view of the + * specified sorted set. Query operations on the returned sorted set "read * through" to the specified sorted set. Attempts to modify the returned * sorted set, whether direct, via its iterator, or via its * {@code subSet}, {@code headSet}, or {@code tailSet} views, result in @@ -1180,9 +1177,8 @@ } /** - * Returns an unmodifiable view of the specified navigable set. This method - * allows modules to provide users with "read-only" access to internal - * navigable sets. Query operations on the returned navigable set "read + * Returns an unmodifiable view of the + * specified navigable set. Query operations on the returned navigable set "read * through" to the specified navigable set. Attempts to modify the returned * navigable set, whether direct, via its iterator, or via its * {@code subSet}, {@code headSet}, or {@code tailSet} views, result in @@ -1269,9 +1265,8 @@ } /** - * Returns an unmodifiable view of the specified list. This method allows - * modules to provide users with "read-only" access to internal - * lists. Query operations on the returned list "read through" to the + * Returns an unmodifiable view of the + * specified list. Query operations on the returned list "read through" to the * specified list, and attempts to modify the returned list, whether * direct or via its iterator, result in an * {@code UnsupportedOperationException}.
@@ -1415,9 +1410,8 @@ } /** - * Returns an unmodifiable view of the specified map. This method - * allows modules to provide users with "read-only" access to internal - * maps. Query operations on the returned map "read through" + * Returns an unmodifiable view of the + * specified map. Query operations on the returned map "read through" * to the specified map, and attempts to modify the returned * map, whether direct or via its collection views, result in an * {@code UnsupportedOperationException}.
@@ -1765,9 +1759,8 @@ } /** - * Returns an unmodifiable view of the specified sorted map. This method - * allows modules to provide users with "read-only" access to internal - * sorted maps. Query operations on the returned sorted map "read through" + * Returns an unmodifiable view of the + * specified sorted map. Query operations on the returned sorted map "read through" * to the specified sorted map. Attempts to modify the returned * sorted map, whether direct, via its collection views, or via its * {@code subMap}, {@code headMap}, or {@code tailMap} views, result in @@ -1809,9 +1802,8 @@ } /** - * Returns an unmodifiable view of the specified navigable map. This method - * allows modules to provide users with "read-only" access to internal - * navigable maps. Query operations on the returned navigable map "read + * Returns an unmodifiable view of the + * specified navigable map. Query operations on the returned navigable map "read * through" to the specified navigable map. Attempts to modify the returned * navigable map, whether direct, via its collection views, or via its * {@code subMap}, {@code headMap}, or {@code tailMap} views, result in --- old/src/java.base/share/classes/java/util/List.java 2017-10-30 15:33:22.000000000 -0700 +++ new/src/java.base/share/classes/java/util/List.java 2017-10-30 15:33:21.000000000 -0700 @@ -87,15 +87,16 @@ * Such exceptions are marked as "optional" in the specification for this * interface. * - *
The {@link List#of(Object...) List.of()} static factory methods - * provide a convenient way to create immutable lists. The {@code List} + *
The {@link List#of(Object...) List.of} and + * {@link List#copyOf List.copyOf} static factory methods + * provide a convenient way to create unmodifiable lists. The {@code List} * instances created by these methods have the following characteristics: * *
The {@link Map#of() Map.of()} and - * {@link Map#ofEntries(Map.Entry...) Map.ofEntries()} - * static factory methods provide a convenient way to create immutable maps. + *
The {@link Map#of() Map.of}, + * {@link Map#ofEntries(Map.Entry...) Map.ofEntries}, and + * {@link Map#copyOf Map.copyOf} + * static factory methods provide a convenient way to create unmodifiable maps. * The {@code Map} * instances created by these methods have the following characteristics: * *
The {@link Set#of(Object...) Set.of()} static factory methods - * provide a convenient way to create immutable sets. The {@code Set} + *
The {@link Set#of(Object...) Set.of} and + * {@link Set#copyOf Set.copyOf} static factory methods + * provide a convenient way to create unmodifiable sets. The {@code Set} * instances created by these methods have the following characteristics: * *
This is an {@link Collector.Characteristics#UNORDERED unordered}
+ * Collector.
+ *
+ * @param If the mapped keys contain duplicates (according to
* {@link Object#equals(Object)}), an {@code IllegalStateException} is
* thrown when the collection operation is performed. If the mapped keys
- * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
+ * might have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
* instead.
*
* There are no guarantees on the type, mutability, serializability,
@@ -1411,6 +1463,45 @@
}
/**
+ * Returns a {@code Collector} that accumulates the input elements into an
+ * unmodifiable Map,
+ * whose keys and values are the result of applying the provided
+ * mapping functions to the input elements.
+ *
+ * If the mapped keys contain duplicates (according to
+ * {@link Object#equals(Object)}), an {@code IllegalStateException} is
+ * thrown when the collection operation is performed. If the mapped keys
+ * might have duplicates, use {@link #toUnmodifiableMap(Function, Function, BinaryOperator)}
+ * instead.
+ *
+ * The returned Collector disallows null keys and values. If either mapping function
+ * returns null, {@code NullPointerException} will be thrown.
+ *
+ * @param If the mapped
+ * keys contain duplicates (according to {@link Object#equals(Object)}),
+ * the value mapping function is applied to each equal element, and the
+ * results are merged using the provided merging function.
+ *
+ * The returned Collector disallows null keys and values. If either mapping function
+ * returns null, {@code NullPointerException} will be thrown.
+ *
+ * @param