/[classpath]/classpath/java/util/Collections.java
ViewVC logotype

Diff of /classpath/java/util/Collections.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.28.2.9 by gnu_andrew, Fri Jan 14 10:24:16 2005 UTC revision 1.28.2.10 by gnu_andrew, Sat Jan 15 17:02:16 2005 UTC
# Line 1  Line 1 
1  /* Collections.java -- Utility class with methods to operate on collections  /* Collections.java -- Utility class with methods to operate on collections
2     Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004 Free Software Foundation, Inc.     Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2005
3       Free Software Foundation, Inc.
4    
5  This file is part of GNU Classpath.  This file is part of GNU Classpath.
6    
# Line 74  public class Collections Line 75  public class Collections
75    /**    /**
76     * Constant used to decide cutoff for when a non-RandomAccess list should     * Constant used to decide cutoff for when a non-RandomAccess list should
77     * be treated as sequential-access. Basically, quadratic behavior is     * be treated as sequential-access. Basically, quadratic behavior is
78     * acceptible for small lists when the overhead is so small in the first     * acceptable for small lists when the overhead is so small in the first
79     * place. I arbitrarily set it to 16, so it may need some tuning.     * place. I arbitrarily set it to 16, so it may need some tuning.
80     */     */
81    private static final int LARGE_LIST_SIZE = 16;    private static final int LARGE_LIST_SIZE = 16;
# Line 87  public class Collections Line 88  public class Collections
88     * and exceeds a large (unspecified) size should be sequential.     * and exceeds a large (unspecified) size should be sequential.
89     *     *
90     * @param l the list to check     * @param l the list to check
91     * @return true if it should be treated as sequential-access     * @return <code>true</code> if it should be treated as sequential-access
92     */     */
93    private static boolean isSequential(List<?> l)    private static boolean isSequential(List<?> l)
94    {    {
# Line 130  public class Collections Line 131  public class Collections
131    
132      /**      /**
133       * The size: always 0!       * The size: always 0!
134         * @return 0.
135       */       */
136      public int size()      public int size()
137      {      {
# Line 138  public class Collections Line 140  public class Collections
140    
141      /**      /**
142       * Returns an iterator that does not iterate.       * Returns an iterator that does not iterate.
143         * @return A non-iterating iterator.
144       */       */
145      // This is really cheating! I think it's perfectly valid, though.      // This is really cheating! I think it's perfectly valid, though.
146      public Iterator<T> iterator()      public Iterator<T> iterator()
# Line 149  public class Collections Line 152  public class Collections
152      // advantage by not allocating unnecessary iterators in AbstractSet.      // advantage by not allocating unnecessary iterators in AbstractSet.
153      /**      /**
154       * The empty set never contains anything.       * The empty set never contains anything.
155         * @param o The object to search for.
156         * @return <code>false</code>.
157       */       */
158      public boolean contains(Object o)      public boolean contains(Object o)
159      {      {
# Line 157  public class Collections Line 162  public class Collections
162    
163      /**      /**
164       * This is true only if the given collection is also empty.       * This is true only if the given collection is also empty.
165         * @param c The collection of objects which are to be compared
166         *          against the members of this set.
167         * @return <code>true</code> if c is empty.
168       */       */
169      public boolean containsAll(Collection<?> c)      public boolean containsAll(Collection<?> c)
170      {      {
# Line 165  public class Collections Line 173  public class Collections
173    
174      /**      /**
175       * Equal only if the other set is empty.       * Equal only if the other set is empty.
176         * @param o The object to compare with this set.
177         * @return <code>true</code> if o is an empty instance of <code>Set</code>.
178       */       */
179      public boolean equals(Object o)      public boolean equals(Object o)
180      {      {
# Line 173  public class Collections Line 183  public class Collections
183    
184      /**      /**
185       * The hashcode is always 0.       * The hashcode is always 0.
186         * @return 0.
187       */       */
188      public int hashCode()      public int hashCode()
189      {      {
# Line 180  public class Collections Line 191  public class Collections
191      }      }
192    
193      /**      /**
194       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
195         * @param o The object to remove.
196         * @return <code>false</code>.
197       */       */
198      public boolean remove(Object o)      public boolean remove(Object o)
199      {      {
# Line 188  public class Collections Line 201  public class Collections
201      }      }
202    
203      /**      /**
204       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
205         * @param c The collection of objects which should
206         *          all be removed from this set.
207         * @return <code>false</code>.
208       */       */
209      public boolean removeAll(Collection<?> c)      public boolean removeAll(Collection<?> c)
210      {      {
# Line 196  public class Collections Line 212  public class Collections
212      }      }
213    
214      /**      /**
215       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
216         * @param c The collection of objects which should
217         *          all be retained within this set.
218         * @return <code>false</code>.
219       */       */
220      public boolean retainAll(Collection<?> c)      public boolean retainAll(Collection<?> c)
221      {      {
# Line 205  public class Collections Line 224  public class Collections
224    
225      /**      /**
226       * The array is always empty.       * The array is always empty.
227         * @return A new array with a size of 0.
228       */       */
229      public Object[] toArray()      public Object[] toArray()
230      {      {
# Line 213  public class Collections Line 233  public class Collections
233    
234      /**      /**
235       * We don't even need to use reflection!       * We don't even need to use reflection!
236         * @param a An existing array, which can be empty.
237         * @return The original array with any existing
238         *         initial element set to null.
239       */       */
240      public <E> E[] toArray(E[] a)      public <E> E[] toArray(E[] a)
241      {      {
# Line 223  public class Collections Line 246  public class Collections
246    
247      /**      /**
248       * The string never changes.       * The string never changes.
249         *
250         * @return the string "[]".
251       */       */
252      public String toString()      public String toString()
253      {      {
# Line 260  public class Collections Line 285  public class Collections
285    
286      /**      /**
287       * The size is always 0.       * The size is always 0.
288         * @return 0.
289       */       */
290      public int size()      public int size()
291      {      {
# Line 267  public class Collections Line 293  public class Collections
293      }      }
294    
295      /**      /**
296       * No matter the index, it is out of bounds.       * No matter the index, it is out of bounds.  This
297         * method never returns, throwing an exception instead.
298         *
299         * @param index The index of the element to retrieve.
300         * @return the object at the specified index.
301         * @throws IndexOutofBoundsException as any given index
302         *         is outside the bounds of an empty array.
303       */       */
304      public T get(int index)      public T get(int index)
305      {      {
# Line 278  public class Collections Line 310  public class Collections
310      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
311      /**      /**
312       * Never contains anything.       * Never contains anything.
313         * @param o The object to search for.
314         * @return <code>false</code>.
315       */       */
316      public boolean contains(Object o)      public boolean contains(Object o)
317      {      {
# Line 286  public class Collections Line 320  public class Collections
320    
321      /**      /**
322       * This is true only if the given collection is also empty.       * This is true only if the given collection is also empty.
323         * @param c The collection of objects, which should be compared
324         *          against the members of this list.
325         * @return <code>true</code> if c is also empty.
326       */       */
327      public boolean containsAll(Collection<?> c)      public boolean containsAll(Collection<?> c)
328      {      {
# Line 293  public class Collections Line 330  public class Collections
330      }      }
331    
332      /**      /**
333       * Equal only if the other set is empty.       * Equal only if the other list is empty.
334         * @param o The object to compare against this list.
335         * @return <code>true</code> if o is also an empty instance of
336         *         <code>List</code>.
337       */       */
338      public boolean equals(Object o)      public boolean equals(Object o)
339      {      {
# Line 302  public class Collections Line 342  public class Collections
342    
343      /**      /**
344       * The hashcode is always 1.       * The hashcode is always 1.
345         * @return 1.
346       */       */
347      public int hashCode()      public int hashCode()
348      {      {
# Line 310  public class Collections Line 351  public class Collections
351    
352      /**      /**
353       * Returns -1.       * Returns -1.
354         * @param o The object to search for.
355         * @return -1.
356       */       */
357      public int indexOf(Object o)      public int indexOf(Object o)
358      {      {
# Line 318  public class Collections Line 361  public class Collections
361    
362      /**      /**
363       * Returns -1.       * Returns -1.
364         * @param o The object to search for.
365         * @return -1.
366       */       */
367      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
368      {      {
# Line 325  public class Collections Line 370  public class Collections
370      }      }
371    
372      /**      /**
373       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
374         * @param o The object to remove.
375         * @return -1.
376       */       */
377      public boolean remove(Object o)      public boolean remove(Object o)
378      {      {
# Line 333  public class Collections Line 380  public class Collections
380      }      }
381    
382      /**      /**
383       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
384         * @param c The collection of objects which should
385         *          all be removed from this list.
386         * @return <code>false</code>.
387       */       */
388      public boolean removeAll(Collection<?> c)      public boolean removeAll(Collection<?> c)
389      {      {
# Line 341  public class Collections Line 391  public class Collections
391      }      }
392    
393      /**      /**
394       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
395         * @param c The collection of objects which should
396         *          all be retained within this list.
397         * @return <code>false</code>.
398       */       */
399      public boolean retainAll(Collection<?> c)      public boolean retainAll(Collection<?> c)
400      {      {
# Line 350  public class Collections Line 403  public class Collections
403    
404      /**      /**
405       * The array is always empty.       * The array is always empty.
406         * @return A new array with a size of 0.
407       */       */
408      public Object[] toArray()      public Object[] toArray()
409      {      {
# Line 358  public class Collections Line 412  public class Collections
412    
413      /**      /**
414       * We don't even need to use reflection!       * We don't even need to use reflection!
415         * @param a An existing array, which can be empty.
416         * @return The original array with any existing
417         *         initial element set to null.
418       */       */
419      public <E> E[] toArray(E[] a)      public <E> E[] toArray(E[] a)
420      {      {
# Line 368  public class Collections Line 425  public class Collections
425    
426      /**      /**
427       * The string never changes.       * The string never changes.
428         *
429         * @return the string "[]".
430       */       */
431      public String toString()      public String toString()
432      {      {
# Line 404  public class Collections Line 463  public class Collections
463    
464      /**      /**
465       * There are no entries.       * There are no entries.
466         * @return The empty set.
467       */       */
468      public Set<Map.Entry<K, V>> entrySet()      public Set<Map.Entry<K, V>> entrySet()
469      {      {
# Line 414  public class Collections Line 474  public class Collections
474      // advantage by not allocating unnecessary iterators in AbstractMap.      // advantage by not allocating unnecessary iterators in AbstractMap.
475      /**      /**
476       * No entries!       * No entries!
477         * @param key The key to search for.
478         * @return <code>false</code>.
479       */       */
480      public boolean containsKey(Object key)      public boolean containsKey(Object key)
481      {      {
# Line 422  public class Collections Line 484  public class Collections
484    
485      /**      /**
486       * No entries!       * No entries!
487         * @param value The value to search for.
488         * @return <code>false</code>.
489       */       */
490      public boolean containsValue(Object value)      public boolean containsValue(Object value)
491      {      {
# Line 430  public class Collections Line 494  public class Collections
494    
495      /**      /**
496       * Equal to all empty maps.       * Equal to all empty maps.
497         * @param o The object o to compare against this map.
498         * @return <code>true</code> if o is also an empty instance of
499         *         <code>Map</code>.
500       */       */
501      public boolean equals(Object o)      public boolean equals(Object o)
502      {      {
# Line 438  public class Collections Line 505  public class Collections
505    
506      /**      /**
507       * No mappings, so this returns null.       * No mappings, so this returns null.
508         * @param o The key of the object to retrieve.
509         * @return null.
510       */       */
511      public V get(Object o)      public V get(Object o)
512      {      {
# Line 446  public class Collections Line 515  public class Collections
515    
516      /**      /**
517       * The hashcode is always 0.       * The hashcode is always 0.
518         * @return 0.
519       */       */
520      public int hashCode()      public int hashCode()
521      {      {
# Line 454  public class Collections Line 524  public class Collections
524    
525      /**      /**
526       * No entries.       * No entries.
527         * @return The empty set.
528       */       */
529      public Set<K> keySet()      public Set<K> keySet()
530      {      {
# Line 462  public class Collections Line 533  public class Collections
533    
534      /**      /**
535       * Remove always succeeds, with null result.       * Remove always succeeds, with null result.
536         * @param o The key of the mapping to remove.
537         * @return null, as there is never a mapping for o.
538       */       */
539      public V remove(Object o)      public V remove(Object o)
540      {      {
# Line 470  public class Collections Line 543  public class Collections
543    
544      /**      /**
545       * Size is always 0.       * Size is always 0.
546         * @return 0.
547       */       */
548      public int size()      public int size()
549      {      {
# Line 479  public class Collections Line 553  public class Collections
553      /**      /**
554       * No entries. Technically, EMPTY_SET, while more specific than a general       * No entries. Technically, EMPTY_SET, while more specific than a general
555       * Collection, will work. Besides, that's what the JDK uses!       * Collection, will work. Besides, that's what the JDK uses!
556         * @return The empty set.
557       */       */
558      public Collection<V> values()      public Collection<V> values()
559      {      {
# Line 487  public class Collections Line 562  public class Collections
562    
563      /**      /**
564       * The string never changes.       * The string never changes.
565         *
566         * @return the string "[]".
567       */       */
568      public String toString()      public String toString()
569      {      {
# Line 665  public class Collections Line 742  public class Collections
742      final Iterator<T> i = c.iterator();      final Iterator<T> i = c.iterator();
743      return new Enumeration<T>()      return new Enumeration<T>()
744      {      {
745          /**
746           * Returns <code>true</code> if there are more elements to
747           * be enumerated.
748           *
749           * @return The result of <code>hasNext()</code>
750           *         called on the underlying iterator.
751           */
752        public final boolean hasMoreElements()        public final boolean hasMoreElements()
753        {        {
754          return i.hasNext();          return i.hasNext();
755        }        }
756    
757          /**
758           * Returns the next element to be enumerated.
759           *
760           * @return The result of <code>next()</code>
761           *         called on the underlying iterator.
762           */
763        public final T nextElement()        public final T nextElement()
764        {        {
765          return i.next();          return i.next();
# Line 912  public class Collections Line 1003  public class Collections
1003    
1004      /**      /**
1005       * The size is fixed.       * The size is fixed.
1006         * @return The size of the list.
1007       */       */
1008      public int size()      public int size()
1009      {      {
# Line 920  public class Collections Line 1012  public class Collections
1012    
1013      /**      /**
1014       * The same element is returned.       * The same element is returned.
1015         * @param index The index of the element to be returned (irrelevant
1016         *        as the list contains only copies of <code>element</code>).
1017         * @return The element used by this list.
1018       */       */
1019      public T get(int index)      public T get(int index)
1020      {      {
# Line 932  public class Collections Line 1027  public class Collections
1027      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
1028      /**      /**
1029       * This list only contains one element.       * This list only contains one element.
1030         * @param o The object to search for.
1031         * @return <code>true</code> if o is the element used by this list.
1032       */       */
1033      public boolean contains(Object o)      public boolean contains(Object o)
1034      {      {
# Line 940  public class Collections Line 1037  public class Collections
1037    
1038      /**      /**
1039       * The index is either 0 or -1.       * The index is either 0 or -1.
1040         * @param o The object to find the index of.
1041         * @return 0 if <code>o == element</code>, -1 if not.
1042       */       */
1043      public int indexOf(Object o)      public int indexOf(Object o)
1044      {      {
# Line 948  public class Collections Line 1047  public class Collections
1047    
1048      /**      /**
1049       * The index is either n-1 or -1.       * The index is either n-1 or -1.
1050         * @param o The object to find the last index of.
1051         * @return The last index in the list if <code>o == element</code>,
1052         *         -1 if not.
1053       */       */
1054      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
1055      {      {
# Line 956  public class Collections Line 1058  public class Collections
1058    
1059      /**      /**
1060       * A subList is just another CopiesList.       * A subList is just another CopiesList.
1061         * @param from The starting bound of the sublist.
1062         * @param to The ending bound of the sublist.
1063         * @return A list of copies containing <code>from - to</code>
1064         *         elements, all of which are equal to the element
1065         *         used by this list.
1066       */       */
1067      public List<T> subList(int from, int to)      public List<T> subList(int from, int to)
1068      {      {
# Line 966  public class Collections Line 1073  public class Collections
1073    
1074      /**      /**
1075       * The array is easy.       * The array is easy.
1076         * @return An array of size n filled with copies of
1077         *         the element used by this list.
1078       */       */
1079      public Object[] toArray()      public Object[] toArray()
1080      {      {
# Line 976  public class Collections Line 1085  public class Collections
1085    
1086      /**      /**
1087       * The string is easy to generate.       * The string is easy to generate.
1088         * @return A string representation of the list.
1089       */       */
1090      public String toString()      public String toString()
1091      {      {
# Line 995  public class Collections Line 1105  public class Collections
1105     * @param list the list to iterate over     * @param list the list to iterate over
1106     * @param oldval the element to replace     * @param oldval the element to replace
1107     * @param newval the new value for the element     * @param newval the new value for the element
1108     * @return true if a replacement occurred     * @return <code>true</code> if a replacement occurred.
1109     * @throws UnsupportedOperationException if the list iterator does not allow     * @throws UnsupportedOperationException if the list iterator does not allow
1110     *         for the set operation     *         for the set operation
1111     * @throws ClassCastException newval is of a type which cannot be added     * @throws ClassCastException if newval is of a type which cannot be added
1112     *         to the list     *         to the list
1113     * @throws IllegalArgumentException some other aspect of newval stops     * @throws IllegalArgumentException if some other aspect of newval stops
1114     *         it being added to the list     *         it being added to the list
1115     * @since 1.4     * @since 1.4
1116     */     */
# Line 1059  public class Collections Line 1169  public class Collections
1169    /**    /**
1170     * The object for {@link #reverseOrder()}.     * The object for {@link #reverseOrder()}.
1171     */     */
1172    static private final ReverseComparator rcInstance = new ReverseComparator();    private static final ReverseComparator rcInstance = new ReverseComparator();
1173    
1174    /**    /**
1175     * The implementation of {@link #reverseOrder()}. This class name     * The implementation of {@link #reverseOrder()}. This class name
# Line 1073  public class Collections Line 1183  public class Collections
1183      /**      /**
1184       * Compatible with JDK 1.4.       * Compatible with JDK 1.4.
1185       */       */
1186      static private final long serialVersionUID = 7207038068494060240L;      private static final long serialVersionUID = 7207038068494060240L;
1187    
1188      /**      /**
1189       * A private constructor adds overhead.       * A private constructor adds overhead.
# Line 1311  public class Collections Line 1421  public class Collections
1421    
1422      /**      /**
1423       * The size: always 1!       * The size: always 1!
1424         * @return 1.
1425       */       */
1426      public int size()      public int size()
1427      {      {
# Line 1324  public class Collections Line 1435  public class Collections
1435      {      {
1436        return new Iterator<T>()        return new Iterator<T>()
1437        {        {
1438            /**
1439             * Flag to indicate whether or not the element has
1440             * been retrieved.
1441             */
1442          private boolean hasNext = true;          private boolean hasNext = true;
1443    
1444            /**
1445             * Returns <code>true</code> if elements still remain to be
1446             * iterated through.
1447             *
1448             * @return <code>true</code> if the element has not yet been returned.
1449             */
1450          public boolean hasNext()          public boolean hasNext()
1451          {          {
1452            return hasNext;            return hasNext;
1453          }          }
1454    
1455            /**
1456             * Returns the element.
1457             *
1458             * @return The element used by this singleton.
1459             * @throws NoSuchElementException if the object
1460             *         has already been retrieved.
1461             */
1462          public T next()          public T next()
1463          {          {
1464            if (hasNext)            if (hasNext)
# Line 1342  public class Collections Line 1470  public class Collections
1470              throw new NoSuchElementException();              throw new NoSuchElementException();
1471          }          }
1472    
1473            /**
1474             * Removes the element from the singleton.
1475             * As this set is immutable, this will always
1476             * throw an exception.
1477             *
1478             * @throws UnsupportedOperationException as the
1479             *         singleton set doesn't support
1480             *         <code>remove()</code>.
1481             */
1482          public void remove()          public void remove()
1483          {          {
1484            throw new UnsupportedOperationException();            throw new UnsupportedOperationException();
# Line 1353  public class Collections Line 1490  public class Collections
1490      // advantage by not allocating unnecessary iterators in AbstractSet.      // advantage by not allocating unnecessary iterators in AbstractSet.
1491      /**      /**
1492       * The set only contains one element.       * The set only contains one element.
1493         *
1494         * @param o The object to search for.
1495         * @return <code>true</code> if o == the element of the singleton.
1496       */       */
1497      public boolean contains(Object o)      public boolean contains(Object o)
1498      {      {
# Line 1361  public class Collections Line 1501  public class Collections
1501    
1502      /**      /**
1503       * This is true if the other collection only contains the element.       * This is true if the other collection only contains the element.
1504         *
1505         * @param c A collection to compare against this singleton.
1506         * @return <code>true</code> if c only contains either no elements or
1507         *         elements equal to the element in this singleton.
1508       */       */
1509      public boolean containsAll(Collection<?> c)      public boolean containsAll(Collection<?> c)
1510      {      {
# Line 1374  public class Collections Line 1518  public class Collections
1518    
1519      /**      /**
1520       * The hash is just that of the element.       * The hash is just that of the element.
1521         *
1522         * @return The hashcode of the element.
1523       */       */
1524      public int hashCode()      public int hashCode()
1525      {      {
# Line 1382  public class Collections Line 1528  public class Collections
1528    
1529      /**      /**
1530       * Returning an array is simple.       * Returning an array is simple.
1531         *
1532         * @return An array containing the element.
1533       */       */
1534      public Object[] toArray()      public Object[] toArray()
1535      {      {
# Line 1390  public class Collections Line 1538  public class Collections
1538    
1539      /**      /**
1540       * Obvious string.       * Obvious string.
1541         *
1542         * @return The string surrounded by enclosing
1543         *         square brackets.
1544       */       */
1545      public String toString()      public String toString()
1546      {      {
# Line 1443  public class Collections Line 1594  public class Collections
1594    
1595      /**      /**
1596       * The size: always 1!       * The size: always 1!
1597         * @return 1.
1598       */       */
1599      public int size()      public int size()
1600      {      {
# Line 1451  public class Collections Line 1603  public class Collections
1603    
1604      /**      /**
1605       * Only index 0 is valid.       * Only index 0 is valid.
1606         * @param index The index of the element
1607         *        to retrieve.
1608         * @return The singleton's element if the
1609         *         index is 0.
1610         * @throws IndexOutOfBoundsException if
1611         *         index is not 0.
1612       */       */
1613      public T get(int index)      public T get(int index)
1614      {      {
# Line 1463  public class Collections Line 1621  public class Collections
1621      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
1622      /**      /**
1623       * The set only contains one element.       * The set only contains one element.
1624         *
1625         * @param o The object to search for.
1626         * @return <code>true</code> if o == the singleton element.
1627       */       */
1628      public boolean contains(Object o)      public boolean contains(Object o)
1629      {      {
# Line 1471  public class Collections Line 1632  public class Collections
1632    
1633      /**      /**
1634       * This is true if the other collection only contains the element.       * This is true if the other collection only contains the element.
1635         *
1636         * @param c A collection to compare against this singleton.
1637         * @return <code>true</code> if c only contains either no elements or
1638         *         elements equal to the element in this singleton.
1639       */       */
1640      public boolean containsAll(Collection<?> c)      public boolean containsAll(Collection<?> c)
1641      {      {
# Line 1484  public class Collections Line 1649  public class Collections
1649    
1650      /**      /**
1651       * Speed up the hashcode computation.       * Speed up the hashcode computation.
1652         *
1653         * @return The hashcode of the list, based
1654         *         on the hashcode of the singleton element.
1655       */       */
1656      public int hashCode()      public int hashCode()
1657      {      {
# Line 1492  public class Collections Line 1660  public class Collections
1660    
1661      /**      /**
1662       * Either the list has it or not.       * Either the list has it or not.
1663         *
1664         * @param o The object to find the first index of.
1665         * @return 0 if o is the singleton element, -1 if not.
1666       */       */
1667      public int indexOf(Object o)      public int indexOf(Object o)
1668      {      {
# Line 1500  public class Collections Line 1671  public class Collections
1671    
1672      /**      /**
1673       * Either the list has it or not.       * Either the list has it or not.
1674         *
1675         * @param o The object to find the last index of.
1676         * @return 0 if o is the singleton element, -1 if not.
1677       */       */
1678      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
1679      {      {
# Line 1508  public class Collections Line 1682  public class Collections
1682    
1683      /**      /**
1684       * Sublists are limited in scope.       * Sublists are limited in scope.
1685         *
1686         * @param from The starting bound for the sublist.
1687         * @param to The ending bound for the sublist.
1688         * @return Either an empty list if both bounds are
1689         *         0 or 1, or this list if the bounds are 0 and 1.
1690         * @throws IllegalArgumentException if <code>from > to</code>
1691         * @throws IndexOutOfBoundsException if either bound is greater
1692         *         than 1.
1693       */       */
1694      public List<T> subList(int from, int to)      public List<T> subList(int from, int to)
1695      {      {
# Line 1522  public class Collections Line 1704  public class Collections
1704    
1705      /**      /**
1706       * Returning an array is simple.       * Returning an array is simple.
1707         *
1708         * @return An array containing the element.
1709       */       */
1710      public Object[] toArray()      public Object[] toArray()
1711      {      {
# Line 1530  public class Collections Line 1714  public class Collections
1714    
1715      /**      /**
1716       * Obvious string.       * Obvious string.
1717         *
1718         * @return The string surrounded by enclosing
1719         *         square brackets.
1720       */       */
1721      public String toString()      public String toString()
1722      {      {
# Line 1596  public class Collections Line 1783  public class Collections
1783    
1784      /**      /**
1785       * There is a single immutable entry.       * There is a single immutable entry.
1786         *
1787         * @return A singleton containing the map entry.
1788       */       */
1789      public Set<Map.Entry<K, V>> entrySet()      public Set<Map.Entry<K, V>> entrySet()
1790      {      {
1791        if (entries == null)        if (entries == null)
1792          {          {
1793            Map.Entry<K,V> entry = new AbstractMap.BasicMapEntry<K, V>(k, v)            Map.Entry<K,V> entry = new AbstractMap.BasicMapEntry<K, V>(k, v)
1794              {
1795                /**
1796                 * Sets the value of the map entry to the supplied value.
1797                 * An exception is always thrown, as the map is immutable.
1798                 *
1799                 * @param o The new value.
1800                 * @return The old value.
1801                 * @throws UnsupportedOperationException as setting the value
1802                 *         is not supported.
1803                 */
1804                public V setValue(V o)
1805              {              {
1806                public V setValue(V o)                throw new UnsupportedOperationException();
1807                {              }
1808                  throw new UnsupportedOperationException();            };
               }  
             };  
1809            entries = singleton(entry);            entries = singleton(entry);
1810          }          }
1811        return entries;        return entries;
# Line 1617  public class Collections Line 1815  public class Collections
1815      // advantage by not allocating unnecessary iterators in AbstractMap.      // advantage by not allocating unnecessary iterators in AbstractMap.
1816      /**      /**
1817       * Single entry.       * Single entry.
1818         *
1819         * @param key The key to look for.
1820         * @return <code>true</code> if the key is the same as the one used by
1821         *         this map.
1822       */       */
1823      public boolean containsKey(Object key)      public boolean containsKey(Object key)
1824      {      {
# Line 1625  public class Collections Line 1827  public class Collections
1827    
1828      /**      /**
1829       * Single entry.       * Single entry.
1830         *
1831         * @param value The value to look for.
1832         * @return <code>true</code> if the value is the same as the one used by
1833         *         this map.
1834       */       */
1835      public boolean containsValue(Object value)      public boolean containsValue(Object value)
1836      {      {
# Line 1633  public class Collections Line 1839  public class Collections
1839    
1840      /**      /**
1841       * Single entry.       * Single entry.
1842         *
1843         * @param key The key of the value to be retrieved.
1844         * @return The singleton value if the key is the same as the
1845         *         singleton key, null otherwise.
1846       */       */
1847      public V get(Object key)      public V get(Object key)
1848      {      {
# Line 1641  public class Collections Line 1851  public class Collections
1851    
1852      /**      /**
1853       * Calculate the hashcode directly.       * Calculate the hashcode directly.
1854         *
1855         * @return The hashcode computed from the singleton key
1856         *         and the singleton value.
1857       */       */
1858      public int hashCode()      public int hashCode()
1859      {      {
# Line 1649  public class Collections Line 1862  public class Collections
1862    
1863      /**      /**
1864       * Return the keyset.       * Return the keyset.
1865         *
1866         * @return A singleton containing the key.
1867       */       */
1868      public Set<K> keySet()      public Set<K> keySet()
1869      {      {
# Line 1659  public class Collections Line 1874  public class Collections
1874    
1875      /**      /**
1876       * The size: always 1!       * The size: always 1!
1877         *
1878         * @return 1.
1879       */       */
1880      public int size()      public int size()
1881      {      {
# Line 1668  public class Collections Line 1885  public class Collections
1885      /**      /**
1886       * Return the values. Technically, a singleton, while more specific than       * Return the values. Technically, a singleton, while more specific than
1887       * a general Collection, will work. Besides, that's what the JDK uses!       * a general Collection, will work. Besides, that's what the JDK uses!
1888         *
1889         * @return A singleton containing the value.
1890       */       */
1891      public Collection<V> values()      public Collection<V> values()
1892      {      {
# Line 1678  public class Collections Line 1897  public class Collections
1897    
1898      /**      /**
1899       * Obvious string.       * Obvious string.
1900         *
1901         * @return A string containing the string representations of the key
1902         *         and its associated value.
1903       */       */
1904      public String toString()      public String toString()
1905      {      {
# Line 1839  public class Collections Line 2061  public class Collections
2061        mutex = sync;        mutex = sync;
2062      }      }
2063    
2064        /**
2065         * Adds the object to the underlying collection, first
2066         * obtaining a lock on the mutex.
2067         *
2068         * @param o The object to add.
2069         * @return <code>true</code> if the collection was modified as a result
2070         *         of this action.
2071         * @throws UnsupportedOperationException if this collection does not
2072         *         support the add operation.
2073         * @throws ClassCastException if o cannot be added to this collection due
2074         *         to its type.
2075         * @throws NullPointerException if o is null and this collection doesn't
2076         *         support the addition of null values.
2077         * @throws IllegalArgumentException if o cannot be added to this
2078         *         collection for some other reason.
2079         */
2080      public boolean add(T o)      public boolean add(T o)
2081      {      {
2082        synchronized (mutex)        synchronized (mutex)
# Line 1847  public class Collections Line 2085  public class Collections
2085          }          }
2086      }      }
2087    
2088        /**
2089         * Adds the objects in col to the underlying collection, first
2090         * obtaining a lock on the mutex.
2091         *
2092         * @param col The collection to take the new objects from.
2093         * @return <code>true</code> if the collection was modified as a result
2094         *          of this action.
2095         * @throws UnsupportedOperationException if this collection does not
2096         *         support the addAll operation.
2097         * @throws ClassCastException if some element of col cannot be added to this
2098         *         collection due to its type.
2099         * @throws NullPointerException if some element of col is null and this
2100         *         collection does not support the addition of null values.
2101         * @throws NullPointerException if col itself is null.
2102         * @throws IllegalArgumentException if some element of col cannot be added
2103         *         to this collection for some other reason.
2104         */
2105      public boolean addAll(Collection<? extends T> col)      public boolean addAll(Collection<? extends T> col)
2106      {      {
2107        synchronized (mutex)        synchronized (mutex)
# Line 1855  public class Collections Line 2110  public class Collections
2110          }          }
2111      }      }
2112    
2113        /**
2114         * Removes all objects from the underlying collection,
2115         * first obtaining a lock on the mutex.
2116         *
2117         * @throws UnsupportedOperationException if this collection does not
2118         *         support the clear operation.
2119         */
2120      public void clear()      public void clear()
2121      {      {
2122        synchronized (mutex)        synchronized (mutex)
# Line 1863  public class Collections Line 2125  public class Collections
2125          }          }
2126      }      }
2127    
2128        /**
2129         * Checks for the existence of o within the underlying
2130         * collection, first obtaining a lock on the mutex.
2131         *
2132         * @param o the element to look for.
2133         * @return <code>true</code> if this collection contains at least one
2134         *         element e such that <code>o == null ? e == null : o.equals(e)</code>.
2135         * @throws ClassCastException if the type of o is not a valid type for this
2136         *         collection.
2137         * @throws NullPointerException if o is null and this collection doesn't
2138         *         support null values.
2139         */
2140      public boolean contains(Object o)      public boolean contains(Object o)
2141      {      {
2142        synchronized (mutex)        synchronized (mutex)
# Line 1871  public class Collections Line 2145  public class Collections
2145          }          }
2146      }      }
2147    
2148        /**
2149         * Checks for the existence of each object in cl
2150         * within the underlying collection, first obtaining
2151         * a lock on the mutex.
2152         *
2153         * @param cl the collection to test for.
2154         * @return <code>true</code> if for every element o in c, contains(o)
2155         *         would return <code>true</code>.
2156         * @throws ClassCastException if the type of any element in cl is not a valid
2157         *         type for this collection.
2158         * @throws NullPointerException if some element of cl is null and this
2159         *         collection does not support null values.
2160         * @throws NullPointerException if cl itself is null.
2161         */
2162      public boolean containsAll(Collection<?> c1)      public boolean containsAll(Collection<?> c1)
2163      {      {
2164        synchronized (mutex)        synchronized (mutex)
# Line 1879  public class Collections Line 2167  public class Collections
2167          }          }
2168      }      }
2169    
2170        /**
2171         * Returns <code>true</code> if there are no objects in the underlying
2172         * collection.  A lock on the mutex is obtained before the
2173         * check is performed.
2174         *
2175         * @return <code>true</code> if this collection contains no elements.
2176         */
2177      public boolean isEmpty()      public boolean isEmpty()
2178      {      {
2179        synchronized (mutex)        synchronized (mutex)
# Line 1887  public class Collections Line 2182  public class Collections
2182          }          }
2183      }      }
2184    
2185        /**
2186         * Returns a synchronized iterator wrapper around the underlying
2187         * collection's iterator.  A lock on the mutex is obtained before
2188         * retrieving the collection's iterator.
2189         *
2190         * @return An iterator over the elements in the underlying collection,
2191         *         which returns each element in any order.
2192         */
2193      public Iterator<T> iterator()      public Iterator<T> iterator()
2194      {      {
2195        synchronized (mutex)        synchronized (mutex)
# Line 1895  public class Collections Line 2198  public class Collections
2198          }          }
2199      }      }
2200    
2201        /**
2202         * Removes the specified object from the underlying collection,
2203         * first obtaining a lock on the mutex.
2204         *
2205         * @param o The object to remove.
2206         * @return <code>true</code> if the collection changed as a result of this call, that is,
2207         *         if the collection contained at least one occurrence of o.
2208         * @throws UnsupportedOperationException if this collection does not
2209         *         support the remove operation.
2210         * @throws ClassCastException if the type of o is not a valid type
2211         *         for this collection.
2212         * @throws NullPointerException if o is null and the collection doesn't
2213         *         support null values.
2214         */
2215      public boolean remove(Object o)      public boolean remove(Object o)
2216      {      {
2217        synchronized (mutex)        synchronized (mutex)
# Line 1903  public class Collections Line 2220  public class Collections
2220          }          }
2221      }      }
2222    
2223        /**
2224         * Removes all elements, e, of the underlying
2225         * collection for which <code>col.contains(e)</code>
2226         * returns <code>true</code>.  A lock on the mutex is obtained
2227         * before the operation proceeds.
2228         *
2229         * @param col The collection of objects to be removed.
2230         * @return <code>true</code> if this collection was modified as a result of this call.
2231         * @throws UnsupportedOperationException if this collection does not
2232         *   support the removeAll operation.
2233         * @throws ClassCastException if the type of any element in c is not a valid
2234         *   type for this collection.
2235         * @throws NullPointerException if some element of c is null and this
2236         *   collection does not support removing null values.
2237         * @throws NullPointerException if c itself is null.
2238         */
2239      public boolean removeAll(Collection<?> col)      public boolean removeAll(Collection<?> col)
2240      {      {
2241        synchronized (mutex)        synchronized (mutex)
# Line 1911  public class Collections Line 2244  public class Collections
2244          }          }
2245      }      }
2246    
2247        /**
2248         * Retains all elements, e, of the underlying
2249         * collection for which <code>col.contains(e)</code>
2250         * returns <code>true</code>.  That is, every element that doesn't
2251         * exist in col is removed.  A lock on the mutex is obtained
2252         * before the operation proceeds.
2253         *
2254         * @param col The collection of objects to be removed.
2255         * @return <code>true</code> if this collection was modified as a result of this call.
2256         * @throws UnsupportedOperationException if this collection does not
2257         *   support the removeAll operation.
2258         * @throws ClassCastException if the type of any element in c is not a valid
2259         *   type for this collection.
2260         * @throws NullPointerException if some element of c is null and this
2261         *   collection does not support removing null values.
2262         * @throws NullPointerException if c itself is null.
2263         */
2264      public boolean retainAll(Collection<?> col)      public boolean retainAll(Collection<?> col)
2265      {      {
2266        synchronized (mutex)        synchronized (mutex)
# Line 1919  public class Collections Line 2269  public class Collections
2269          }          }
2270      }      }
2271    
2272        /**
2273         * Retrieves the size of the underlying collection.
2274         * A lock on the mutex is obtained before the collection
2275         * is accessed.
2276         *
2277         * @return The size of the collection.
2278         */
2279      public int size()      public int size()
2280      {      {
2281        synchronized (mutex)        synchronized (mutex)
# Line 1927  public class Collections Line 2284  public class Collections
2284          }          }
2285      }      }
2286    
2287        /**
2288         * Returns an array containing each object within the underlying
2289         * collection.  A lock is obtained on the mutex before the collection
2290         * is accessed.
2291         *
2292         * @return An array of objects, matching the collection in size.  The
2293         *         elements occur in any order.
2294         */
2295      public Object[] toArray()      public Object[] toArray()
2296      {      {
2297        synchronized (mutex)        synchronized (mutex)
# Line 1935  public class Collections Line 2300  public class Collections
2300          }          }
2301      }      }
2302    
2303        /**
2304         * Copies the elements in the underlying collection to the supplied
2305         * array.  If <code>a.length < size()</code>, a new array of the
2306         * same run-time type is created, with a size equal to that of
2307         * the collection.  If <code>a.length > size()</code>, then the
2308         * elements from 0 to <code>size() - 1</code> contain the elements
2309         * from this collection.  The following element is set to null
2310         * to indicate the end of the collection objects.  However, this
2311         * only makes a difference if null is not a permitted value within
2312         * the collection.
2313         * Before the copying takes place, a lock is obtained on the mutex.
2314         *
2315         * @param a An array to copy elements to.
2316         * @return An array containing the elements of the underlying collection.
2317         * @throws ArrayStoreException if the type of any element of the
2318         *         collection is not a subtype of the element type of a.
2319         */
2320      public <T> T[] toArray(T[] a)      public <T> T[] toArray(T[] a)
2321      {      {
2322        synchronized (mutex)        synchronized (mutex)
# Line 1943  public class Collections Line 2325  public class Collections
2325          }          }
2326      }      }
2327    
2328        /**
2329         * Returns a string representation of the underlying collection.
2330         * A lock is obtained on the mutex before the string is created.
2331         *
2332         * @return A string representation of the collection.
2333         */
2334      public String toString()      public String toString()
2335      {      {
2336        synchronized (mutex)        synchronized (mutex)
# Line 1982  public class Collections Line 2370  public class Collections
2370        mutex = sync;        mutex = sync;
2371      }      }
2372    
2373        /**
2374         * Retrieves the next object in the underlying collection.
2375         * A lock is obtained on the mutex before the collection is accessed.
2376         *
2377         * @return The next object in the collection.
2378         * @throws NoSuchElementException if there are no more elements
2379         */
2380      public T next()      public T next()
2381      {      {
2382        synchronized (mutex)        synchronized (mutex)
# Line 1990  public class Collections Line 2385  public class Collections
2385          }          }
2386      }      }
2387    
2388        /**
2389         * Returns <code>true</code> if objects can still be retrieved from the iterator
2390         * using <code>next()</code>.  A lock is obtained on the mutex before
2391         * the collection is accessed.
2392         *
2393         * @return <code>true</code> if at least one element is still to be returned by
2394         *         <code>next()</code>.
2395         */
2396      public boolean hasNext()      public boolean hasNext()
2397      {      {
2398        synchronized (mutex)        synchronized (mutex)
# Line 1998  public class Collections Line 2401  public class Collections
2401          }          }
2402      }      }
2403    
2404        /**
2405         * Removes the object that was last returned by <code>next()</code>
2406         * from the underlying collection.  Only one call to this method is
2407         * allowed per call to the <code>next()</code> method, and it does
2408         * not affect the value that will be returned by <code>next()</code>.
2409         * Thus, if element n was retrieved from the collection by
2410         * <code>next()</code>, it is this element that gets removed.
2411         * Regardless of whether this takes place or not, element n+1 is
2412         * still returned on the subsequent <code>next()</code> call.
2413         *
2414         * @throws IllegalStateException if next has not yet been called or remove
2415         *         has already been called since the last call to next.
2416         * @throws UnsupportedOperationException if this Iterator does not support
2417         *         the remove operation.
2418         */
2419      public void remove()      public void remove()
2420      {      {
2421        synchronized (mutex)        synchronized (mutex)
# Line 2085  public class Collections Line 2503  public class Collections
2503        list = l;        list = l;
2504      }      }
2505    
2506      /**
2507       * Insert an element into the underlying list at a given position (optional
2508       * operation).  This shifts all existing elements from that position to the
2509       * end one index to the right. This version of add has no return, since it is
2510       * assumed to always succeed if there is no exception.  Before the
2511       * addition takes place, a lock is obtained on the mutex.
2512       *
2513       * @param index the location to insert the item
2514       * @param o the object to insert
2515       * @throws UnsupportedOperationException if this list does not support the
2516       *         add operation
2517       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
2518       * @throws ClassCastException if o cannot be added to this list due to its
2519       *         type
2520       * @throws IllegalArgumentException if o cannot be added to this list for
2521       *         some other reason
2522       * @throws NullPointerException if o is null and this list doesn't support
2523       *         the addition of null values.
2524       */
2525      public void add(int index, T o)      public void add(int index, T o)
2526      {      {
2527        synchronized (mutex)        synchronized (mutex)
# Line 2093  public class Collections Line 2530  public class Collections
2530          }          }
2531      }      }
2532    
2533      /**
2534       * Add an element to the end of the underlying list (optional operation).
2535       * If the list imposes restraints on what can be inserted, such as no null
2536       * elements, this should be documented.  A lock is obtained on the mutex before
2537       * any of the elements are added.
2538       *
2539       * @param o the object to add
2540       * @return <code>true</code>, as defined by Collection for a modified list
2541       * @throws UnsupportedOperationException if this list does not support the
2542       *         add operation
2543       * @throws ClassCastException if o cannot be added to this list due to its
2544       *         type
2545       * @throws IllegalArgumentException if o cannot be added to this list for
2546       *         some other reason
2547       * @throws NullPointerException if o is null and this list doesn't support
2548       *         the addition of null values.
2549       */
2550      public boolean addAll(int index, Collection<? extends T> c)      public boolean addAll(int index, Collection<? extends T> c)
2551      {      {
2552        synchronized (mutex)        synchronized (mutex)
# Line 2101  public class Collections Line 2555  public class Collections
2555          }          }
2556      }      }
2557    
2558       /**
2559        * Tests whether the underlying list is equal to the supplied object.
2560        * The object is deemed to be equal if it is also a <code>List</code>
2561        * of equal size and with the same elements (i.e. each element, e1,
2562        * in list, l1, and each element, e2, in l2, must return <code>true</code> for
2563        * <code>e1 == null ? e2 == null : e1.equals(e2)</code>.  Before the
2564        * comparison is made, a lock is obtained on the mutex.
2565        *
2566        * @param o The object to test for equality with the underlying list.
2567        * @return <code>true</code> if o is equal to the underlying list under the above
2568        *         definition.
2569        */
2570      public boolean equals(Object o)      public boolean equals(Object o)
2571      {      {
2572        synchronized (mutex)        synchronized (mutex)
# Line 2109  public class Collections Line 2575  public class Collections
2575          }          }
2576      }      }
2577    
2578        /**
2579         * Retrieves the object at the specified index.  A lock
2580         * is obtained on the mutex before the list is accessed.
2581         *
2582         * @param index the index of the element to be returned
2583         * @return the element at index index in this list
2584         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2585         */
2586      public T get(int index)      public T get(int index)
2587      {      {
2588        synchronized (mutex)        synchronized (mutex)
# Line 2117  public class Collections Line 2591  public class Collections
2591          }          }
2592      }      }
2593    
2594        /**
2595         * Obtains a hashcode for the underlying list, first obtaining
2596         * a lock on the mutex.  The calculation of the hashcode is
2597         * detailed in the documentation for the <code>List</code>
2598         * interface.
2599         *
2600         * @return The hashcode of the underlying list.
2601         * @see List#hashCode()
2602         */
2603      public int hashCode()      public int hashCode()
2604      {      {
2605        synchronized (mutex)        synchronized (mutex)
# Line 2125  public class Collections Line 2608  public class Collections
2608          }          }
2609      }      }
2610    
2611        /**
2612         * Obtain the first index at which a given object is to be found in the
2613         * underlying list.  A lock is obtained on the mutex before the list is
2614         * accessed.
2615         *
2616         * @param o the object to search for
2617         * @return the least integer n such that <code>o == null ? get(n) == null :
2618         *         o.equals(get(n))</code>, or -1 if there is no such index.
2619         * @throws ClassCastException if the type of o is not a valid
2620         *         type for this list.
2621         * @throws NullPointerException if o is null and this
2622         *         list does not support null values.
2623         */
2624    
2625      public int indexOf(Object o)      public int indexOf(Object o)
2626      {      {
2627        synchronized (mutex)        synchronized (mutex)
# Line 2133  public class Collections Line 2630  public class Collections
2630          }          }
2631      }      }
2632    
2633        /**
2634         * Obtain the last index at which a given object is to be found in this
2635         * underlying list.  A lock is obtained on the mutex before the list
2636         * is accessed.
2637         *
2638         * @return the greatest integer n such that <code>o == null ? get(n) == null
2639         *         : o.equals(get(n))</code>, or -1 if there is no such index.
2640         * @throws ClassCastException if the type of o is not a valid
2641         *         type for this list.
2642         * @throws NullPointerException if o is null and this
2643         *         list does not support null values.
2644         */
2645      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
2646      {      {
2647        synchronized (mutex)        synchronized (mutex)
# Line 2141  public class Collections Line 2650  public class Collections
2650          }          }
2651      }      }
2652    
2653        /**
2654         * Retrieves a synchronized wrapper around the underlying list's
2655         * list iterator.  A lock is obtained on the mutex before the
2656         * list iterator is retrieved.
2657         *
2658         * @return A list iterator over the elements in the underlying list.
2659         *         The list iterator allows additional list-specific operations
2660         *         to be performed, in addition to those supplied by the
2661         *         standard iterator.
2662         */
2663      public ListIterator<T> listIterator()      public ListIterator<T> listIterator()
2664      {      {
2665        synchronized (mutex)        synchronized (mutex)
# Line 2149  public class Collections Line 2668  public class Collections
2668          }          }
2669      }      }
2670    
2671        /**
2672         * Retrieves a synchronized wrapper around the underlying list's
2673         * list iterator.  A lock is obtained on the mutex before the
2674         * list iterator is retrieved.  The iterator starts at the
2675         * index supplied, leading to the element at that index being
2676         * the first one returned by <code>next()</code>.  Calling
2677         * <code>previous()</code> from this initial position returns
2678         * index - 1.
2679         *
2680         * @param index the position, between 0 and size() inclusive, to begin the
2681         *        iteration from
2682         * @return A list iterator over the elements in the underlying list.
2683         *         The list iterator allows additional list-specific operations
2684         *         to be performed, in addition to those supplied by the
2685         *         standard iterator.
2686         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
2687         */
2688      public ListIterator<T> listIterator(int index)      public ListIterator<T> listIterator(int index)
2689      {      {
2690        synchronized (mutex)        synchronized (mutex)
# Line 2158  public class Collections Line 2694  public class Collections
2694          }          }
2695      }      }
2696    
2697        /**
2698         * Remove the element at a given position in the underlying list (optional
2699         * operation).  All remaining elements are shifted to the left to fill the gap.
2700         * A lock on the mutex is obtained before the element is removed.
2701         *
2702         * @param index the position within the list of the object to remove
2703         * @return the object that was removed
2704         * @throws UnsupportedOperationException if this list does not support the
2705         *         remove operation
2706         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2707         */
2708      public T remove(int index)      public T remove(int index)
2709      {      {
2710        synchronized (mutex)        synchronized (mutex)
# Line 2166  public class Collections Line 2713  public class Collections
2713          }          }
2714      }      }
2715    
2716      /**
2717       * Replace an element of the underlying list with another object (optional
2718       * operation).  A lock is obtained on the mutex before the element is
2719       * replaced.
2720       *
2721       * @param index the position within this list of the element to be replaced
2722       * @param o the object to replace it with
2723       * @return the object that was replaced
2724       * @throws UnsupportedOperationException if this list does not support the
2725       *         set operation.
2726       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2727       * @throws ClassCastException if o cannot be added to this list due to its
2728       *         type
2729       * @throws IllegalArgumentException if o cannot be added to this list for
2730       *         some other reason
2731       * @throws NullPointerException if o is null and this
2732       *         list does not support null values.
2733       */
2734      public T set(int index, T o)      public T set(int index, T o)
2735      {      {
2736        synchronized (mutex)        synchronized (mutex)
# Line 2174  public class Collections Line 2739  public class Collections
2739          }          }
2740      }      }
2741    
2742        /**
2743         * Obtain a List view of a subsection of the underlying list, from fromIndex
2744         * (inclusive) to toIndex (exclusive). If the two indices are equal, the
2745         * sublist is empty. The returned list should be modifiable if and only
2746         * if this list is modifiable. Changes to the returned list should be
2747         * reflected in this list. If this list is structurally modified in
2748         * any way other than through the returned list, the result of any subsequent
2749         * operations on the returned list is undefined.  A lock is obtained
2750         * on the mutex before the creation of the sublist.  The returned list
2751         * is also synchronized, using the same mutex.
2752         *
2753         * @param fromIndex the index that the returned list should start from
2754         *        (inclusive)
2755         * @param toIndex the index that the returned list should go to (exclusive)
2756         * @return a List backed by a subsection of this list
2757         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
2758         *         || toIndex &gt; size() || fromIndex &gt; toIndex
2759         */
2760      public List<T> subList(int fromIndex, int toIndex)      public List<T> subList(int fromIndex, int toIndex)
2761      {      {
2762        synchronized (mutex)        synchronized (mutex)
# Line 2220  public class Collections Line 2803  public class Collections
2803        super(sync, l);        super(sync, l);
2804      }      }
2805    
2806        /**
2807         * Obtain a List view of a subsection of the underlying list, from fromIndex
2808         * (inclusive) to toIndex (exclusive). If the two indices are equal, the
2809         * sublist is empty. The returned list should be modifiable if and only
2810         * if this list is modifiable. Changes to the returned list should be
2811         * reflected in this list. If this list is structurally modified in
2812         * any way other than through the returned list, the result of any subsequent
2813         * operations on the returned list is undefined.    A lock is obtained
2814         * on the mutex before the creation of the sublist.  The returned list
2815         * is also synchronized, using the same mutex.  Random accessibility
2816         * is also extended to the new list.
2817         *
2818         * @param fromIndex the index that the returned list should start from
2819         *        (inclusive)
2820         * @param toIndex the index that the returned list should go to (exclusive)
2821         * @return a List backed by a subsection of this list
2822         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
2823         *         || toIndex &gt; size() || fromIndex &gt; toIndex
2824         */
2825      public List<T> subList(int fromIndex, int toIndex)      public List<T> subList(int fromIndex, int toIndex)
2826      {      {
2827        synchronized (mutex)        synchronized (mutex)
# Line 2257  public class Collections Line 2859  public class Collections
2859        this.li = li;        this.li = li;
2860      }      }
2861    
2862        /**
2863         * Insert an element into the underlying list at the current position of
2864         * the iterator (optional operation). The element is inserted in between
2865         * the element that would be returned by <code>previous()</code> and the
2866         * element that would be returned by <code>next()</code>. After the
2867         * insertion, a subsequent call to next is unaffected, but
2868         * a call to previous returns the item that was added. The values returned
2869         * by nextIndex() and previousIndex() are incremented.  A lock is obtained
2870         * on the mutex before the addition takes place.
2871         *
2872         * @param o the object to insert into the list
2873         * @throws ClassCastException if the object is of a type which cannot be added
2874         *         to this list.
2875         * @throws IllegalArgumentException if some other aspect of the object stops
2876         *         it being added to this list.
2877         * @throws UnsupportedOperationException if this ListIterator does not
2878         *         support the add operation.
2879         */
2880      public void add(T o)      public void add(T o)
2881      {      {
2882        synchronized (mutex)        synchronized (mutex)
# Line 2265  public class Collections Line 2885  public class Collections
2885          }          }
2886      }      }
2887    
2888        /**
2889         * Tests whether there are elements remaining in the underlying list
2890         * in the reverse direction. In other words, <code>previous()</code>
2891         * will not fail with a NoSuchElementException.  A lock is obtained
2892         * on the mutex before the check takes place.
2893         *
2894         * @return <code>true</code> if the list continues in the reverse direction
2895         */
2896      public boolean hasPrevious()      public boolean hasPrevious()
2897      {      {
2898        synchronized (mutex)        synchronized (mutex)
# Line 2273  public class Collections Line 2901  public class Collections
2901          }          }
2902      }      }
2903    
2904        /**
2905          * Find the index of the element that would be returned by a call to
2906          * <code>next()</code>.  If hasNext() returns <code>false</code>, this
2907          * returns the list size.  A lock is obtained on the mutex before the
2908          * query takes place.
2909          *
2910          * @return the index of the element that would be returned by next()
2911          */
2912      public int nextIndex()      public int nextIndex()
2913      {      {
2914        synchronized (mutex)        synchronized (mutex)
# Line 2281  public class Collections Line 2917  public class Collections
2917          }          }
2918      }      }
2919    
2920        /**
2921         * Obtain the previous element from the underlying list. Repeated
2922         * calls to previous may be used to iterate backwards over the entire list,
2923         * or calls to next and previous may be used together to go forwards and
2924         * backwards. Alternating calls to next and previous will return the same
2925         * element.  A lock is obtained on the mutex before the object is retrieved.
2926         *
2927         * @return the next element in the list in the reverse direction
2928         * @throws NoSuchElementException if there are no more elements
2929         */
2930      public T previous()      public T previous()
2931      {      {
2932        synchronized (mutex)        synchronized (mutex)
# Line 2289  public class Collections Line 2935  public class Collections
2935          }          }
2936      }      }
2937    
2938        /**
2939         * Find the index of the element that would be returned by a call to
2940         * previous. If hasPrevious() returns <code>false</code>, this returns -1.
2941         * A lock is obtained on the mutex before the query takes place.
2942         *
2943         * @return the index of the element that would be returned by previous()
2944         */
2945      public int previousIndex()      public int previousIndex()
2946      {      {
2947        synchronized (mutex)        synchronized (mutex)
# Line 2297  public class Collections Line 2950  public class Collections
2950          }          }
2951      }      }
2952    
2953        /**
2954         * Replace the element last returned by a call to <code>next()</code> or
2955         * <code>previous()</code> with a given object (optional operation).  This
2956         * method may only be called if neither <code>add()</code> nor
2957         * <code>remove()</code> have been called since the last call to
2958         * <code>next()</code> or <code>previous</code>.  A lock is obtained
2959         * on the mutex before the list is modified.
2960         *
2961         * @param o the object to replace the element with
2962         * @throws ClassCastException the object is of a type which cannot be added
2963         *         to this list
2964         * @throws IllegalArgumentException some other aspect of the object stops
2965         *         it being added to this list
2966         * @throws IllegalStateException if neither next or previous have been
2967         *         called, or if add or remove has been called since the last call
2968         *         to next or previous
2969         * @throws UnsupportedOperationException if this ListIterator does not
2970         *         support the set operation
2971         */
2972      public void set(T o)      public void set(T o)
2973      {      {
2974        synchronized (mutex)        synchronized (mutex)
# Line 2403  public class Collections Line 3075  public class Collections
3075        mutex = sync;        mutex = sync;
3076      }      }
3077    
3078        /**
3079         * Clears all the entries from the underlying map.  A lock is obtained
3080         * on the mutex before the map is cleared.
3081         *
3082         * @throws UnsupportedOperationException if clear is not supported
3083         */
3084      public void clear()      public void clear()
3085      {      {
3086        synchronized (mutex)        synchronized (mutex)
# Line 2411  public class Collections Line 3089  public class Collections
3089          }          }
3090      }      }
3091    
3092        /**
3093         * Returns <code>true</code> if the underlying map contains a entry for the given key.
3094         * A lock is obtained on the mutex before the map is queried.
3095         *
3096         * @param key the key to search for.
3097         * @return <code>true</code> if the underlying map contains the key.
3098         * @throws ClassCastException if the key is of an inappropriate type.
3099         * @throws NullPointerException if key is <code>null</code> but the map
3100         *         does not permit null keys.
3101         */
3102      public boolean containsKey(Object key)      public boolean containsKey(Object key)
3103      {      {
3104        synchronized (mutex)        synchronized (mutex)
# Line 2419  public class Collections Line 3107  public class Collections
3107          }          }
3108      }      }
3109    
3110      /**
3111       * Returns <code>true</code> if the underlying map contains at least one entry with the
3112       * given value.  In other words, returns <code>true</code> if a value v exists where
3113       * <code>(value == null ? v == null : value.equals(v))</code>. This usually
3114       * requires linear time.  A lock is obtained on the mutex before the map
3115       * is queried.
3116       *
3117       * @param value the value to search for
3118       * @return <code>true</code> if the map contains the value
3119       * @throws ClassCastException if the type of the value is not a valid type
3120       *         for this map.
3121       * @throws NullPointerException if the value is null and the map doesn't
3122       *         support null values.
3123       */
3124      public boolean containsValue(Object value)      public boolean containsValue(Object value)
3125      {      {
3126        synchronized (mutex)        synchronized (mutex)
# Line 2441  public class Collections Line 3143  public class Collections
3143          {          {
3144            e = o;            e = o;
3145          }          }
3146    
3147            /**
3148             * Returns <code>true</code> if the object, o, implements <code>Map.Entry</code>
3149             * with the same key and value as the underlying entry.  A lock is
3150             * obtained on the mutex before the comparison takes place.
3151             *
3152             * @param o The object to compare with this entry.
3153             * @return <code>true</code> if o is equivalent to the underlying map entry.
3154             */
3155          public boolean equals(Object o)          public boolean equals(Object o)
3156          {          {
3157            synchronized (mutex)            synchronized (mutex)
# Line 2448  public class Collections Line 3159  public class Collections
3159                return e.equals(o);                return e.equals(o);
3160              }              }
3161          }          }
3162    
3163            /**
3164             * Returns the key used in the underlying map entry.  A lock is obtained
3165             * on the mutex before the key is retrieved.
3166             *
3167             * @return The key of the underlying map entry.
3168             */
3169          public K getKey()          public K getKey()
3170          {          {
3171            synchronized (mutex)            synchronized (mutex)
# Line 2455  public class Collections Line 3173  public class Collections
3173                return e.getKey();                return e.getKey();
3174              }              }
3175          }          }
3176    
3177            /**
3178             * Returns the value used in the underlying map entry.  A lock is obtained
3179             * on the mutex before the value is retrieved.
3180             *
3181             * @return The value of the underlying map entry.
3182             */
3183          public V getValue()          public V getValue()
3184          {          {
3185            synchronized (mutex)            synchronized (mutex)
# Line 2462  public class Collections Line 3187  public class Collections
3187                return e.getValue();                return e.getValue();
3188              }              }
3189          }          }
3190    
3191            /**
3192             * Computes the hash code for the underlying map entry.
3193             * This computation is described in the documentation for the
3194             * <code>Map</code> interface.  A lock is obtained on the mutex
3195             * before the underlying map is accessed.
3196             *
3197             * @return The hash code of the underlying map entry.
3198             * @see Map#hashCode()
3199             */
3200          public int hashCode()          public int hashCode()
3201          {          {
3202            synchronized (mutex)            synchronized (mutex)
# Line 2469  public class Collections Line 3204  public class Collections
3204                return e.hashCode();                return e.hashCode();
3205              }              }
3206          }          }
3207    
3208            /**
3209             * Replaces the value in the underlying map entry with the specified
3210             * object (optional operation).  A lock is obtained on the mutex
3211             * before the map is altered.  The map entry, in turn, will alter
3212             * the underlying map object.  The operation is undefined if the
3213             * <code>remove()</code> method of the iterator has been called
3214             * beforehand.
3215             *
3216             * @param value the new value to store
3217             * @return the old value
3218             * @throws UnsupportedOperationException if the operation is not supported.
3219             * @throws ClassCastException if the value is of the wrong type.
3220             * @throws IllegalArgumentException if something about the value
3221             *         prevents it from existing in this map.
3222             * @throws NullPointerException if the map forbids null values.
3223             */
3224          public V setValue(V value)          public V setValue(V value)
3225          {          {
3226            synchronized (mutex)            synchronized (mutex)
# Line 2476  public class Collections Line 3228  public class Collections
3228                return e.setValue(value);                return e.setValue(value);
3229              }              }
3230          }          }
3231    
3232            /**
3233             * Returns a textual representation of the underlying map entry.
3234             * A lock is obtained on the mutex before the entry is accessed.
3235             *
3236             * @return The contents of the map entry in <code>String</code> form.
3237             */
3238          public String toString()          public String toString()
3239          {          {
3240            synchronized (mutex)            synchronized (mutex)
# Line 2491  public class Collections Line 3250  public class Collections
3250            {            {
3251              entries = new SynchronizedSet<Map.Entry<K, V>>(mutex, m.entrySet())              entries = new SynchronizedSet<Map.Entry<K, V>>(mutex, m.entrySet())
3252              {              {
3253                  /**
3254                   * Returns an iterator over the set.  The iterator has no specific order,
3255                   * unless further specified.  A lock is obtained on the set's mutex
3256                   * before the iterator is created.  The created iterator is also
3257                   * thread-safe.
3258                   *
3259                   * @return A synchronized set iterator.
3260                   */
3261                public Iterator<Map.Entry<K, V>> iterator()                public Iterator<Map.Entry<K, V>> iterator()
3262                {                {
3263                  synchronized (super.mutex)                  synchronized (super.mutex)
# Line 2498  public class Collections Line 3265  public class Collections
3265                      return new SynchronizedIterator<Map.Entry<K, V>>(super.mutex,                      return new SynchronizedIterator<Map.Entry<K, V>>(super.mutex,
3266                                                                       c.iterator())                                                                       c.iterator())
3267                      {                      {
3268                          /**
3269                           * Retrieves the next map entry from the iterator.
3270                           * A lock is obtained on the iterator's mutex before
3271                           * the entry is created.  The new map entry is enclosed in
3272                           * a thread-safe wrapper.
3273                           *
3274                           * @return A synchronized map entry.
3275                           */
3276                        public Map.Entry<K, V> next()                        public Map.Entry<K, V> next()
3277                        {                        {
3278                          synchronized (super.mutex)                          synchronized (super.mutex)
# Line 2513  public class Collections Line 3288  public class Collections
3288        return entries;        return entries;
3289      }      }
3290    
3291        /**
3292         * Returns <code>true</code> if the object, o, is also an instance
3293         * of <code>Map</code> and contains an equivalent
3294         * entry set to that of the underlying map.  A lock
3295         * is obtained on the mutex before the objects are
3296         * compared.
3297         *
3298         * @param o The object to compare.
3299         * @return <code>true</code> if o and the underlying map are equivalent.
3300         */
3301      public boolean equals(Object o)      public boolean equals(Object o)
3302      {      {
3303        synchronized (mutex)        synchronized (mutex)
# Line 2521  public class Collections Line 3306  public class Collections
3306          }          }
3307      }      }
3308    
3309        /**
3310         * Returns the value associated with the given key, or null
3311         * if no such mapping exists.  An ambiguity exists with maps
3312         * that accept null values as a return value of null could
3313         * be due to a non-existent mapping or simply a null value
3314         * for that key.  To resolve this, <code>containsKey</code>
3315         * should be used.  A lock is obtained on the mutex before
3316         * the value is retrieved from the underlying map.
3317         *
3318         * @param key The key of the required mapping.
3319         * @return The value associated with the given key, or
3320         *         null if no such mapping exists.
3321         * @throws ClassCastException if the key is an inappropriate type.
3322         * @throws NullPointerException if this map does not accept null keys.
3323         */
3324      public V get(Object key)      public V get(Object key)
3325      {      {
3326        synchronized (mutex)        synchronized (mutex)
# Line 2529  public class Collections Line 3329  public class Collections
3329          }          }
3330      }      }
3331    
3332        /**
3333         * Calculates the hash code of the underlying map as the
3334         * sum of the hash codes of all entries.  A lock is obtained
3335         * on the mutex before the hash code is computed.
3336         *
3337         * @return The hash code of the underlying map.
3338         */
3339      public int hashCode()      public int hashCode()
3340      {      {
3341        synchronized (mutex)        synchronized (mutex)
# Line 2537  public class Collections Line 3344  public class Collections
3344          }          }
3345      }      }
3346    
3347        /**
3348         * Returns <code>true</code> if the underlying map contains no entries.
3349         * A lock is obtained on the mutex before the map is examined.
3350         *
3351         * @return <code>true</code> if the map is empty.
3352         */
3353      public boolean isEmpty()      public boolean isEmpty()
3354      {      {
3355        synchronized (mutex)        synchronized (mutex)
# Line 2545  public class Collections Line 3358  public class Collections
3358          }          }
3359      }      }
3360    
3361        /**
3362         * Returns a thread-safe set view of the keys in the underlying map.  The
3363         * set is backed by the map, so that changes in one show up in the other.
3364         * Modifications made while an iterator is in progress cause undefined
3365         * behavior.  If the set supports removal, these methods remove the
3366         * underlying mapping from the map: <code>Iterator.remove</code>,
3367         * <code>Set.remove</code>, <code>removeAll</code>, <code>retainAll</code>,
3368         * and <code>clear</code>.  Element addition, via <code>add</code> or
3369         * <code>addAll</code>, is not supported via this set.  A lock is obtained
3370         * on the mutex before the set is created.
3371         *
3372         * @return A synchronized set containing the keys of the underlying map.
3373         */
3374      public Set<K> keySet()      public Set<K> keySet()
3375      {      {
3376        if (keys == null)        if (keys == null)
# Line 2555  public class Collections Line 3381  public class Collections
3381        return keys;        return keys;
3382      }      }
3383    
3384        /**
3385         * Associates the given key to the given value (optional operation). If the
3386         * underlying map already contains the key, its value is replaced. Be aware
3387         * that in a map that permits <code>null</code> values, a null return does not
3388         * always imply that the mapping was created.  A lock is obtained on the mutex
3389         * before the modification is made.
3390         *
3391         * @param key the key to map.
3392         * @param value the value to be mapped.
3393         * @return the previous value of the key, or null if there was no mapping
3394         * @throws UnsupportedOperationException if the operation is not supported
3395         * @throws ClassCastException if the key or value is of the wrong type
3396         * @throws IllegalArgumentException if something about this key or value
3397         *         prevents it from existing in this map
3398         * @throws NullPointerException if either the key or the value is null,
3399         *         and the map forbids null keys or values
3400         * @see #containsKey(Object)
3401         */
3402      public V put(K key, V value)      public V put(K key, V value)
3403      {      {
3404        synchronized (mutex)        synchronized (mutex)
# Line 2563  public class Collections Line 3407  public class Collections
3407          }          }
3408      }      }
3409    
3410        /**
3411         * Copies all entries of the given map to the underlying one (optional
3412         * operation). If the map already contains a key, its value is replaced.
3413         * A lock is obtained on the mutex before the operation proceeds.
3414         *
3415         * @param m the mapping to load into this map
3416         * @throws UnsupportedOperationException if the operation is not supported
3417         * @throws ClassCastException if a key or value is of the wrong type
3418         * @throws IllegalArgumentException if something about a key or value
3419         *         prevents it from existing in this map
3420         * @throws NullPointerException if the map forbids null keys or values, or
3421         *         if <code>m</code> is null.
3422         * @see #put(Object, Object)
3423         */
3424      public void putAll(Map<? extends K, ? extends V> map)      public void putAll(Map<? extends K, ? extends V> map)
3425      {      {
3426        synchronized (mutex)        synchronized (mutex)
# Line 2571  public class Collections Line 3429  public class Collections
3429          }          }
3430      }      }
3431    
3432        /**
3433         * Removes the mapping for the key, o, if present (optional operation). If
3434         * the key is not present, this returns null. Note that maps which permit
3435         * null values may also return null if the key was removed.  A prior
3436         * <code>containsKey()</code> check is required to avoid this ambiguity.
3437         * Before the mapping is removed, a lock is obtained on the mutex.
3438         *
3439         * @param key the key to remove
3440         * @return the value the key mapped to, or null if not present
3441         * @throws UnsupportedOperationException if deletion is unsupported
3442         * @throws NullPointerException if the key is null and this map doesn't
3443         *         support null keys.
3444         * @throws ClassCastException if the type of the key is not a valid type
3445         *         for this map.
3446         */
3447      public V remove(Object o)      public V remove(Object o)
3448      {      {
3449        synchronized (mutex)        synchronized (mutex)
# Line 2579  public class Collections Line 3452  public class Collections
3452          }          }
3453      }      }
3454    
3455        /**
3456         * Retrieves the size of the underlying map.  A lock
3457         * is obtained on the mutex before access takes place.
3458         * Maps with a size greater than <code>Integer.MAX_VALUE</code>
3459         * return <code>Integer.MAX_VALUE</code> instead.
3460         *
3461         * @return The size of the underlying map.
3462         */
3463      public int size()      public int size()
3464      {      {
3465        synchronized (mutex)        synchronized (mutex)
# Line 2587  public class Collections Line 3468  public class Collections
3468          }          }
3469      }      }
3470    
3471        /**
3472         * Returns a textual representation of the underlying
3473         * map.  A lock is obtained on the mutex before the map
3474         * is accessed.
3475         *
3476         * @return The map in <code>String</code> form.
3477         */
3478      public String toString()      public String toString()
3479      {      {
3480        synchronized (mutex)        synchronized (mutex)
# Line 2595  public class Collections Line 3483  public class Collections
3483          }          }
3484      }      }
3485    
3486        /**
3487         * Returns a synchronized collection view of the values in the underlying
3488         * map.  The collection is backed by the map, so that changes in one show up in
3489         * the other.  Modifications made while an iterator is in progress cause
3490         * undefined behavior.  If the collection supports removal, these methods
3491         * remove the underlying mapping from the map: <code>Iterator.remove</code>,
3492         * <code>Collection.remove</code>, <code>removeAll</code>,
3493         * <code>retainAll</code>, and <code>clear</code>. Element addition, via
3494         * <code>add</code> or <code>addAll</code>, is not supported via this
3495         * collection.  A lock is obtained on the mutex before the collection
3496         * is created.
3497         *
3498         * @return the collection of all values in the underlying map.
3499         */
3500      public Collection<V> values()      public Collection<V> values()
3501      {      {
3502        if (values == null)        if (values == null)
# Line 2671  public class Collections Line 3573  public class Collections
3573        super(sync, s);        super(sync, s);
3574      }      }
3575    
3576        /**
3577         * Returns <code>true</code> if the object, o, is a <code>Set</code>
3578         * of the same size as the underlying set, and contains
3579         * each element, e, which occurs in the underlying set.
3580         * A lock is obtained on the mutex before the comparison
3581         * takes place.
3582         *
3583         * @param o The object to compare against.
3584         * @return <code>true</code> if o is an equivalent set.
3585         */
3586      public boolean equals(Object o)      public boolean equals(Object o)
3587      {      {
3588        synchronized (mutex)        synchronized (mutex)
# Line 2679  public class Collections Line 3591  public class Collections
3591          }          }
3592      }      }
3593    
3594        /**
3595         * Computes the hash code for the underlying set as the
3596         * sum of the hash code of all elements within the set.
3597         * A lock is obtained on the mutex before the computation
3598         * occurs.
3599         *
3600         * @return The hash code for the underlying set.
3601         */
3602      public int hashCode()      public int hashCode()
3603      {      {
3604        synchronized (mutex)        synchronized (mutex)
# Line 2767  public class Collections Line 3687  public class Collections
3687        this.sm = sm;        this.sm = sm;
3688      }      }
3689    
3690        /**
3691         * Returns the comparator used in sorting the underlying map, or null if
3692         * it is the keys' natural ordering.  A lock is obtained on the mutex
3693         * before the comparator is retrieved.
3694         *
3695         * @return the sorting comparator.
3696         */
3697      public Comparator<? super K> comparator()      public Comparator<? super K> comparator()
3698      {      {
3699        synchronized (mutex)        synchronized (mutex)
# Line 2775  public class Collections Line 3702  public class Collections
3702          }          }
3703      }      }
3704    
3705        /**
3706         * Returns the first, lowest sorted, key from the underlying map.
3707         * A lock is obtained on the mutex before the map is accessed.
3708         *
3709         * @return the first key.
3710         * @throws NoSuchElementException if this map is empty.
3711         */
3712      public K firstKey()      public K firstKey()
3713      {      {
3714        synchronized (mutex)        synchronized (mutex)
# Line 2783  public class Collections Line 3717  public class Collections
3717          }          }
3718      }      }
3719    
3720        /**
3721         * Returns a submap containing the keys from the first
3722         * key (as returned by <code>firstKey()</code>) to
3723         * the key before that specified.  The submap supports all
3724         * operations supported by the underlying map and all actions
3725         * taking place on the submap are also reflected in the underlying
3726         * map.  A lock is obtained on the mutex prior to submap creation.
3727         * This operation is equivalent to <code>subMap(firstKey(), toKey)</code>.
3728         * The submap retains the thread-safe status of this map.
3729         *
3730         * @param toKey the exclusive upper range of the submap.
3731         * @return a submap from <code>firstKey()</code> to the
3732         *         the key preceding toKey.
3733         * @throws ClassCastException if toKey is not comparable to the underlying
3734         *         map's contents.
3735         * @throws IllegalArgumentException if toKey is outside the map's range.
3736         * @throws NullPointerException if toKey is null. but the map does not allow
3737         *         null keys.
3738         */
3739      public SortedMap<K, V> headMap(K toKey)      public SortedMap<K, V> headMap(K toKey)
3740      {      {
3741        synchronized (mutex)        synchronized (mutex)
# Line 2791  public class Collections Line 3744  public class Collections
3744          }          }
3745      }      }
3746    
3747        /**
3748         * Returns the last, highest sorted, key from the underlying map.
3749         * A lock is obtained on the mutex before the map is accessed.
3750         *
3751         * @return the last key.
3752         * @throws NoSuchElementException if this map is empty.
3753         */
3754      public K lastKey()      public K lastKey()
3755      {      {
3756        synchronized (mutex)        synchronized (mutex)
# Line 2799  public class Collections Line 3759  public class Collections
3759          }          }
3760      }      }
3761    
3762        /**
3763         * Returns a submap containing the keys from fromKey to
3764         * the key before toKey.  The submap supports all
3765         * operations supported by the underlying map and all actions
3766         * taking place on the submap are also reflected in the underlying
3767         * map.  A lock is obtained on the mutex prior to submap creation.
3768         * The submap retains the thread-safe status of this map.
3769         *
3770         * @param fromKey the inclusive lower range of the submap.
3771         * @param toKey the exclusive upper range of the submap.
3772         * @return a submap from fromKey to the key preceding toKey.
3773         * @throws ClassCastException if fromKey or toKey is not comparable
3774         *         to the underlying map's contents.
3775         * @throws IllegalArgumentException if fromKey or toKey is outside the map's
3776         *         range.
3777         * @throws NullPointerException if fromKey or toKey is null. but the map does
3778         *         not allow  null keys.
3779         */
3780      public SortedMap<K, V> subMap(K fromKey, K toKey)      public SortedMap<K, V> subMap(K fromKey, K toKey)
3781      {      {
3782        synchronized (mutex)        synchronized (mutex)
# Line 2808  public class Collections Line 3786  public class Collections
3786          }          }
3787      }      }
3788    
3789        /**
3790         * Returns a submap containing all the keys from fromKey onwards.
3791         * The submap supports all operations supported by the underlying
3792         * map and all actions taking place on the submap are also reflected
3793         * in the underlying map.  A lock is obtained on the mutex prior to
3794         * submap creation.  The submap retains the thread-safe status of
3795         * this map.
3796         *
3797         * @param fromKey the inclusive lower range of the submap.
3798         * @return a submap from fromKey to <code>lastKey()</code>.
3799         * @throws ClassCastException if fromKey is not comparable to the underlying
3800         *         map's contents.
3801         * @throws IllegalArgumentException if fromKey is outside the map's range.
3802         * @throws NullPointerException if fromKey is null. but the map does not allow
3803         *         null keys.
3804         */
3805      public SortedMap<K, V> tailMap(K fromKey)      public SortedMap<K, V> tailMap(K fromKey)
3806      {      {
3807        synchronized (mutex)        synchronized (mutex)
# Line 2891  public class Collections Line 3885  public class Collections
3885        this.ss = ss;        this.ss = ss;
3886      }      }
3887    
3888        /**
3889         * Returns the comparator used in sorting the underlying set, or null if
3890         * it is the elements' natural ordering.  A lock is obtained on the mutex
3891         * before the comparator is retrieved.
3892         *
3893         * @return the sorting comparator.
3894         */
3895      public Comparator<? super T> comparator()      public Comparator<? super T> comparator()
3896      {      {
3897        synchronized (mutex)        synchronized (mutex)
# Line 2899  public class Collections Line 3900  public class Collections
3900          }          }
3901      }      }
3902    
3903        /**
3904         * Returns the first, lowest sorted, element from the underlying set.
3905         * A lock is obtained on the mutex before the set is accessed.
3906         *
3907         * @return the first element.
3908         * @throws NoSuchElementException if this set is empty.
3909         */
3910      public T first()      public T first()
3911      {      {
3912        synchronized (mutex)        synchronized (mutex)
# Line 2907  public class Collections Line 3915  public class Collections
3915          }          }
3916      }      }
3917    
3918        /**
3919         * Returns a subset containing the element from the first
3920         * element (as returned by <code>first()</code>) to
3921         * the element before that specified.  The subset supports all
3922         * operations supported by the underlying set and all actions
3923         * taking place on the subset are also reflected in the underlying
3924         * set.  A lock is obtained on the mutex prior to subset creation.
3925         * This operation is equivalent to <code>subSet(first(), toElement)</code>.
3926         * The subset retains the thread-safe status of this set.
3927         *
3928         * @param toElement the exclusive upper range of the subset.
3929         * @return a subset from <code>first()</code> to the
3930         *         the element preceding toElement.
3931         * @throws ClassCastException if toElement is not comparable to the underlying
3932         *         set's contents.
3933         * @throws IllegalArgumentException if toElement is outside the set's range.
3934         * @throws NullPointerException if toElement is null. but the set does not allow
3935         *         null elements.
3936         */
3937      public SortedSet<T> headSet(T toElement)      public SortedSet<T> headSet(T toElement)
3938      {      {
3939        synchronized (mutex)        synchronized (mutex)
# Line 2915  public class Collections Line 3942  public class Collections
3942          }          }
3943      }      }
3944    
3945        /**
3946         * Returns the last, highest sorted, element from the underlying set.
3947         * A lock is obtained on the mutex before the set is accessed.
3948         *
3949         * @return the last element.
3950         * @throws NoSuchElementException if this set is empty.
3951         */
3952      public T last()      public T last()
3953      {      {
3954        synchronized (mutex)        synchronized (mutex)
# Line 2923  public class Collections Line 3957  public class Collections
3957          }          }
3958      }      }
3959    
3960        /**
3961         * Returns a subset containing the elements from fromElement to
3962         * the element before toElement.  The subset supports all
3963         * operations supported by the underlying set and all actions
3964         * taking place on the subset are also reflected in the underlying
3965         * set.  A lock is obtained on the mutex prior to subset creation.
3966         * The subset retains the thread-safe status of this set.
3967         *
3968         * @param fromElement the inclusive lower range of the subset.
3969         * @param toElement the exclusive upper range of the subset.
3970         * @return a subset from fromElement to the element preceding toElement.
3971         * @throws ClassCastException if fromElement or toElement is not comparable
3972         *         to the underlying set's contents.
3973         * @throws IllegalArgumentException if fromElement or toElement is outside the set's
3974         *         range.
3975         * @throws NullPointerException if fromElement or toElement is null. but the set does
3976         *         not allow null elements.
3977         */
3978      public SortedSet<T> subSet(T fromElement, T toElement)      public SortedSet<T> subSet(T fromElement, T toElement)
3979      {      {
3980        synchronized (mutex)        synchronized (mutex)
# Line 2933  public class Collections Line 3985  public class Collections
3985          }          }
3986      }      }
3987    
3988        /**
3989         * Returns a subset containing all the elements from fromElement onwards.
3990         * The subset supports all operations supported by the underlying
3991         * set and all actions taking place on the subset are also reflected
3992         * in the underlying set.  A lock is obtained on the mutex prior to
3993         * subset creation.  The subset retains the thread-safe status of
3994         * this set.
3995         *
3996         * @param fromElement the inclusive lower range of the subset.
3997         * @return a subset from fromElement to <code>last()</code>.
3998         * @throws ClassCastException if fromElement is not comparable to the underlying
3999         *         set's contents.
4000         * @throws IllegalArgumentException if fromElement is outside the set's range.
4001         * @throws NullPointerException if fromElement is null. but the set does not allow
4002         *         null elements.
4003         */
4004      public SortedSet<T> tailSet(T fromElement)      public SortedSet<T> tailSet(T fromElement)
4005      {      {
4006        synchronized (mutex)        synchronized (mutex)
# Line 2947  public class Collections Line 4015  public class Collections
4015     * Returns an unmodifiable view of the given collection. This allows     * Returns an unmodifiable view of the given collection. This allows
4016     * "read-only" access, although changes in the backing collection show up     * "read-only" access, although changes in the backing collection show up
4017     * in this view. Attempts to modify the collection directly or via iterators     * in this view. Attempts to modify the collection directly or via iterators
4018     * will fail with {@link UnsupportedOperationException}.     * will fail with {@link UnsupportedOperationException}.  Although this view
4019       * prevents changes to the structure of the collection and its elements, the values
4020       * referenced by the objects in the collection can still be modified.
4021     * <p>     * <p>
4022     *     *
4023     * Since the collection might be a List or a Set, and those have incompatible     * Since the collection might be a List or a Set, and those have incompatible
# Line 2997  public class Collections Line 4067  public class Collections
4067          throw new NullPointerException();          throw new NullPointerException();
4068      }      }
4069    
4070        /**
4071         * Blocks the addition of elements to the underlying collection.
4072         * This method never returns, throwing an exception instead.
4073         *
4074         * @param o the object to add.
4075         * @return <code>true</code> if the collection was modified as a result of this action.
4076         * @throws UnsupportedOperationException as an unmodifiable collection does not
4077         *         support the add operation.
4078         */
4079      public boolean add(T o)      public boolean add(T o)
4080      {      {
4081        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4082      }      }
4083    
4084        /**
4085         * Blocks the addition of a collection of elements to the underlying
4086         * collection.  This method never returns, throwing an exception instead.
4087         *
4088         * @param c the collection to add.
4089         * @return <code>true</code> if the collection was modified as a result of this action.
4090         * @throws UnsupportedOperationException as an unmodifiable collection does not
4091         *         support the <code>addAll</code> operation.
4092         */
4093      public boolean addAll(Collection<? extends T> c)      public boolean addAll(Collection<? extends T> c)
4094      {      {
4095        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4096      }      }
4097    
4098        /**
4099         * Blocks the clearing of the underlying collection.  This method never
4100         * returns, throwing an exception instead.
4101         *
4102         * @throws UnsupportedOperationException as an unmodifiable collection does
4103         *         not support the <code>clear()</code> operation.
4104         */
4105      public void clear()      public void clear()
4106      {      {
4107        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4108      }      }
4109    
4110        /**
4111         * Test whether the underlying collection contains a given object as one of its
4112         * elements.
4113         *
4114         * @param o the element to look for.
4115         * @return <code>true</code> if the underlying collection contains at least
4116         *         one element e such that
4117         *         <code>o == null ? e == null : o.equals(e)</code>.
4118         * @throws ClassCastException if the type of o is not a valid type for the
4119         *         underlying collection.
4120         * @throws NullPointerException if o is null and the underlying collection
4121         *         doesn't support null values.
4122         */
4123      public boolean contains(Object o)      public boolean contains(Object o)
4124      {      {
4125        return c.contains(o);        return c.contains(o);
4126      }      }
4127    
4128        /**
4129         * Test whether the underlying collection contains every element in a given
4130         * collection.
4131         *
4132         * @param c the collection to test for.
4133         * @return <code>true</code> if for every element o in c, contains(o) would
4134         *         return <code>true</code>.
4135         * @throws ClassCastException if the type of any element in c is not a valid
4136         *   type for the underlying collection.
4137         * @throws NullPointerException if some element of c is null and the underlying
4138         *   collection does not support null values.
4139         * @throws NullPointerException if c itself is null.
4140         */
4141      public boolean containsAll(Collection<?> c1)      public boolean containsAll(Collection<?> c1)
4142      {      {
4143        return c.containsAll(c1);        return c.containsAll(c1);
4144      }      }
4145    
4146        /**
4147         * Tests whether the underlying collection is empty, that is,
4148         * if size() == 0.
4149         *
4150         * @return <code>true</code> if this collection contains no elements.
4151         */
4152      public boolean isEmpty()      public boolean isEmpty()
4153      {      {
4154        return c.isEmpty();        return c.isEmpty();
4155      }      }
4156    
4157        /**
4158         * Obtain an Iterator over the underlying collection, which maintains
4159         * its unmodifiable nature.
4160         *
4161         * @return an UnmodifiableIterator over the elements of the underlying
4162         *         collection, in any order.
4163         */
4164      public Iterator<T> iterator()      public Iterator<T> iterator()
4165      {      {
4166        return new UnmodifiableIterator<T>(c.iterator());        return new UnmodifiableIterator<T>(c.iterator());
4167      }      }
4168    
4169        /**
4170         * Blocks the removal of an object from the underlying collection.
4171         * This method never returns, throwing an exception instead.
4172         *
4173         * @param o The object to remove.
4174         * @return <code>true</code> if the object was removed (i.e. the underlying
4175         *         collection returned 1 or more instances of o).
4176         * @throws UnsupportedOperationException as an unmodifiable collection
4177         *         does not support the <code>remove()</code> operation.
4178         */
4179      public boolean remove(Object o)      public boolean remove(Object o)
4180      {      {
4181        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4182      }      }
4183    
4184        /**
4185         * Blocks the removal of a collection of objects from the underlying
4186         * collection.  This method never returns, throwing an exception
4187         * instead.
4188         *
4189         * @param c The collection of objects to remove.
4190         * @return <code>true</code> if the collection was modified.
4191         * @throws UnsupportedOperationException as an unmodifiable collection
4192         *         does not support the <code>removeAll()</code> operation.
4193         */
4194      public boolean removeAll(Collection<?> c)      public boolean removeAll(Collection<?> c)
4195      {      {
4196        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4197      }      }
4198    
4199        /**
4200         * Blocks the removal of all elements from the underlying collection,
4201         * except those in the supplied collection.  This method never returns,
4202         * throwing an exception instead.
4203         *
4204         * @param c The collection of objects to retain.
4205         * @return <code>true</code> if the collection was modified.
4206         * @throws UnsupportedOperationException as an unmodifiable collection
4207         *         does not support the <code>retainAll()</code> operation.
4208         */
4209      public boolean retainAll(Collection<?> c)      public boolean retainAll(Collection<?> c)
4210      {      {
4211        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4212      }      }
4213    
4214        /**
4215         * Retrieves the number of elements in the underlying collection.
4216         *
4217         * @return the number of elements in the collection.
4218         */
4219      public int size()      public int size()
4220      {      {
4221        return c.size();        return c.size();
4222      }      }
4223    
4224        /**
4225         * Copy the current contents of the underlying collection into an array.
4226         *
4227         * @return an array of type Object[] with a length equal to the size of the
4228         *         underlying collection and containing the elements currently in
4229         *         the underlying collection, in any order.
4230         */
4231      public Object[] toArray()      public Object[] toArray()
4232      {      {
4233        return c.toArray();        return c.toArray();
4234      }      }
4235    
4236        /**
4237         * Copy the current contents of the underlying collection into an array.  If
4238         * the array passed as an argument has length less than the size of the
4239         * underlying collection, an array of the same run-time type as a, with a length
4240         * equal to the size of the underlying collection, is allocated using reflection.
4241         * Otherwise, a itself is used.  The elements of the underlying collection are
4242         * copied into it, and if there is space in the array, the following element is
4243         * set to null. The resultant array is returned.
4244         * Note: The fact that the following element is set to null is only useful
4245         * if it is known that this collection does not contain any null elements.
4246         *
4247         * @param a the array to copy this collection into.
4248         * @return an array containing the elements currently in the underlying
4249         *         collection, in any order.
4250         * @throws ArrayStoreException if the type of any element of the
4251         *         collection is not a subtype of the element type of a.
4252         */
4253      public <S> S[] toArray(S[] a)      public <S> S[] toArray(S[] a)
4254      {      {
4255        return c.toArray(a);        return c.toArray(a);
4256      }      }
4257    
4258        /**
4259         * A textual representation of the unmodifiable collection.
4260         *
4261         * @return The unmodifiable collection in the form of a <code>String</code>.
4262         */
4263      public String toString()      public String toString()
4264      {      {
4265        return c.toString();        return c.toString();
# Line 3072  public class Collections Line 4270  public class Collections
4270     * The implementation of the various iterator methods in the     * The implementation of the various iterator methods in the
4271     * unmodifiable classes.     * unmodifiable classes.
4272     *     *
4273     * @author Eric Blake <ebb9@email.byu.edu>     * @author Eric Blake (ebb9@email.byu.edu)
4274     */     */
4275    private static class UnmodifiableIterator<T> implements Iterator<T>    private static class UnmodifiableIterator<T> implements Iterator<T>
4276    {    {
# Line 3090  public class Collections Line 4288  public class Collections
4288        this.i = i;        this.i = i;
4289      }      }
4290    
4291        /**
4292         * Obtains the next element in the underlying collection.
4293         *
4294         * @return the next element in the collection.
4295         * @throws NoSuchElementException if there are no more elements.
4296         */
4297      public T next()      public T next()
4298      {      {
4299        return i.next();        return i.next();
4300      }      }
4301    
4302        /**
4303         * Tests whether there are still elements to be retrieved from the
4304         * underlying collection by <code>next()</code>.  When this method
4305         * returns <code>true</code>, an exception will not be thrown on calling
4306         * <code>next()</code>.
4307         *
4308         * @return <code>true</code> if there is at least one more element in the underlying
4309         *         collection.
4310         */
4311      public boolean hasNext()      public boolean hasNext()
4312      {      {
4313        return i.hasNext();        return i.hasNext();
4314      }      }
4315    
4316        /**
4317         * Blocks the removal of elements from the underlying collection by the
4318         * iterator.
4319         *
4320         * @throws UnsupportedOperationException as an unmodifiable collection
4321         *         does not support the removal of elements by its iterator.
4322         */
4323      public void remove()      public void remove()
4324      {      {
4325        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
# Line 3111  public class Collections Line 4331  public class Collections
4331     * "read-only" access, although changes in the backing list show up     * "read-only" access, although changes in the backing list show up
4332     * in this view. Attempts to modify the list directly, via iterators, or     * in this view. Attempts to modify the list directly, via iterators, or
4333     * via sublists, will fail with {@link UnsupportedOperationException}.     * via sublists, will fail with {@link UnsupportedOperationException}.
4334       * Although this view prevents changes to the structure of the list and
4335       * its elements, the values referenced by the objects in the list can
4336       * still be modified.  
4337     * <p>     * <p>
4338     *     *
4339     * The returned List implements Serializable, but can only be serialized if     * The returned List implements Serializable, but can only be serialized if
# Line 3134  public class Collections Line 4357  public class Collections
4357     * lists. This class name is required for compatibility with Sun's JDK     * lists. This class name is required for compatibility with Sun's JDK
4358     * serializability.     * serializability.
4359     *     *
4360     * @author Eric Blake <ebb9@email.byu.edu>     * @author Eric Blake (ebb9@email.byu.edu)
4361     */     */
4362    private static class UnmodifiableList<T> extends UnmodifiableCollection<T>    private static class UnmodifiableList<T> extends UnmodifiableCollection<T>
4363      implements List<T>      implements List<T>
# Line 3163  public class Collections Line 4386  public class Collections
4386        list = l;        list = l;
4387      }      }
4388    
4389        /**
4390         * Blocks the addition of an element to the underlying
4391         * list at a specific index.  This method never returns,
4392         * throwing an exception instead.
4393         *
4394         * @param index The index at which to place the new element.
4395         * @param o the object to add.
4396         * @throws UnsupportedOperationException as an unmodifiable
4397         *         list doesn't support the <code>add()</code> operation.
4398         */
4399      public void add(int index, T o)      public void add(int index, T o)
4400      {      {
4401        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4402      }      }
4403    
4404        /**
4405         * Blocks the addition of a collection of elements to the
4406         * underlying list at a specific index.  This method never
4407         * returns, throwing an exception instead.
4408         *
4409         * @param index The index at which to place the new element.
4410         * @param c the collections of objects to add.
4411         * @throws UnsupportedOperationException as an unmodifiable
4412         *         list doesn't support the <code>addAll()</code> operation.
4413         */
4414      public boolean addAll(int index, Collection<? extends T> c)      public boolean addAll(int index, Collection<? extends T> c)
4415      {      {
4416        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4417      }      }
4418    
4419        /**
4420         * Returns <code>true</code> if the object, o, is an instance of
4421         * <code>List</code> with the same size and elements
4422         * as the underlying list.
4423         *
4424         * @param o The object to compare.
4425         * @return <code>true</code> if o is equivalent to the underlying list.
4426         */
4427      public boolean equals(Object o)      public boolean equals(Object o)
4428      {      {
4429        return list.equals(o);        return list.equals(o);
4430      }      }
4431    
4432        /**
4433         * Retrieves the element at a given index in the underlying list.
4434         *
4435         * @param index the index of the element to be returned
4436         * @return the element at index index in this list
4437         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
4438         */
4439      public T get(int index)      public T get(int index)
4440      {      {
4441        return list.get(index);        return list.get(index);
4442      }      }
4443    
4444        /**
4445         * Computes the hash code for the underlying list.
4446         * The exact computation is described in the documentation
4447         * of the <code>List</code> interface.
4448         *
4449         * @return The hash code of the underlying list.
4450         * @see List#hashCode()
4451         */
4452      public int hashCode()      public int hashCode()
4453      {      {
4454        return list.hashCode();        return list.hashCode();
4455      }      }
4456    
4457        /**
4458         * Obtain the first index at which a given object is to be found in the
4459         * underlying list.
4460         *
4461         * @param o the object to search for
4462         * @return the least integer n such that <code>o == null ? get(n) == null :
4463         *         o.equals(get(n))</code>, or -1 if there is no such index.
4464         * @throws ClassCastException if the type of o is not a valid
4465         *         type for the underlying list.
4466         * @throws NullPointerException if o is null and the underlying
4467         *         list does not support null values.
4468         */
4469      public int indexOf(Object o)      public int indexOf(Object o)
4470      {      {
4471        return list.indexOf(o);        return list.indexOf(o);
4472      }      }
4473    
4474        /**
4475         * Obtain the last index at which a given object is to be found in the
4476         * underlying list.
4477         *
4478         * @return the greatest integer n such that <code>o == null ? get(n) == null
4479         *         : o.equals(get(n))</code>, or -1 if there is no such index.
4480         * @throws ClassCastException if the type of o is not a valid
4481         *         type for the underlying list.
4482         * @throws NullPointerException if o is null and the underlying
4483         *         list does not support null values.
4484         */
4485      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
4486      {      {
4487        return list.lastIndexOf(o);        return list.lastIndexOf(o);
4488      }      }
4489    
4490      /**
4491       * Obtains a list iterator over the underlying list, starting at the beginning
4492       * and maintaining the unmodifiable nature of this list.
4493       *
4494       * @return a <code>UnmodifiableListIterator</code> over the elements of the
4495       *         underlying list, in order, starting at the beginning.
4496       */
4497      public ListIterator<T> listIterator()      public ListIterator<T> listIterator()
4498      {      {
4499        return new UnmodifiableListIterator<T>(list.listIterator());        return new UnmodifiableListIterator<T>(list.listIterator());
4500      }      }
4501    
4502      /**
4503       * Obtains a list iterator over the underlying list, starting at the specified
4504       * index and maintaining the unmodifiable nature of this list.  An initial call
4505       * to <code>next()</code> will retrieve the element at the specified index,
4506       * and an initial call to <code>previous()</code> will retrieve the element
4507       * at index - 1.
4508       *
4509       *
4510       * @param index the position, between 0 and size() inclusive, to begin the
4511       *        iteration from.
4512       * @return a <code>UnmodifiableListIterator</code> over the elements of the
4513       *         underlying list, in order, starting at the specified index.
4514       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
4515       */
4516      public ListIterator<T> listIterator(int index)      public ListIterator<T> listIterator(int index)
4517      {      {
4518        return new UnmodifiableListIterator<T>(list.listIterator(index));        return new UnmodifiableListIterator<T>(list.listIterator(index));
4519      }      }
4520    
4521        /**
4522         * Blocks the removal of the element at the specified index.
4523         * This method never returns, throwing an exception instead.
4524         *
4525         * @param index The index of the element to remove.
4526         * @return the removed element.
4527         * @throws UnsupportedOperationException as an unmodifiable
4528         *         list does not support the <code>remove()</code>
4529         *         operation.
4530         */
4531      public T remove(int index)      public T remove(int index)
4532      {      {
4533        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4534      }      }
4535    
4536        /**
4537         * Blocks the replacement of the element at the specified index.
4538         * This method never returns, throwing an exception instead.
4539         *
4540         * @param index The index of the element to replace.
4541         * @param o The new object to place at the specified index.
4542         * @return the replaced element.
4543         * @throws UnsupportedOperationException as an unmodifiable
4544         *         list does not support the <code>set()</code>
4545         *         operation.
4546         */
4547      public T set(int index, T o)      public T set(int index, T o)
4548      {      {
4549        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4550      }      }
4551    
4552        /**
4553         * Obtain a List view of a subsection of the underlying list, from
4554         * fromIndex (inclusive) to toIndex (exclusive). If the two indices
4555         * are equal, the sublist is empty. The returned list will be
4556         * unmodifiable, like this list.  Changes to the elements of the
4557         * returned list will be reflected in the underlying list. No structural
4558         * modifications can take place in either list.
4559         *
4560         * @param fromIndex the index that the returned list should start from
4561         *        (inclusive).
4562         * @param toIndex the index that the returned list should go to (exclusive).
4563         * @return a List backed by a subsection of the underlying list.
4564         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
4565         *         || toIndex &gt; size() || fromIndex &gt; toIndex.
4566         */
4567      public List<T> subList(int fromIndex, int toIndex)      public List<T> subList(int fromIndex, int toIndex)
4568      {      {
4569        return unmodifiableList(list.subList(fromIndex, toIndex));        return unmodifiableList(list.subList(fromIndex, toIndex));
# Line 3274  public class Collections Line 4620  public class Collections
4620        this.li = li;        this.li = li;
4621      }      }
4622    
4623        /**
4624         * Blocks the addition of an object to the list underlying this iterator.
4625         * This method never returns, throwing an exception instead.
4626         *
4627         * @param o The object to add.
4628         * @throws UnsupportedOperationException as the iterator of an unmodifiable
4629         *         list does not support the <code>add()</code> operation.
4630         */
4631      public void add(T o)      public void add(T o)
4632      {      {
4633        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4634      }      }
4635    
4636        /**
4637         * Tests whether there are still elements to be retrieved from the
4638         * underlying collection by <code>previous()</code>.  When this method
4639         * returns <code>true</code>, an exception will not be thrown on calling
4640         * <code>previous()</code>.
4641         *
4642         * @return <code>true</code> if there is at least one more element prior to the
4643         *         current position in the underlying list.
4644         */
4645      public boolean hasPrevious()      public boolean hasPrevious()
4646      {      {
4647        return li.hasPrevious();        return li.hasPrevious();
4648      }      }
4649    
4650        /**
4651         * Find the index of the element that would be returned by a call to next.
4652         * If <code>hasNext()</code> returns <code>false</code>, this returns the list size.
4653         *
4654         * @return the index of the element that would be returned by
4655         *         <code>next()</code>.
4656         */
4657      public int nextIndex()      public int nextIndex()
4658      {      {
4659        return li.nextIndex();        return li.nextIndex();
4660      }      }
4661    
4662        /**
4663         * Obtains the previous element in the underlying list.
4664         *
4665         * @return the previous element in the list.
4666         * @throws NoSuchElementException if there are no more prior elements.
4667         */
4668      public T previous()      public T previous()
4669      {      {
4670        return li.previous();        return li.previous();
4671      }      }
4672    
4673        /**
4674         * Find the index of the element that would be returned by a call to
4675         * previous. If <code>hasPrevious()</code> returns <code>false</code>,
4676         * this returns -1.
4677         *
4678         * @return the index of the element that would be returned by
4679         *         <code>previous()</code>.
4680         */
4681      public int previousIndex()      public int previousIndex()
4682      {      {
4683        return li.previousIndex();        return li.previousIndex();
4684      }      }
4685    
4686        /**
4687         * Blocks the replacement of an element in the list underlying this
4688         * iterator.  This method never returns, throwing an exception instead.
4689         *
4690         * @param o The new object to replace the existing one.
4691         * @throws UnsupportedOperationException as the iterator of an unmodifiable
4692         *         list does not support the <code>set()</code> operation.
4693         */
4694      public void set(T o)      public void set(T o)
4695      {      {
4696        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
# Line 3310  public class Collections Line 4702  public class Collections
4702     * access, although changes in the backing map show up in this view.     * access, although changes in the backing map show up in this view.
4703     * Attempts to modify the map directly, or via collection views or their     * Attempts to modify the map directly, or via collection views or their
4704     * iterators will fail with {@link UnsupportedOperationException}.     * iterators will fail with {@link UnsupportedOperationException}.
4705       * Although this view prevents changes to the structure of the map and its
4706       * entries, the values referenced by the objects in the map can still be
4707       * modified.  
4708     * <p>     * <p>
4709     *     *
4710     * The returned Map implements Serializable, but can only be serialized if     * The returned Map implements Serializable, but can only be serialized if
# Line 3370  public class Collections Line 4765  public class Collections
4765          throw new NullPointerException();          throw new NullPointerException();
4766      }      }
4767    
4768        /**
4769         * Blocks the clearing of entries from the underlying map.
4770         * This method never returns, throwing an exception instead.
4771         *
4772         * @throws UnsupportedOperationException as an unmodifiable
4773         *         map does not support the <code>clear()</code> operation.
4774         */
4775      public void clear()      public void clear()
4776      {      {
4777        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4778      }      }
4779    
4780        /**
4781         * Returns <code>true</code> if the underlying map contains a mapping for
4782         * the given key.
4783         *
4784         * @param key the key to search for
4785         * @return <code>true</code> if the map contains the key
4786         * @throws ClassCastException if the key is of an inappropriate type
4787         * @throws NullPointerException if key is <code>null</code> but the map
4788         *         does not permit null keys
4789         */
4790      public boolean containsKey(Object key)      public boolean containsKey(Object key)
4791      {      {
4792        return m.containsKey(key);        return m.containsKey(key);
4793      }      }
4794    
4795        /**
4796         * Returns <code>true</code> if the underlying map contains at least one mapping with
4797         * the given value.  In other words, it returns <code>true</code> if a value v exists where
4798         * <code>(value == null ? v == null : value.equals(v))</code>. This usually
4799         * requires linear time.
4800         *
4801         * @param value the value to search for
4802         * @return <code>true</code> if the map contains the value
4803         * @throws ClassCastException if the type of the value is not a valid type
4804         *         for this map.
4805         * @throws NullPointerException if the value is null and the map doesn't
4806         *         support null values.
4807         */
4808      public boolean containsValue(Object value)      public boolean containsValue(Object value)
4809      {      {
4810        return m.containsValue(value);        return m.containsValue(value);
4811      }      }
4812    
4813        /**
4814         * Returns a unmodifiable set view of the entries in the underlying map.
4815         * Each element in the set is a unmodifiable variant of <code>Map.Entry</code>.
4816         * The set is backed by the map, so that changes in one show up in the other.
4817         * Modifications made while an iterator is in progress cause undefined
4818         * behavior.  These modifications are again limited to the values of
4819         * the objects.
4820         *
4821         * @return the unmodifiable set view of all mapping entries.
4822         * @see Map.Entry
4823         */
4824      public Set<Map.Entry<K, V>> entrySet()      public Set<Map.Entry<K, V>> entrySet()
4825      {      {
4826        if (entries == null)        if (entries == null)
# Line 3396  public class Collections Line 4832  public class Collections
4832       * The implementation of {@link UnmodifiableMap#entrySet()}. This class       * The implementation of {@link UnmodifiableMap#entrySet()}. This class
4833       * name is required for compatibility with Sun's JDK serializability.       * name is required for compatibility with Sun's JDK serializability.
4834       *       *
4835       * @author Eric Blake <ebb9@email.byu.edu>       * @author Eric Blake (ebb9@email.byu.edu)
4836       */       */
4837      private static final class UnmodifiableEntrySet<T>      private static final class UnmodifiableEntrySet<T>
4838        extends UnmodifiableSet<T>        extends UnmodifiableSet<T>
# Line 3421  public class Collections Line 4857  public class Collections
4857        {        {
4858          return new UnmodifiableIterator<T>(c.iterator())          return new UnmodifiableIterator<T>(c.iterator())
4859          {          {
4860              /**
4861               * Obtains the next element from the underlying set of
4862               * map entries.
4863               *
4864               * @return the next element in the collection.
4865               * @throws NoSuchElementException if there are no more elements.
4866               */
4867            public T next()            public T next()
4868            {            {
4869              final Map.Entry e = (Map.Entry) super.next();              final Map.Entry e = (Map.Entry) super.next();
4870              return (T) new Map.Entry()              return (T) new Map.Entry()
4871              {              {
4872                  /**
4873                   * Returns <code>true</code> if the object, o, is also a map entry with an
4874                   * identical key and value.
4875                   *
4876                   * @param o the object to compare.
4877                   * @return <code>true</code> if o is an equivalent map entry.
4878                   */
4879                public boolean equals(Object o)                public boolean equals(Object o)
4880                {                {
4881                  return e.equals(o);                  return e.equals(o);
4882                }                }
4883                  
4884                  /**
4885                   * Returns the key of this map entry.
4886                   *
4887                   * @return the key.
4888                   */
4889                public Object getKey()                public Object getKey()
4890                {                {
4891                  return e.getKey();                  return e.getKey();
4892                }                }
4893    
4894                  /**
4895                   * Returns the value of this map entry.
4896                   *
4897                   * @return the value.
4898                   */
4899                public Object getValue()                public Object getValue()
4900                {                {
4901                  return e.getValue();                  return e.getValue();
4902                }                }
4903                public int hashCode()  
4904                  /**
4905                   * Computes the hash code of this map entry.
4906                   * The computation is described in the <code>Map</code>
4907                   * interface documentation.
4908                   *
4909                   * @return the hash code of this entry.
4910                   * @see Map#hashCode()
4911                   */
4912                 public int hashCode()
4913                {                {
4914                  return e.hashCode();                  return e.hashCode();
4915                }                }
4916    
4917                  /**
4918                   * Blocks the alteration of the value of this map entry.
4919                   * This method never returns, throwing an exception instead.
4920                   *
4921                   * @param value The new value.
4922                   * @throws UnsupportedOperationException as an unmodifiable
4923                   *         map entry does not support the <code>setValue()</code>
4924                   *         operation.
4925                   */
4926                public Object setValue(Object value)                public Object setValue(Object value)
4927                {                {
4928                  throw new UnsupportedOperationException();                  throw new UnsupportedOperationException();
4929                }                }
4930    
4931                  /**
4932                   * Returns a textual representation of the map entry.
4933                   *
4934                   * @return The map entry as a <code>String</code>.
4935                   */
4936                public String toString()                public String toString()
4937                {                {
4938                  return e.toString();                  return e.toString();
# Line 3456  public class Collections Line 4943  public class Collections
4943        }        }
4944      } // class UnmodifiableEntrySet      } // class UnmodifiableEntrySet
4945    
4946        /**
4947         * Returns <code>true</code> if the object, o, is also an instance
4948         * of <code>Map</code> with an equal set of map entries.
4949         *
4950         * @param o The object to compare.
4951         * @return <code>true</code> if o is an equivalent map.
4952         */
4953      public boolean equals(Object o)      public boolean equals(Object o)
4954      {      {
4955        return m.equals(o);        return m.equals(o);
4956      }      }
4957    
4958        /**
4959         * Returns the value associated with the supplied key or
4960         * null if no such mapping exists.  An ambiguity can occur
4961         * if null values are accepted by the underlying map.
4962         * In this case, <code>containsKey()</code> can be used
4963         * to separate the two possible cases of a null result.
4964         *
4965         * @param key The key to look up.
4966         * @return the value associated with the key, or null if key not in map.
4967         * @throws ClassCastException if the key is an inappropriate type.
4968         * @throws NullPointerException if this map does not accept null keys.
4969         * @see #containsKey(Object)
4970         */
4971      public V get(Object key)      public V get(Object key)
4972      {      {
4973        return m.get(key);        return m.get(key);
4974      }      }
4975    
4976        /**
4977         * Blocks the addition of a new entry to the underlying map.
4978         * This method never returns, throwing an exception instead.
4979         *
4980         * @param key The new key.
4981         * @param value The new value.
4982         * @return the previous value of the key, or null if there was no mapping.
4983         * @throws UnsupportedOperationException as an unmodifiable
4984         *         map does not support the <code>put()</code> operation.
4985         */
4986      public V put(K key, V value)      public V put(K key, V value)
4987      {      {
4988        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4989      }      }
4990    
4991        /**
4992         * Computes the hash code for the underlying map, as the sum
4993         * of the hash codes of all entries.
4994         *
4995         * @return The hash code of the underlying map.
4996         * @see Map.Entry#hashCode()
4997         */
4998      public int hashCode()      public int hashCode()
4999      {      {
5000        return m.hashCode();        return m.hashCode();
5001      }      }
5002    
5003        /**
5004         * Returns <code>true</code> if the underlying map contains no entries.
5005         *
5006         * @return <code>true</code> if the map is empty.
5007         */
5008      public boolean isEmpty()      public boolean isEmpty()
5009      {      {
5010        return m.isEmpty();        return m.isEmpty();
5011      }      }
5012    
5013        /**
5014         * Returns a unmodifiable set view of the keys in the underlying map.
5015         * The set is backed by the map, so that changes in one show up in the other.
5016         * Modifications made while an iterator is in progress cause undefined
5017         * behavior.  These modifications are again limited to the values of
5018         * the keys.
5019         *
5020         * @return the set view of all keys.
5021         */
5022      public Set<K> keySet()      public Set<K> keySet()
5023      {      {
5024        if (keys == null)        if (keys == null)
# Line 3488  public class Collections Line 5026  public class Collections
5026        return keys;        return keys;
5027      }      }
5028    
5029        /**
5030         * Blocks the addition of the entries in the supplied map.
5031         * This method never returns, throwing an exception instead.
5032         *
5033         * @param m The map, the entries of which should be added
5034         *          to the underlying map.
5035         * @throws UnsupportedOperationException as an unmodifiable
5036         *         map does not support the <code>putAll</code> operation.
5037         */
5038      public void putAll(Map<? extends K, ? extends V> m)      public void putAll(Map<? extends K, ? extends V> m)
5039      {      {
5040        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
5041      }      }
5042    
5043        /**
5044         * Blocks the removal of an entry from the map.
5045         * This method never returns, throwing an exception instead.
5046         *
5047         * @param o The key of the entry to remove.
5048         * @return The value the key was associated with, or null
5049         *         if no such mapping existed.  Null is also returned
5050         *         if the removed entry had a null key.
5051         * @throws UnsupportedOperationException as an unmodifiable
5052         *         map does not support the <code>remove</code> operation.
5053         */
5054      public V remove(Object o)      public V remove(Object o)
5055      {      {
5056        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
5057      }      }
5058    
5059    
5060        /**
5061         * Returns the number of key-value mappings in the underlying map.
5062         * If there are more than Integer.MAX_VALUE mappings, Integer.MAX_VALUE
5063         * is returned.
5064         *
5065         * @return the number of mappings.
5066         */
5067      public int size()      public int size()
5068      {      {
5069        return m.size();        return m.size();
5070      }      }
5071    
5072        /**
5073         * Returns a textual representation of the map.
5074         *
5075         * @return The map in the form of a <code>String</code>.
5076         */
5077      public String toString()      public String toString()
5078      {      {
5079        return m.toString();        return m.toString();
5080      }      }
5081    
5082        /**
5083         * Returns a unmodifiable collection view of the values in the underlying map.
5084         * The collection is backed by the map, so that changes in one show up in the other.
5085         * Modifications made while an iterator is in progress cause undefined
5086         * behavior.  These modifications are again limited to the values of
5087         * the keys.
5088         *
5089         * @return the collection view of all values.
5090         */
5091      public Collection<V> values()      public Collection<V> values()
5092      {      {
5093        if (values == null)        if (values == null)
# Line 3521  public class Collections Line 5101  public class Collections
5101     * "read-only" access, although changes in the backing set show up     * "read-only" access, although changes in the backing set show up
5102     * in this view. Attempts to modify the set directly or via iterators     * in this view. Attempts to modify the set directly or via iterators
5103     * will fail with {@link UnsupportedOperationException}.     * will fail with {@link UnsupportedOperationException}.
5104       * Although this view prevents changes to the structure of the set and its
5105       * entries, the values referenced by the objects in the set can still be
5106       * modified.  
5107     * <p>     * <p>
5108     *     *
5109     * The returned Set implements Serializable, but can only be serialized if     * The returned Set implements Serializable, but can only be serialized if
# Line 3559  public class Collections Line 5142  public class Collections
5142        super(s);        super(s);
5143      }      }
5144    
5145        /**
5146         * Returns <code>true</code> if the object, o, is also an instance of
5147         * <code>Set</code> of the same size and with the same entries.
5148         *
5149         * @return <code>true</code> if o is an equivalent set.
5150         */
5151      public boolean equals(Object o)      public boolean equals(Object o)
5152      {      {
5153        return c.equals(o);        return c.equals(o);
5154      }      }
5155    
5156        /**
5157         * Computes the hash code of this set, as the sum of the
5158         * hash codes of all elements within the set.
5159         *
5160         * @return the hash code of the set.
5161         */
5162      public int hashCode()      public int hashCode()
5163      {      {
5164        return c.hashCode();        return c.hashCode();
# Line 3575  public class Collections Line 5170  public class Collections
5170     * "read-only" access, although changes in the backing map show up in this     * "read-only" access, although changes in the backing map show up in this
5171     * view. Attempts to modify the map directly, via subviews, via collection     * view. Attempts to modify the map directly, via subviews, via collection
5172     * views, or iterators, will fail with {@link UnsupportedOperationException}.     * views, or iterators, will fail with {@link UnsupportedOperationException}.
5173       * Although this view prevents changes to the structure of the map and its
5174       * entries, the values referenced by the objects in the map can still be
5175       * modified.  
5176     * <p>     * <p>
5177     *     *
5178     * The returned SortedMap implements Serializable, but can only be     * The returned SortedMap implements Serializable, but can only be
# Line 3622  public class Collections Line 5220  public class Collections
5220        this.sm = sm;        this.sm = sm;
5221      }      }
5222    
5223        /**
5224         * Returns the comparator used in sorting the underlying map,
5225         * or null if it is the keys' natural ordering.
5226         *
5227         * @return the sorting comparator.
5228         */
5229      public Comparator<? super K> comparator()      public Comparator<? super K> comparator()
5230      {      {
5231        return sm.comparator();        return sm.comparator();
5232      }      }
5233    
5234        /**
5235         * Returns the first (lowest sorted) key in the map.
5236         *
5237         * @return the first key.
5238         * @throws NoSuchElementException if this map is empty.
5239         */
5240      public K firstKey()      public K firstKey()
5241      {      {
5242        return sm.firstKey();        return sm.firstKey();
5243      }      }
5244    
5245        /**
5246         * Returns a unmodifiable view of the portion of the map strictly less
5247         * than toKey. The view is backed by the underlying map, so changes in
5248         * one show up in the other.  The submap supports all optional operations
5249         * of the original.  This operation is equivalent to
5250         * <code>subMap(firstKey(), toKey)</code>.
5251         * <p>
5252         *
5253         * The returned map throws an IllegalArgumentException any time a key is
5254         * used which is out of the range of toKey. Note that the endpoint, toKey,
5255         * is not included; if you want this value to be included, pass its successor
5256         * object in to toKey.  For example, for Integers, you could request
5257         * <code>headMap(new Integer(limit.intValue() + 1))</code>.
5258         *
5259         * @param toKey the exclusive upper range of the submap.
5260         * @return the submap.
5261         * @throws ClassCastException if toKey is not comparable to the map contents.
5262         * @throws IllegalArgumentException if this is a subMap, and toKey is out
5263         *         of range.
5264         * @throws NullPointerException if toKey is null but the map does not allow
5265         *         null keys.
5266         */
5267      public SortedMap<K, V> headMap(K toKey)      public SortedMap<K, V> headMap(K toKey)
5268      {      {
5269        return new UnmodifiableSortedMap<K, V>(sm.headMap(toKey));        return new UnmodifiableSortedMap<K, V>(sm.headMap(toKey));
5270      }      }
5271    
5272        /**
5273         * Returns the last (highest sorted) key in the map.
5274         *
5275         * @return the last key.
5276         * @throws NoSuchElementException if this map is empty.
5277         */
5278      public K lastKey()      public K lastKey()
5279      {      {
5280        return sm.lastKey();        return sm.lastKey();
5281      }      }
5282    
5283        /**
5284         * Returns a unmodifiable view of the portion of the map greater than or
5285         * equal to fromKey, and strictly less than toKey. The view is backed by
5286         * the underlying map, so changes in one show up in the other. The submap
5287         * supports all optional operations of the original.
5288         * <p>
5289         *
5290         * The returned map throws an IllegalArgumentException any time a key is
5291         * used which is out of the range of fromKey and toKey. Note that the
5292         * lower endpoint is included, but the upper is not; if you want to
5293         * change the inclusion or exclusion of an endpoint, pass its successor
5294         * object in instead.  For example, for Integers, you could request
5295         * <code>subMap(new Integer(lowlimit.intValue() + 1),
5296         * new Integer(highlimit.intValue() + 1))</code> to reverse
5297         * the inclusiveness of both endpoints.
5298         *
5299         * @param fromKey the inclusive lower range of the submap.
5300         * @param toKey the exclusive upper range of the submap.
5301         * @return the submap.
5302         * @throws ClassCastException if fromKey or toKey is not comparable to
5303         *         the map contents.
5304         * @throws IllegalArgumentException if this is a subMap, and fromKey or
5305         *         toKey is out of range.
5306         * @throws NullPointerException if fromKey or toKey is null but the map
5307         *         does not allow null keys.
5308         */
5309      public SortedMap<K, V> subMap(K fromKey, K toKey)      public SortedMap<K, V> subMap(K fromKey, K toKey)
5310      {      {
5311        return new UnmodifiableSortedMap<K, V>(sm.subMap(fromKey, toKey));        return new UnmodifiableSortedMap<K, V>(sm.subMap(fromKey, toKey));
5312      }      }
5313    
5314        /**
5315         * Returns a unmodifiable view of the portion of the map greater than or
5316         * equal to fromKey. The view is backed by the underlying map, so changes
5317         * in one show up in the other. The submap supports all optional operations
5318         * of the original.
5319         * <p>
5320         *
5321         * The returned map throws an IllegalArgumentException any time a key is
5322         * used which is out of the range of fromKey. Note that the endpoint, fromKey, is
5323         * included; if you do not want this value to be included, pass its successor object in
5324         * to fromKey.  For example, for Integers, you could request
5325         * <code>tailMap(new Integer(limit.intValue() + 1))</code>.
5326         *
5327         * @param fromKey the inclusive lower range of the submap
5328         * @return the submap
5329         * @throws ClassCastException if fromKey is not comparable to the map
5330         *         contents
5331         * @throws IllegalArgumentException if this is a subMap, and fromKey is out
5332         *         of range
5333         * @throws NullPointerException if fromKey is null but the map does not allow
5334         *         null keys
5335         */
5336      public SortedMap<K, V> tailMap(K fromKey)      public SortedMap<K, V> tailMap(K fromKey)
5337      {      {
5338        return new UnmodifiableSortedMap<K, V>(sm.tailMap(fromKey));        return new UnmodifiableSortedMap<K, V>(sm.tailMap(fromKey));
# Line 3658  public class Collections Line 5344  public class Collections
5344     * "read-only" access, although changes in the backing set show up     * "read-only" access, although changes in the backing set show up
5345     * in this view. Attempts to modify the set directly, via subsets, or via     * in this view. Attempts to modify the set directly, via subsets, or via
5346     * iterators, will fail with {@link UnsupportedOperationException}.     * iterators, will fail with {@link UnsupportedOperationException}.
5347       * Although this view prevents changes to the structure of the set and its
5348       * entries, the values referenced by the objects in the set can still be
5349       * modified.  
5350     * <p>     * <p>
5351     *     *
5352     * The returns SortedSet implements Serializable, but can only be     * The returns SortedSet implements Serializable, but can only be
# Line 3676  public class Collections Line 5365  public class Collections
5365     * The implementation of {@link #synchronizedSortedMap(SortedMap)}. This     * The implementation of {@link #synchronizedSortedMap(SortedMap)}. This
5366     * class name is required for compatibility with Sun's JDK serializability.     * class name is required for compatibility with Sun's JDK serializability.
5367     *     *
5368     * @author Eric Blake <ebb9@email.byu.edu>     * @author Eric Blake (ebb9@email.byu.edu)
5369     */     */
5370    private static class UnmodifiableSortedSet<T> extends UnmodifiableSet<T>    private static class UnmodifiableSortedSet<T> extends UnmodifiableSet<T>
5371      implements SortedSet<T>      implements SortedSet<T>
# Line 3704  public class Collections Line 5393  public class Collections
5393        this.ss = ss;        this.ss = ss;
5394      }      }
5395    
5396        /**
5397         * Returns the comparator used in sorting the underlying set,
5398         * or null if it is the elements' natural ordering.
5399         *
5400         * @return the sorting comparator
5401         */
5402      public Comparator<? super T> comparator()      public Comparator<? super T> comparator()
5403      {      {
5404        return ss.comparator();        return ss.comparator();
5405      }      }
5406    
5407        /**
5408         * Returns the first (lowest sorted) element in the underlying
5409         * set.
5410         *
5411         * @return the first element.
5412         * @throws NoSuchElementException if the set is empty.
5413         */
5414      public T first()      public T first()
5415      {      {
5416        return ss.first();        return ss.first();
5417      }      }
5418    
5419        /**
5420         * Returns a unmodifiable view of the portion of the set strictly
5421         * less than toElement. The view is backed by the underlying set,
5422         * so changes in one show up in the other.  The subset supports
5423         * all optional operations of the original.  This operation
5424         * is equivalent to <code>subSet(first(), toElement)</code>.
5425         * <p>
5426         *
5427         * The returned set throws an IllegalArgumentException any time an element is
5428         * used which is out of the range of toElement. Note that the endpoint, toElement,
5429         * is not included; if you want this value included, pass its successor object in to
5430         * toElement.  For example, for Integers, you could request
5431         * <code>headSet(new Integer(limit.intValue() + 1))</code>.
5432         *
5433         * @param toElement the exclusive upper range of the subset
5434         * @return the subset.
5435         * @throws ClassCastException if toElement is not comparable to the set
5436         *         contents.
5437         * @throws IllegalArgumentException if this is a subSet, and toElement is out
5438         *         of range.
5439         * @throws NullPointerException if toElement is null but the set does not
5440         *         allow null elements.
5441         */
5442      public SortedSet<T> headSet(T toElement)      public SortedSet<T> headSet(T toElement)
5443      {      {
5444        return new UnmodifiableSortedSet<T>(ss.headSet(toElement));        return new UnmodifiableSortedSet<T>(ss.headSet(toElement));
5445      }      }
5446    
5447        /**
5448         * Returns the last (highest sorted) element in the underlying
5449         * set.
5450         *
5451         * @return the last element.
5452         * @throws NoSuchElementException if the set is empty.
5453         */
5454      public T last()      public T last()
5455      {      {
5456        return ss.last();        return ss.last();
5457      }      }
5458    
5459        /**
5460         * Returns a unmodifiable view of the portion of the set greater than or
5461         * equal to fromElement, and strictly less than toElement. The view is backed by
5462         * the underlying set, so changes in one show up in the other. The subset
5463         * supports all optional operations of the original.
5464         * <p>
5465         *
5466         * The returned set throws an IllegalArgumentException any time an element is
5467         * used which is out of the range of fromElement and toElement. Note that the
5468         * lower endpoint is included, but the upper is not; if you want to
5469         * change the inclusion or exclusion of an endpoint, pass its successor
5470         * object in instead.  For example, for Integers, you can request
5471         * <code>subSet(new Integer(lowlimit.intValue() + 1),
5472         * new Integer(highlimit.intValue() + 1))</code> to reverse
5473         * the inclusiveness of both endpoints.
5474         *
5475         * @param fromElement the inclusive lower range of the subset.
5476         * @param toElement the exclusive upper range of the subset.
5477         * @return the subset.
5478         * @throws ClassCastException if fromElement or toElement is not comparable
5479         *         to the set contents.
5480         * @throws IllegalArgumentException if this is a subSet, and fromElement or
5481         *         toElement is out of range.
5482         * @throws NullPointerException if fromElement or toElement is null but the
5483         *         set does not allow null elements.
5484         */
5485      public SortedSet<T> subSet(T fromElement, T toElement)      public SortedSet<T> subSet(T fromElement, T toElement)
5486      {      {
5487        return new UnmodifiableSortedSet<T>(ss.subSet(fromElement, toElement));        return new UnmodifiableSortedSet<T>(ss.subSet(fromElement, toElement));
5488      }      }
5489    
5490        /**
5491         * Returns a unmodifiable view of the portion of the set greater than or equal to
5492         * fromElement. The view is backed by the underlying set, so changes in one show up
5493         * in the other. The subset supports all optional operations of the original.
5494         * <p>
5495         *
5496         * The returned set throws an IllegalArgumentException any time an element is
5497         * used which is out of the range of fromElement. Note that the endpoint,
5498         * fromElement, is included; if you do not want this value to be included, pass its
5499         * successor object in to fromElement.  For example, for Integers, you could request
5500         * <code>tailSet(new Integer(limit.intValue() + 1))</code>.
5501         *
5502         * @param fromElement the inclusive lower range of the subset
5503         * @return the subset.
5504         * @throws ClassCastException if fromElement is not comparable to the set
5505         *         contents.
5506         * @throws IllegalArgumentException if this is a subSet, and fromElement is
5507         *         out of range.
5508         * @throws NullPointerException if fromElement is null but the set does not
5509         *         allow null elements.
5510         */
5511      public SortedSet<T> tailSet(T fromElement)      public SortedSet<T> tailSet(T fromElement)
5512      {      {
5513        return new UnmodifiableSortedSet<T>(ss.tailSet(fromElement));        return new UnmodifiableSortedSet<T>(ss.tailSet(fromElement));

Legend:
Removed from v.1.28.2.9  
changed lines
  Added in v.1.28.2.10

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26