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

rev 47476 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: alanb, dholmes, rriggs, scolebourne

*** 987,999 ****
  
  
      // 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"
       * to the specified collection, and attempts to modify the returned
       * collection, whether direct or via its iterator, result in an
       * {@code UnsupportedOperationException}.<p>
       *
       * The returned collection does <i>not</i> pass the hashCode and equals
--- 987,998 ----
  
  
      // Unmodifiable Wrappers
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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}.<p>
       *
       * The returned collection does <i>not</i> pass the hashCode and equals
*** 1100,1112 ****
              return (Stream<E>)c.parallelStream();
          }
      }
  
      /**
!      * 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
       * set, and attempts to modify the returned set, whether direct or via its
       * iterator, result in an {@code UnsupportedOperationException}.<p>
       *
       * The returned set will be serializable if the specified set
       * is serializable.
--- 1099,1110 ----
              return (Stream<E>)c.parallelStream();
          }
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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}.<p>
       *
       * The returned set will be serializable if the specified set
       * is serializable.
*** 1130,1142 ****
          public boolean equals(Object o) {return o == this || c.equals(o);}
          public int hashCode()           {return c.hashCode();}
      }
  
      /**
!      * 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
       * 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
       * an {@code UnsupportedOperationException}.<p>
       *
--- 1128,1139 ----
          public boolean equals(Object o) {return o == this || c.equals(o);}
          public int hashCode()           {return c.hashCode();}
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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
       * an {@code UnsupportedOperationException}.<p>
       *
*** 1178,1190 ****
          public E first()                   {return ss.first();}
          public E last()                    {return ss.last();}
      }
  
      /**
!      * 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
       * 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
       * an {@code UnsupportedOperationException}.<p>
       *
--- 1175,1186 ----
          public E first()                   {return ss.first();}
          public E last()                    {return ss.last();}
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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
       * an {@code UnsupportedOperationException}.<p>
       *
*** 1267,1279 ****
                  ns.tailSet(fromElement, inclusive));
          }
      }
  
      /**
!      * 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
       * specified list, and attempts to modify the returned list, whether
       * direct or via its iterator, result in an
       * {@code UnsupportedOperationException}.<p>
       *
       * The returned list will be serializable if the specified list
--- 1263,1274 ----
                  ns.tailSet(fromElement, inclusive));
          }
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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}.<p>
       *
       * The returned list will be serializable if the specified list
*** 1413,1425 ****
              return new UnmodifiableList<>(list);
          }
      }
  
      /**
!      * 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"
       * to the specified map, and attempts to modify the returned
       * map, whether direct or via its collection views, result in an
       * {@code UnsupportedOperationException}.<p>
       *
       * The returned map will be serializable if the specified map
--- 1408,1419 ----
              return new UnmodifiableList<>(list);
          }
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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}.<p>
       *
       * The returned map will be serializable if the specified map
*** 1763,1775 ****
              }
          }
      }
  
      /**
!      * 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"
       * 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
       * an {@code UnsupportedOperationException}.<p>
       *
--- 1757,1768 ----
              }
          }
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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
       * an {@code UnsupportedOperationException}.<p>
       *
*** 1807,1819 ****
          public K firstKey()                           { return sm.firstKey(); }
          public K lastKey()                             { return sm.lastKey(); }
      }
  
      /**
!      * 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
       * 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
       * an {@code UnsupportedOperationException}.<p>
       *
--- 1800,1811 ----
          public K firstKey()                           { return sm.firstKey(); }
          public K lastKey()                             { return sm.lastKey(); }
      }
  
      /**
!      * Returns an <a href="Collection.html#unmodview">unmodifiable view</a> 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
       * an {@code UnsupportedOperationException}.<p>
       *