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

Print this page
rev 6197 : [mq]: collections


  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 import java.io.Serializable;
  28 import java.io.ObjectOutputStream;
  29 import java.io.IOException;
  30 import java.lang.reflect.Array;



  31 
  32 /**
  33  * This class consists exclusively of static methods that operate on or return
  34  * collections.  It contains polymorphic algorithms that operate on
  35  * collections, "wrappers", which return a new collection backed by a
  36  * specified collection, and a few other odds and ends.
  37  *
  38  * <p>The methods of this class all throw a <tt>NullPointerException</tt>
  39  * if the collections or class objects provided to them are null.
  40  *
  41  * <p>The documentation for the polymorphic algorithms contained in this class
  42  * generally includes a brief description of the <i>implementation</i>.  Such
  43  * descriptions should be regarded as <i>implementation notes</i>, rather than
  44  * parts of the <i>specification</i>.  Implementors should feel free to
  45  * substitute other algorithms, so long as the specification itself is adhered
  46  * to.  (For example, the algorithm used by <tt>sort</tt> does not have to be
  47  * a mergesort, but it does have to be <i>stable</i>.)
  48  *
  49  * <p>The "destructive" algorithms contained in this class, that is, the
  50  * algorithms that modify the collection on which they operate, are specified


1090         }
1091         public boolean remove(Object o) {
1092             throw new UnsupportedOperationException();
1093         }
1094 
1095         public boolean containsAll(Collection<?> coll) {
1096             return c.containsAll(coll);
1097         }
1098         public boolean addAll(Collection<? extends E> coll) {
1099             throw new UnsupportedOperationException();
1100         }
1101         public boolean removeAll(Collection<?> coll) {
1102             throw new UnsupportedOperationException();
1103         }
1104         public boolean retainAll(Collection<?> coll) {
1105             throw new UnsupportedOperationException();
1106         }
1107         public void clear() {
1108             throw new UnsupportedOperationException();
1109         }



1110     }
1111 
1112     /**
1113      * Returns an unmodifiable view of the specified set.  This method allows
1114      * modules to provide users with "read-only" access to internal sets.
1115      * Query operations on the returned set "read through" to the specified
1116      * set, and attempts to modify the returned set, whether direct or via its
1117      * iterator, result in an <tt>UnsupportedOperationException</tt>.<p>
1118      *
1119      * The returned set will be serializable if the specified set
1120      * is serializable.
1121      *
1122      * @param  s the set for which an unmodifiable view is to be returned.
1123      * @return an unmodifiable view of the specified set.
1124      */
1125     public static <T> Set<T> unmodifiableSet(Set<? extends T> s) {
1126         return new UnmodifiableSet<>(s);
1127     }
1128 
1129     /**


1220         }
1221 
1222         public boolean equals(Object o) {return o == this || list.equals(o);}
1223         public int hashCode()           {return list.hashCode();}
1224 
1225         public E get(int index) {return list.get(index);}
1226         public E set(int index, E element) {
1227             throw new UnsupportedOperationException();
1228         }
1229         public void add(int index, E element) {
1230             throw new UnsupportedOperationException();
1231         }
1232         public E remove(int index) {
1233             throw new UnsupportedOperationException();
1234         }
1235         public int indexOf(Object o)            {return list.indexOf(o);}
1236         public int lastIndexOf(Object o)        {return list.lastIndexOf(o);}
1237         public boolean addAll(int index, Collection<? extends E> c) {
1238             throw new UnsupportedOperationException();
1239         }






1240         public ListIterator<E> listIterator()   {return listIterator(0);}
1241 
1242         public ListIterator<E> listIterator(final int index) {
1243             return new ListIterator<E>() {
1244                 private final ListIterator<? extends E> i
1245                     = list.listIterator(index);
1246 
1247                 public boolean hasNext()     {return i.hasNext();}
1248                 public E next()              {return i.next();}
1249                 public boolean hasPrevious() {return i.hasPrevious();}
1250                 public E previous()          {return i.previous();}
1251                 public int nextIndex()       {return i.nextIndex();}
1252                 public int previousIndex()   {return i.previousIndex();}
1253 
1254                 public void remove() {
1255                     throw new UnsupportedOperationException();
1256                 }
1257                 public void set(E e) {
1258                     throw new UnsupportedOperationException();
1259                 }


1661             synchronized (mutex) {return c.containsAll(coll);}
1662         }
1663         public boolean addAll(Collection<? extends E> coll) {
1664             synchronized (mutex) {return c.addAll(coll);}
1665         }
1666         public boolean removeAll(Collection<?> coll) {
1667             synchronized (mutex) {return c.removeAll(coll);}
1668         }
1669         public boolean retainAll(Collection<?> coll) {
1670             synchronized (mutex) {return c.retainAll(coll);}
1671         }
1672         public void clear() {
1673             synchronized (mutex) {c.clear();}
1674         }
1675         public String toString() {
1676             synchronized (mutex) {return c.toString();}
1677         }
1678         private void writeObject(ObjectOutputStream s) throws IOException {
1679             synchronized (mutex) {s.defaultWriteObject();}
1680         }






1681     }
1682 
1683     /**
1684      * Returns a synchronized (thread-safe) set backed by the specified
1685      * set.  In order to guarantee serial access, it is critical that
1686      * <strong>all</strong> access to the backing set is accomplished
1687      * through the returned set.<p>
1688      *
1689      * It is imperative that the user manually synchronize on the returned
1690      * set when iterating over it:
1691      * <pre>
1692      *  Set s = Collections.synchronizedSet(new HashSet());
1693      *      ...
1694      *  synchronized (s) {
1695      *      Iterator i = s.iterator(); // Must be in the synchronized block
1696      *      while (i.hasNext())
1697      *          foo(i.next());
1698      *  }
1699      * </pre>
1700      * Failure to follow this advice may result in non-deterministic behavior.


1898         }
1899         public E set(int index, E element) {
1900             synchronized (mutex) {return list.set(index, element);}
1901         }
1902         public void add(int index, E element) {
1903             synchronized (mutex) {list.add(index, element);}
1904         }
1905         public E remove(int index) {
1906             synchronized (mutex) {return list.remove(index);}
1907         }
1908 
1909         public int indexOf(Object o) {
1910             synchronized (mutex) {return list.indexOf(o);}
1911         }
1912         public int lastIndexOf(Object o) {
1913             synchronized (mutex) {return list.lastIndexOf(o);}
1914         }
1915 
1916         public boolean addAll(int index, Collection<? extends E> c) {
1917             synchronized (mutex) {return list.addAll(index, c);}






1918         }
1919 
1920         public ListIterator<E> listIterator() {
1921             return list.listIterator(); // Must be manually synched by user
1922         }
1923 
1924         public ListIterator<E> listIterator(int index) {
1925             return list.listIterator(index); // Must be manually synched by user
1926         }
1927 
1928         public List<E> subList(int fromIndex, int toIndex) {
1929             synchronized (mutex) {
1930                 return new SynchronizedList<>(list.subList(fromIndex, toIndex),
1931                                             mutex);
1932             }
1933         }
1934 
1935         /**
1936          * SynchronizedRandomAccessList instances are serialized as
1937          * SynchronizedList instances to allow them to be deserialized




  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 import java.io.Serializable;
  28 import java.io.ObjectOutputStream;
  29 import java.io.IOException;
  30 import java.lang.reflect.Array;
  31 import java.util.function.Block;
  32 import java.util.function.Predicate;
  33 import java.util.function.UnaryOperator;
  34 
  35 /**
  36  * This class consists exclusively of static methods that operate on or return
  37  * collections.  It contains polymorphic algorithms that operate on
  38  * collections, "wrappers", which return a new collection backed by a
  39  * specified collection, and a few other odds and ends.
  40  *
  41  * <p>The methods of this class all throw a <tt>NullPointerException</tt>
  42  * if the collections or class objects provided to them are null.
  43  *
  44  * <p>The documentation for the polymorphic algorithms contained in this class
  45  * generally includes a brief description of the <i>implementation</i>.  Such
  46  * descriptions should be regarded as <i>implementation notes</i>, rather than
  47  * parts of the <i>specification</i>.  Implementors should feel free to
  48  * substitute other algorithms, so long as the specification itself is adhered
  49  * to.  (For example, the algorithm used by <tt>sort</tt> does not have to be
  50  * a mergesort, but it does have to be <i>stable</i>.)
  51  *
  52  * <p>The "destructive" algorithms contained in this class, that is, the
  53  * algorithms that modify the collection on which they operate, are specified


1093         }
1094         public boolean remove(Object o) {
1095             throw new UnsupportedOperationException();
1096         }
1097 
1098         public boolean containsAll(Collection<?> coll) {
1099             return c.containsAll(coll);
1100         }
1101         public boolean addAll(Collection<? extends E> coll) {
1102             throw new UnsupportedOperationException();
1103         }
1104         public boolean removeAll(Collection<?> coll) {
1105             throw new UnsupportedOperationException();
1106         }
1107         public boolean retainAll(Collection<?> coll) {
1108             throw new UnsupportedOperationException();
1109         }
1110         public void clear() {
1111             throw new UnsupportedOperationException();
1112         }
1113         public boolean removeAll(Predicate<? super E> filter) {
1114             throw new UnsupportedOperationException();
1115         }
1116     }
1117 
1118     /**
1119      * Returns an unmodifiable view of the specified set.  This method allows
1120      * modules to provide users with "read-only" access to internal sets.
1121      * Query operations on the returned set "read through" to the specified
1122      * set, and attempts to modify the returned set, whether direct or via its
1123      * iterator, result in an <tt>UnsupportedOperationException</tt>.<p>
1124      *
1125      * The returned set will be serializable if the specified set
1126      * is serializable.
1127      *
1128      * @param  s the set for which an unmodifiable view is to be returned.
1129      * @return an unmodifiable view of the specified set.
1130      */
1131     public static <T> Set<T> unmodifiableSet(Set<? extends T> s) {
1132         return new UnmodifiableSet<>(s);
1133     }
1134 
1135     /**


1226         }
1227 
1228         public boolean equals(Object o) {return o == this || list.equals(o);}
1229         public int hashCode()           {return list.hashCode();}
1230 
1231         public E get(int index) {return list.get(index);}
1232         public E set(int index, E element) {
1233             throw new UnsupportedOperationException();
1234         }
1235         public void add(int index, E element) {
1236             throw new UnsupportedOperationException();
1237         }
1238         public E remove(int index) {
1239             throw new UnsupportedOperationException();
1240         }
1241         public int indexOf(Object o)            {return list.indexOf(o);}
1242         public int lastIndexOf(Object o)        {return list.lastIndexOf(o);}
1243         public boolean addAll(int index, Collection<? extends E> c) {
1244             throw new UnsupportedOperationException();
1245         }
1246         public void replaceAll(UnaryOperator<E> operator) {
1247             throw new UnsupportedOperationException();
1248         }
1249         public void sort(Comparator<? super E> c) {
1250             throw new UnsupportedOperationException();
1251         }
1252         public ListIterator<E> listIterator()   {return listIterator(0);}
1253 
1254         public ListIterator<E> listIterator(final int index) {
1255             return new ListIterator<E>() {
1256                 private final ListIterator<? extends E> i
1257                     = list.listIterator(index);
1258 
1259                 public boolean hasNext()     {return i.hasNext();}
1260                 public E next()              {return i.next();}
1261                 public boolean hasPrevious() {return i.hasPrevious();}
1262                 public E previous()          {return i.previous();}
1263                 public int nextIndex()       {return i.nextIndex();}
1264                 public int previousIndex()   {return i.previousIndex();}
1265 
1266                 public void remove() {
1267                     throw new UnsupportedOperationException();
1268                 }
1269                 public void set(E e) {
1270                     throw new UnsupportedOperationException();
1271                 }


1673             synchronized (mutex) {return c.containsAll(coll);}
1674         }
1675         public boolean addAll(Collection<? extends E> coll) {
1676             synchronized (mutex) {return c.addAll(coll);}
1677         }
1678         public boolean removeAll(Collection<?> coll) {
1679             synchronized (mutex) {return c.removeAll(coll);}
1680         }
1681         public boolean retainAll(Collection<?> coll) {
1682             synchronized (mutex) {return c.retainAll(coll);}
1683         }
1684         public void clear() {
1685             synchronized (mutex) {c.clear();}
1686         }
1687         public String toString() {
1688             synchronized (mutex) {return c.toString();}
1689         }
1690         private void writeObject(ObjectOutputStream s) throws IOException {
1691             synchronized (mutex) {s.defaultWriteObject();}
1692         }
1693         public void forEach(Block<? super E> block) {
1694             synchronized (mutex) {c.forEach(block);}
1695         }
1696         public boolean removeAll(Predicate<? super E> filter) {
1697             synchronized (mutex) {return c.removeAll(filter);}
1698         }
1699     }
1700 
1701     /**
1702      * Returns a synchronized (thread-safe) set backed by the specified
1703      * set.  In order to guarantee serial access, it is critical that
1704      * <strong>all</strong> access to the backing set is accomplished
1705      * through the returned set.<p>
1706      *
1707      * It is imperative that the user manually synchronize on the returned
1708      * set when iterating over it:
1709      * <pre>
1710      *  Set s = Collections.synchronizedSet(new HashSet());
1711      *      ...
1712      *  synchronized (s) {
1713      *      Iterator i = s.iterator(); // Must be in the synchronized block
1714      *      while (i.hasNext())
1715      *          foo(i.next());
1716      *  }
1717      * </pre>
1718      * Failure to follow this advice may result in non-deterministic behavior.


1916         }
1917         public E set(int index, E element) {
1918             synchronized (mutex) {return list.set(index, element);}
1919         }
1920         public void add(int index, E element) {
1921             synchronized (mutex) {list.add(index, element);}
1922         }
1923         public E remove(int index) {
1924             synchronized (mutex) {return list.remove(index);}
1925         }
1926 
1927         public int indexOf(Object o) {
1928             synchronized (mutex) {return list.indexOf(o);}
1929         }
1930         public int lastIndexOf(Object o) {
1931             synchronized (mutex) {return list.lastIndexOf(o);}
1932         }
1933 
1934         public boolean addAll(int index, Collection<? extends E> c) {
1935             synchronized (mutex) {return list.addAll(index, c);}
1936         }
1937         public void replaceAll(UnaryOperator<E> operator) {
1938             synchronized (mutex) {list.replaceAll(operator);}
1939         }
1940         public void sort(Comparator<? super E> c) {
1941             synchronized (mutex) {list.sort(c);}
1942         }
1943 
1944         public ListIterator<E> listIterator() {
1945             return list.listIterator(); // Must be manually synched by user
1946         }
1947 
1948         public ListIterator<E> listIterator(int index) {
1949             return list.listIterator(index); // Must be manually synched by user
1950         }
1951 
1952         public List<E> subList(int fromIndex, int toIndex) {
1953             synchronized (mutex) {
1954                 return new SynchronizedList<>(list.subList(fromIndex, toIndex),
1955                                             mutex);
1956             }
1957         }
1958 
1959         /**
1960          * SynchronizedRandomAccessList instances are serialized as
1961          * SynchronizedList instances to allow them to be deserialized