/[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.31 by mkoch, Mon Sep 27 10:58:56 2004 UTC revision 1.32 by gnu_andrew, Wed Oct 20 20:05:24 2004 UTC
# Line 74  public class Collections Line 74  public class Collections
74    /**    /**
75     * Constant used to decide cutoff for when a non-RandomAccess list should     * Constant used to decide cutoff for when a non-RandomAccess list should
76     * be treated as sequential-access. Basically, quadratic behavior is     * be treated as sequential-access. Basically, quadratic behavior is
77     * 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
78     * 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.
79     */     */
80    private static final int LARGE_LIST_SIZE = 16;    private static final int LARGE_LIST_SIZE = 16;
# Line 87  public class Collections Line 87  public class Collections
87     * and exceeds a large (unspecified) size should be sequential.     * and exceeds a large (unspecified) size should be sequential.
88     *     *
89     * @param l the list to check     * @param l the list to check
90     * @return true if it should be treated as sequential-access     * @return <code>true</code> if it should be treated as sequential-access
91     */     */
92    private static boolean isSequential(List l)    private static boolean isSequential(List l)
93    {    {
# Line 130  public class Collections Line 130  public class Collections
130    
131      /**      /**
132       * The size: always 0!       * The size: always 0!
133         * @return 0.
134       */       */
135      public int size()      public int size()
136      {      {
# Line 138  public class Collections Line 139  public class Collections
139    
140      /**      /**
141       * Returns an iterator that does not iterate.       * Returns an iterator that does not iterate.
142         * @return A non-iterating iterator.
143       */       */
144      // This is really cheating! I think it's perfectly valid, though.      // This is really cheating! I think it's perfectly valid, though.
145      public Iterator iterator()      public Iterator iterator()
# Line 149  public class Collections Line 151  public class Collections
151      // advantage by not allocating unnecessary iterators in AbstractSet.      // advantage by not allocating unnecessary iterators in AbstractSet.
152      /**      /**
153       * The empty set never contains anything.       * The empty set never contains anything.
154         * @param o The object to search for.
155         * @return <code>false</code>.
156       */       */
157      public boolean contains(Object o)      public boolean contains(Object o)
158      {      {
# Line 157  public class Collections Line 161  public class Collections
161    
162      /**      /**
163       * This is true only if the given collection is also empty.       * This is true only if the given collection is also empty.
164         * @param c The collection of objects which are to be compared
165         *          against the members of this set.
166         * @return <code>true</code> if c is empty.
167       */       */
168      public boolean containsAll(Collection c)      public boolean containsAll(Collection c)
169      {      {
# Line 165  public class Collections Line 172  public class Collections
172    
173      /**      /**
174       * Equal only if the other set is empty.       * Equal only if the other set is empty.
175         * @param o The object to compare with this set.
176         * @return <code>true</code> if o is an empty instance of <code>Set</code>.
177       */       */
178      public boolean equals(Object o)      public boolean equals(Object o)
179      {      {
# Line 173  public class Collections Line 182  public class Collections
182    
183      /**      /**
184       * The hashcode is always 0.       * The hashcode is always 0.
185         * @return 0.
186       */       */
187      public int hashCode()      public int hashCode()
188      {      {
# Line 180  public class Collections Line 190  public class Collections
190      }      }
191    
192      /**      /**
193       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
194         * @param o The object to remove.
195         * @return <code>false</code>.
196       */       */
197      public boolean remove(Object o)      public boolean remove(Object o)
198      {      {
# Line 188  public class Collections Line 200  public class Collections
200      }      }
201    
202      /**      /**
203       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
204         * @param c The collection of objects which should
205         *          all be removed from this set.
206         * @return <code>false</code>.
207       */       */
208      public boolean removeAll(Collection c)      public boolean removeAll(Collection c)
209      {      {
# Line 196  public class Collections Line 211  public class Collections
211      }      }
212    
213      /**      /**
214       * Always succeeds with false result.       * Always succeeds with a <code>false</code> result.
215         * @param c The collection of objects which should
216         *          all be retained within this set.
217         * @return <code>false</code>.
218       */       */
219      public boolean retainAll(Collection c)      public boolean retainAll(Collection c)
220      {      {
# Line 205  public class Collections Line 223  public class Collections
223    
224      /**      /**
225       * The array is always empty.       * The array is always empty.
226         * @return A new array with a size of 0.
227       */       */
228      public Object[] toArray()      public Object[] toArray()
229      {      {
# Line 213  public class Collections Line 232  public class Collections
232    
233      /**      /**
234       * We don't even need to use reflection!       * We don't even need to use reflection!
235         * @param a An existing array, which can be empty.
236         * @return The original array with any existing
237         *         initial element set to null.
238       */       */
239      public Object[] toArray(Object[] a)      public Object[] toArray(Object[] a)
240      {      {
# Line 223  public class Collections Line 245  public class Collections
245    
246      /**      /**
247       * The string never changes.       * The string never changes.
248         *
249         * @return the string "[]".
250       */       */
251      public String toString()      public String toString()
252      {      {
# Line 260  public class Collections Line 284  public class Collections
284    
285      /**      /**
286       * The size is always 0.       * The size is always 0.
287         * @return 0.
288       */       */
289      public int size()      public int size()
290      {      {
# Line 267  public class Collections Line 292  public class Collections
292      }      }
293    
294      /**      /**
295       * No matter the index, it is out of bounds.       * No matter the index, it is out of bounds.  This
296         * method never returns, throwing an exception instead.
297         *
298         * @param index The index of the element to retrieve.
299         * @return the object at the specified index.
300         * @throws IndexOutofBoundsException as any given index
301         *         is outside the bounds of an empty array.
302       */       */
303      public Object get(int index)      public Object get(int index)
304      {      {
# Line 278  public class Collections Line 309  public class Collections
309      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
310      /**      /**
311       * Never contains anything.       * Never contains anything.
312         * @param o The object to search for.
313         * @return <code>false</code>.
314       */       */
315      public boolean contains(Object o)      public boolean contains(Object o)
316      {      {
# Line 286  public class Collections Line 319  public class Collections
319    
320      /**      /**
321       * This is true only if the given collection is also empty.       * This is true only if the given collection is also empty.
322         * @param c The collection of objects, which should be compared
323         *          against the members of this list.
324         * @return <code>true</code> if c is also empty.
325       */       */
326      public boolean containsAll(Collection c)      public boolean containsAll(Collection c)
327      {      {
# Line 293  public class Collections Line 329  public class Collections
329      }      }
330    
331      /**      /**
332       * Equal only if the other set is empty.       * Equal only if the other list is empty.
333         * @param o The object to compare against this list.
334         * @return <code>true</code> if o is also an empty instance of
335         *         <code>List</code>.
336       */       */
337      public boolean equals(Object o)      public boolean equals(Object o)
338      {      {
# Line 302  public class Collections Line 341  public class Collections
341    
342      /**      /**
343       * The hashcode is always 1.       * The hashcode is always 1.
344         * @return 1.
345       */       */
346      public int hashCode()      public int hashCode()
347      {      {
# Line 310  public class Collections Line 350  public class Collections
350    
351      /**      /**
352       * Returns -1.       * Returns -1.
353         * @param o The object to search for.
354         * @return -1.
355       */       */
356      public int indexOf(Object o)      public int indexOf(Object o)
357      {      {
# Line 318  public class Collections Line 360  public class Collections
360    
361      /**      /**
362       * Returns -1.       * Returns -1.
363         * @param o The object to search for.
364         * @return -1.
365       */       */
366      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
367      {      {
# Line 325  public class Collections Line 369  public class Collections
369      }      }
370    
371      /**      /**
372       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
373         * @param o The object to remove.
374         * @return -1.
375       */       */
376      public boolean remove(Object o)      public boolean remove(Object o)
377      {      {
# Line 333  public class Collections Line 379  public class Collections
379      }      }
380    
381      /**      /**
382       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
383         * @param c The collection of objects which should
384         *          all be removed from this list.
385         * @return <code>false</code>.
386       */       */
387      public boolean removeAll(Collection c)      public boolean removeAll(Collection c)
388      {      {
# Line 341  public class Collections Line 390  public class Collections
390      }      }
391    
392      /**      /**
393       * Always succeeds with false result.       * Always succeeds with <code>false</code> result.
394         * @param c The collection of objects which should
395         *          all be retained within this list.
396         * @return <code>false</code>.
397       */       */
398      public boolean retainAll(Collection c)      public boolean retainAll(Collection c)
399      {      {
# Line 350  public class Collections Line 402  public class Collections
402    
403      /**      /**
404       * The array is always empty.       * The array is always empty.
405         * @return A new array with a size of 0.
406       */       */
407      public Object[] toArray()      public Object[] toArray()
408      {      {
# Line 358  public class Collections Line 411  public class Collections
411    
412      /**      /**
413       * We don't even need to use reflection!       * We don't even need to use reflection!
414         * @param a An existing array, which can be empty.
415         * @return The original array with any existing
416         *         initial element set to null.
417       */       */
418      public Object[] toArray(Object[] a)      public Object[] toArray(Object[] a)
419      {      {
# Line 368  public class Collections Line 424  public class Collections
424    
425      /**      /**
426       * The string never changes.       * The string never changes.
427         *
428         * @return the string "[]".
429       */       */
430      public String toString()      public String toString()
431      {      {
# Line 404  public class Collections Line 462  public class Collections
462    
463      /**      /**
464       * There are no entries.       * There are no entries.
465         * @return The empty set.
466       */       */
467      public Set entrySet()      public Set entrySet()
468      {      {
# Line 414  public class Collections Line 473  public class Collections
473      // advantage by not allocating unnecessary iterators in AbstractMap.      // advantage by not allocating unnecessary iterators in AbstractMap.
474      /**      /**
475       * No entries!       * No entries!
476         * @param key The key to search for.
477         * @return <code>false</code>.
478       */       */
479      public boolean containsKey(Object key)      public boolean containsKey(Object key)
480      {      {
# Line 422  public class Collections Line 483  public class Collections
483    
484      /**      /**
485       * No entries!       * No entries!
486         * @param value The value to search for.
487         * @return <code>false</code>.
488       */       */
489      public boolean containsValue(Object value)      public boolean containsValue(Object value)
490      {      {
# Line 430  public class Collections Line 493  public class Collections
493    
494      /**      /**
495       * Equal to all empty maps.       * Equal to all empty maps.
496         * @param o The object o to compare against this map.
497         * @return <code>true</code> if o is also an empty instance of
498         *         <code>Map</code>.
499       */       */
500      public boolean equals(Object o)      public boolean equals(Object o)
501      {      {
# Line 438  public class Collections Line 504  public class Collections
504    
505      /**      /**
506       * No mappings, so this returns null.       * No mappings, so this returns null.
507         * @param o The key of the object to retrieve.
508         * @return null.
509       */       */
510      public Object get(Object o)      public Object get(Object o)
511      {      {
# Line 446  public class Collections Line 514  public class Collections
514    
515      /**      /**
516       * The hashcode is always 0.       * The hashcode is always 0.
517         * @return 0.
518       */       */
519      public int hashCode()      public int hashCode()
520      {      {
# Line 454  public class Collections Line 523  public class Collections
523    
524      /**      /**
525       * No entries.       * No entries.
526         * @return The empty set.
527       */       */
528      public Set keySet()      public Set keySet()
529      {      {
# Line 462  public class Collections Line 532  public class Collections
532    
533      /**      /**
534       * Remove always succeeds, with null result.       * Remove always succeeds, with null result.
535         * @param o The key of the mapping to remove.
536         * @return null, as there is never a mapping for o.
537       */       */
538      public Object remove(Object o)      public Object remove(Object o)
539      {      {
# Line 470  public class Collections Line 542  public class Collections
542    
543      /**      /**
544       * Size is always 0.       * Size is always 0.
545         * @return 0.
546       */       */
547      public int size()      public int size()
548      {      {
# Line 479  public class Collections Line 552  public class Collections
552      /**      /**
553       * No entries. Technically, EMPTY_SET, while more specific than a general       * No entries. Technically, EMPTY_SET, while more specific than a general
554       * Collection, will work. Besides, that's what the JDK uses!       * Collection, will work. Besides, that's what the JDK uses!
555         * @return The empty set.
556       */       */
557      public Collection values()      public Collection values()
558      {      {
# Line 487  public class Collections Line 561  public class Collections
561    
562      /**      /**
563       * The string never changes.       * The string never changes.
564         *
565         * @return the string "[]".
566       */       */
567      public String toString()      public String toString()
568      {      {
# Line 663  public class Collections Line 739  public class Collections
739      final Iterator i = c.iterator();      final Iterator i = c.iterator();
740      return new Enumeration()      return new Enumeration()
741      {      {
742          /**
743           * Returns <code>true</code> if there are more elements to
744           * be enumerated.
745           *
746           * @return The result of <code>hasNext()</code>
747           *         called on the underlying iterator.
748           */
749        public final boolean hasMoreElements()        public final boolean hasMoreElements()
750        {        {
751          return i.hasNext();          return i.hasNext();
752        }        }
753    
754          /**
755           * Returns the next element to be enumerated.
756           *
757           * @return The result of <code>next()</code>
758           *         called on the underlying iterator.
759           */
760        public final Object nextElement()        public final Object nextElement()
761        {        {
762          return i.next();          return i.next();
# Line 906  public class Collections Line 996  public class Collections
996    
997      /**      /**
998       * The size is fixed.       * The size is fixed.
999         * @return The size of the list.
1000       */       */
1001      public int size()      public int size()
1002      {      {
# Line 914  public class Collections Line 1005  public class Collections
1005    
1006      /**      /**
1007       * The same element is returned.       * The same element is returned.
1008         * @param index The index of the element to be returned (irrelevant
1009         *        as the list contains only copies of <code>element</code>).
1010         * @return The element used by this list.
1011       */       */
1012      public Object get(int index)      public Object get(int index)
1013      {      {
# Line 926  public class Collections Line 1020  public class Collections
1020      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
1021      /**      /**
1022       * This list only contains one element.       * This list only contains one element.
1023         * @param o The object to search for.
1024         * @return <code>true</code> if o is the element used by this list.
1025       */       */
1026      public boolean contains(Object o)      public boolean contains(Object o)
1027      {      {
# Line 934  public class Collections Line 1030  public class Collections
1030    
1031      /**      /**
1032       * The index is either 0 or -1.       * The index is either 0 or -1.
1033         * @param o The object to find the index of.
1034         * @return 0 if <code>o == element</code>, -1 if not.
1035       */       */
1036      public int indexOf(Object o)      public int indexOf(Object o)
1037      {      {
# Line 942  public class Collections Line 1040  public class Collections
1040    
1041      /**      /**
1042       * The index is either n-1 or -1.       * The index is either n-1 or -1.
1043         * @param o The object to find the last index of.
1044         * @return The last index in the list if <code>o == element</code>,
1045         *         -1 if not.
1046       */       */
1047      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
1048      {      {
# Line 950  public class Collections Line 1051  public class Collections
1051    
1052      /**      /**
1053       * A subList is just another CopiesList.       * A subList is just another CopiesList.
1054         * @param from The starting bound of the sublist.
1055         * @param to The ending bound of the sublist.
1056         * @return A list of copies containing <code>from - to</code>
1057         *         elements, all of which are equal to the element
1058         *         used by this list.
1059       */       */
1060      public List subList(int from, int to)      public List subList(int from, int to)
1061      {      {
# Line 960  public class Collections Line 1066  public class Collections
1066    
1067      /**      /**
1068       * The array is easy.       * The array is easy.
1069         * @return An array of size n filled with copies of
1070         *         the element used by this list.
1071       */       */
1072      public Object[] toArray()      public Object[] toArray()
1073      {      {
# Line 970  public class Collections Line 1078  public class Collections
1078    
1079      /**      /**
1080       * The string is easy to generate.       * The string is easy to generate.
1081         * @return A string representation of the list.
1082       */       */
1083      public String toString()      public String toString()
1084      {      {
# Line 989  public class Collections Line 1098  public class Collections
1098     * @param list the list to iterate over     * @param list the list to iterate over
1099     * @param oldval the element to replace     * @param oldval the element to replace
1100     * @param newval the new value for the element     * @param newval the new value for the element
1101     * @return true if a replacement occurred     * @return <code>true</code> if a replacement occurred.
1102     * @throws UnsupportedOperationException if the list iterator does not allow     * @throws UnsupportedOperationException if the list iterator does not allow
1103     *         for the set operation     *         for the set operation
1104     * @throws ClassCastException newval is of a type which cannot be added     * @throws ClassCastException if newval is of a type which cannot be added
1105     *         to the list     *         to the list
1106     * @throws IllegalArgumentException some other aspect of newval stops     * @throws IllegalArgumentException if some other aspect of newval stops
1107     *         it being added to the list     *         it being added to the list
1108     * @since 1.4     * @since 1.4
1109     */     */
# Line 1302  public class Collections Line 1411  public class Collections
1411    
1412      /**      /**
1413       * The size: always 1!       * The size: always 1!
1414         * @return 1.
1415       */       */
1416      public int size()      public int size()
1417      {      {
# Line 1315  public class Collections Line 1425  public class Collections
1425      {      {
1426        return new Iterator()        return new Iterator()
1427        {        {
1428            /**
1429             * Flag to indicate whether or not the element has
1430             * been retrieved.
1431             */
1432          private boolean hasNext = true;          private boolean hasNext = true;
1433    
1434            /**
1435             * Returns <code>true</code> if elements still remain to be
1436             * iterated through.
1437             *
1438             * @return <code>true</code> if the element has not yet been returned.
1439             */
1440          public boolean hasNext()          public boolean hasNext()
1441          {          {
1442            return hasNext;            return hasNext;
1443          }          }
1444    
1445            /**
1446             * Returns the element.
1447             *
1448             * @return The element used by this singleton.
1449             * @throws NoSuchElementException if the object
1450             *         has already been retrieved.
1451             */
1452          public Object next()          public Object next()
1453          {          {
1454            if (hasNext)            if (hasNext)
# Line 1333  public class Collections Line 1460  public class Collections
1460              throw new NoSuchElementException();              throw new NoSuchElementException();
1461          }          }
1462    
1463            /**
1464             * Removes the element from the singleton.
1465             * As this set is immutable, this will always
1466             * throw an exception.
1467             *
1468             * @throws UnsupportedOperationException as the
1469             *         singleton set doesn't support
1470             *         <code>remove()</code>.
1471             */
1472          public void remove()          public void remove()
1473          {          {
1474            throw new UnsupportedOperationException();            throw new UnsupportedOperationException();
# Line 1344  public class Collections Line 1480  public class Collections
1480      // advantage by not allocating unnecessary iterators in AbstractSet.      // advantage by not allocating unnecessary iterators in AbstractSet.
1481      /**      /**
1482       * The set only contains one element.       * The set only contains one element.
1483         *
1484         * @param o The object to search for.
1485         * @return <code>true</code> if o == the element of the singleton.
1486       */       */
1487      public boolean contains(Object o)      public boolean contains(Object o)
1488      {      {
# Line 1352  public class Collections Line 1491  public class Collections
1491    
1492      /**      /**
1493       * This is true if the other collection only contains the element.       * This is true if the other collection only contains the element.
1494         *
1495         * @param c A collection to compare against this singleton.
1496         * @return <code>true</code> if c only contains either no elements or
1497         *         elements equal to the element in this singleton.
1498       */       */
1499      public boolean containsAll(Collection c)      public boolean containsAll(Collection c)
1500      {      {
# Line 1365  public class Collections Line 1508  public class Collections
1508    
1509      /**      /**
1510       * The hash is just that of the element.       * The hash is just that of the element.
1511         *
1512         * @return The hashcode of the element.
1513       */       */
1514      public int hashCode()      public int hashCode()
1515      {      {
# Line 1373  public class Collections Line 1518  public class Collections
1518    
1519      /**      /**
1520       * Returning an array is simple.       * Returning an array is simple.
1521         *
1522         * @return An array containing the element.
1523       */       */
1524      public Object[] toArray()      public Object[] toArray()
1525      {      {
# Line 1381  public class Collections Line 1528  public class Collections
1528    
1529      /**      /**
1530       * Obvious string.       * Obvious string.
1531         *
1532         * @return The string surrounded by enclosing
1533         *         square brackets.
1534       */       */
1535      public String toString()      public String toString()
1536      {      {
# Line 1434  public class Collections Line 1584  public class Collections
1584    
1585      /**      /**
1586       * The size: always 1!       * The size: always 1!
1587         * @return 1.
1588       */       */
1589      public int size()      public int size()
1590      {      {
# Line 1442  public class Collections Line 1593  public class Collections
1593    
1594      /**      /**
1595       * Only index 0 is valid.       * Only index 0 is valid.
1596         * @param index The index of the element
1597         *        to retrieve.
1598         * @return The singleton's element if the
1599         *         index is 0.
1600         * @throws IndexOutOfBoundsException if
1601         *         index is not 0.
1602       */       */
1603      public Object get(int index)      public Object get(int index)
1604      {      {
# Line 1454  public class Collections Line 1611  public class Collections
1611      // advantage by not allocating unnecessary iterators in AbstractList.      // advantage by not allocating unnecessary iterators in AbstractList.
1612      /**      /**
1613       * The set only contains one element.       * The set only contains one element.
1614         *
1615         * @param o The object to search for.
1616         * @return <code>true</code> if o == the singleton element.
1617       */       */
1618      public boolean contains(Object o)      public boolean contains(Object o)
1619      {      {
# Line 1462  public class Collections Line 1622  public class Collections
1622    
1623      /**      /**
1624       * This is true if the other collection only contains the element.       * This is true if the other collection only contains the element.
1625         *
1626         * @param c A collection to compare against this singleton.
1627         * @return <code>true</code> if c only contains either no elements or
1628         *         elements equal to the element in this singleton.
1629       */       */
1630      public boolean containsAll(Collection c)      public boolean containsAll(Collection c)
1631      {      {
# Line 1475  public class Collections Line 1639  public class Collections
1639    
1640      /**      /**
1641       * Speed up the hashcode computation.       * Speed up the hashcode computation.
1642         *
1643         * @return The hashcode of the list, based
1644         *         on the hashcode of the singleton element.
1645       */       */
1646      public int hashCode()      public int hashCode()
1647      {      {
# Line 1483  public class Collections Line 1650  public class Collections
1650    
1651      /**      /**
1652       * Either the list has it or not.       * Either the list has it or not.
1653         *
1654         * @param o The object to find the first index of.
1655         * @return 0 if o is the singleton element, -1 if not.
1656       */       */
1657      public int indexOf(Object o)      public int indexOf(Object o)
1658      {      {
# Line 1491  public class Collections Line 1661  public class Collections
1661    
1662      /**      /**
1663       * Either the list has it or not.       * Either the list has it or not.
1664         *
1665         * @param o The object to find the last index of.
1666         * @return 0 if o is the singleton element, -1 if not.
1667       */       */
1668      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
1669      {      {
# Line 1499  public class Collections Line 1672  public class Collections
1672    
1673      /**      /**
1674       * Sublists are limited in scope.       * Sublists are limited in scope.
1675         *
1676         * @param from The starting bound for the sublist.
1677         * @param to The ending bound for the sublist.
1678         * @return Either an empty list if both bounds are
1679         *         0 or 1, or this list if the bounds are 0 and 1.
1680         * @throws IllegalArgumentException if <code>from > to</code>
1681         * @throws IndexOutOfBoundsException if either bound is greater
1682         *         than 1.
1683       */       */
1684      public List subList(int from, int to)      public List subList(int from, int to)
1685      {      {
# Line 1513  public class Collections Line 1694  public class Collections
1694    
1695      /**      /**
1696       * Returning an array is simple.       * Returning an array is simple.
1697         *
1698         * @return An array containing the element.
1699       */       */
1700      public Object[] toArray()      public Object[] toArray()
1701      {      {
# Line 1521  public class Collections Line 1704  public class Collections
1704    
1705      /**      /**
1706       * Obvious string.       * Obvious string.
1707         *
1708         * @return The string surrounded by enclosing
1709         *         square brackets.
1710       */       */
1711      public String toString()      public String toString()
1712      {      {
# Line 1587  public class Collections Line 1773  public class Collections
1773    
1774      /**      /**
1775       * There is a single immutable entry.       * There is a single immutable entry.
1776         *
1777         * @return A singleton containing the map entry.
1778       */       */
1779      public Set entrySet()      public Set entrySet()
1780      {      {
1781        if (entries == null)        if (entries == null)
1782          entries = singleton(new AbstractMap.BasicMapEntry(k, v)          entries = singleton(new AbstractMap.BasicMapEntry(k, v)
1783          {          {
1784              /**
1785               * Sets the value of the map entry to the supplied value.
1786               * An exception is always thrown, as the map is immutable.
1787               *
1788               * @param o The new value.
1789               * @return The old value.
1790               * @throws UnsupportedOperationException as setting the value
1791               *         is not supported.
1792               */
1793            public Object setValue(Object o)            public Object setValue(Object o)
1794            {            {
1795              throw new UnsupportedOperationException();              throw new UnsupportedOperationException();
# Line 1605  public class Collections Line 1802  public class Collections
1802      // advantage by not allocating unnecessary iterators in AbstractMap.      // advantage by not allocating unnecessary iterators in AbstractMap.
1803      /**      /**
1804       * Single entry.       * Single entry.
1805         *
1806         * @param key The key to look for.
1807         * @return <code>true</code> if the key is the same as the one used by
1808         *         this map.
1809       */       */
1810      public boolean containsKey(Object key)      public boolean containsKey(Object key)
1811      {      {
# Line 1613  public class Collections Line 1814  public class Collections
1814    
1815      /**      /**
1816       * Single entry.       * Single entry.
1817         *
1818         * @param value The value to look for.
1819         * @return <code>true</code> if the value is the same as the one used by
1820         *         this map.
1821       */       */
1822      public boolean containsValue(Object value)      public boolean containsValue(Object value)
1823      {      {
# Line 1621  public class Collections Line 1826  public class Collections
1826    
1827      /**      /**
1828       * Single entry.       * Single entry.
1829         *
1830         * @param key The key of the value to be retrieved.
1831         * @return The singleton value if the key is the same as the
1832         *         singleton key, null otherwise.
1833       */       */
1834      public Object get(Object key)      public Object get(Object key)
1835      {      {
# Line 1629  public class Collections Line 1838  public class Collections
1838    
1839      /**      /**
1840       * Calculate the hashcode directly.       * Calculate the hashcode directly.
1841         *
1842         * @return The hashcode computed from the singleton key
1843         *         and the singleton value.
1844       */       */
1845      public int hashCode()      public int hashCode()
1846      {      {
# Line 1637  public class Collections Line 1849  public class Collections
1849    
1850      /**      /**
1851       * Return the keyset.       * Return the keyset.
1852         *
1853         * @return A singleton containing the key.
1854       */       */
1855      public Set keySet()      public Set keySet()
1856      {      {
# Line 1647  public class Collections Line 1861  public class Collections
1861    
1862      /**      /**
1863       * The size: always 1!       * The size: always 1!
1864         *
1865         * @return 1.
1866       */       */
1867      public int size()      public int size()
1868      {      {
# Line 1656  public class Collections Line 1872  public class Collections
1872      /**      /**
1873       * Return the values. Technically, a singleton, while more specific than       * Return the values. Technically, a singleton, while more specific than
1874       * a general Collection, will work. Besides, that's what the JDK uses!       * a general Collection, will work. Besides, that's what the JDK uses!
1875         *
1876         * @return A singleton containing the value.
1877       */       */
1878      public Collection values()      public Collection values()
1879      {      {
# Line 1666  public class Collections Line 1884  public class Collections
1884    
1885      /**      /**
1886       * Obvious string.       * Obvious string.
1887         *
1888         * @return A string containing the string representations of the key
1889         *         and its associated value.
1890       */       */
1891      public String toString()      public String toString()
1892      {      {
# Line 1826  public class Collections Line 2047  public class Collections
2047        mutex = sync;        mutex = sync;
2048      }      }
2049    
2050        /**
2051         * Adds the object to the underlying collection, first
2052         * obtaining a lock on the mutex.
2053         *
2054         * @param o The object to add.
2055         * @return <code>true</code> if the collection was modified as a result
2056         *         of this action.
2057         * @throws UnsupportedOperationException if this collection does not
2058         *         support the add operation.
2059         * @throws ClassCastException if o cannot be added to this collection due
2060         *         to its type.
2061         * @throws NullPointerException if o is null and this collection doesn't
2062         *         support the addition of null values.
2063         * @throws IllegalArgumentException if o cannot be added to this
2064         *         collection for some other reason.
2065         */
2066      public boolean add(Object o)      public boolean add(Object o)
2067      {      {
2068        synchronized (mutex)        synchronized (mutex)
# Line 1834  public class Collections Line 2071  public class Collections
2071          }          }
2072      }      }
2073    
2074        /**
2075         * Adds the objects in col to the underlying collection, first
2076         * obtaining a lock on the mutex.
2077         *
2078         * @param col The collection to take the new objects from.
2079         * @return <code>true</code> if the collection was modified as a result
2080         *          of this action.
2081         * @throws UnsupportedOperationException if this collection does not
2082         *         support the addAll operation.
2083         * @throws ClassCastException if some element of col cannot be added to this
2084         *         collection due to its type.
2085         * @throws NullPointerException if some element of col is null and this
2086         *         collection does not support the addition of null values.
2087         * @throws NullPointerException if col itself is null.
2088         * @throws IllegalArgumentException if some element of col cannot be added
2089         *         to this collection for some other reason.
2090         */
2091      public boolean addAll(Collection col)      public boolean addAll(Collection col)
2092      {      {
2093        synchronized (mutex)        synchronized (mutex)
# Line 1842  public class Collections Line 2096  public class Collections
2096          }          }
2097      }      }
2098    
2099        /**
2100         * Removes all objects from the underlying collection,
2101         * first obtaining a lock on the mutex.
2102         *
2103         * @throws UnsupportedOperationException if this collection does not
2104         *         support the clear operation.
2105         */
2106      public void clear()      public void clear()
2107      {      {
2108        synchronized (mutex)        synchronized (mutex)
# Line 1850  public class Collections Line 2111  public class Collections
2111          }          }
2112      }      }
2113    
2114        /**
2115         * Checks for the existence of o within the underlying
2116         * collection, first obtaining a lock on the mutex.
2117         *
2118         * @param o the element to look for.
2119         * @return <code>true</code> if this collection contains at least one
2120         *         element e such that <code>o == null ? e == null : o.equals(e)</code>.
2121         * @throws ClassCastException if the type of o is not a valid type for this
2122         *         collection.
2123         * @throws NullPointerException if o is null and this collection doesn't
2124         *         support null values.
2125         */
2126      public boolean contains(Object o)      public boolean contains(Object o)
2127      {      {
2128        synchronized (mutex)        synchronized (mutex)
# Line 1858  public class Collections Line 2131  public class Collections
2131          }          }
2132      }      }
2133    
2134        /**
2135         * Checks for the existence of each object in cl
2136         * within the underlying collection, first obtaining
2137         * a lock on the mutex.
2138         *
2139         * @param cl the collection to test for.
2140         * @return <code>true</code> if for every element o in c, contains(o)
2141         *         would return <code>true</code>.
2142         * @throws ClassCastException if the type of any element in cl is not a valid
2143         *         type for this collection.
2144         * @throws NullPointerException if some element of cl is null and this
2145         *         collection does not support null values.
2146         * @throws NullPointerException if cl itself is null.
2147         */
2148      public boolean containsAll(Collection c1)      public boolean containsAll(Collection c1)
2149      {      {
2150        synchronized (mutex)        synchronized (mutex)
# Line 1866  public class Collections Line 2153  public class Collections
2153          }          }
2154      }      }
2155    
2156        /**
2157         * Returns <code>true</code> if there are no objects in the underlying
2158         * collection.  A lock on the mutex is obtained before the
2159         * check is performed.
2160         *
2161         * @return <code>true</code> if this collection contains no elements.
2162         */
2163      public boolean isEmpty()      public boolean isEmpty()
2164      {      {
2165        synchronized (mutex)        synchronized (mutex)
# Line 1874  public class Collections Line 2168  public class Collections
2168          }          }
2169      }      }
2170    
2171        /**
2172         * Returns a synchronized iterator wrapper around the underlying
2173         * collection's iterator.  A lock on the mutex is obtained before
2174         * retrieving the collection's iterator.
2175         *
2176         * @return An iterator over the elements in the underlying collection,
2177         *         which returns each element in any order.
2178         */
2179      public Iterator iterator()      public Iterator iterator()
2180      {      {
2181        synchronized (mutex)        synchronized (mutex)
# Line 1882  public class Collections Line 2184  public class Collections
2184          }          }
2185      }      }
2186    
2187        /**
2188         * Removes the specified object from the underlying collection,
2189         * first obtaining a lock on the mutex.
2190         *
2191         * @param o The object to remove.
2192         * @return <code>true</code> if the collection changed as a result of this call, that is,
2193         *         if the collection contained at least one occurrence of o.
2194         * @throws UnsupportedOperationException if this collection does not
2195         *         support the remove operation.
2196         * @throws ClassCastException if the type of o is not a valid type
2197         *         for this collection.
2198         * @throws NullPointerException if o is null and the collection doesn't
2199         *         support null values.
2200         */
2201      public boolean remove(Object o)      public boolean remove(Object o)
2202      {      {
2203        synchronized (mutex)        synchronized (mutex)
# Line 1890  public class Collections Line 2206  public class Collections
2206          }          }
2207      }      }
2208    
2209        /**
2210         * Removes all elements, e, of the underlying
2211         * collection for which <code>col.contains(e)</code>
2212         * returns <code>true</code>.  A lock on the mutex is obtained
2213         * before the operation proceeds.
2214         *
2215         * @param col The collection of objects to be removed.
2216         * @return <code>true</code> if this collection was modified as a result of this call.
2217         * @throws UnsupportedOperationException if this collection does not
2218         *   support the removeAll operation.
2219         * @throws ClassCastException if the type of any element in c is not a valid
2220         *   type for this collection.
2221         * @throws NullPointerException if some element of c is null and this
2222         *   collection does not support removing null values.
2223         * @throws NullPointerException if c itself is null.
2224         */
2225      public boolean removeAll(Collection col)      public boolean removeAll(Collection col)
2226      {      {
2227        synchronized (mutex)        synchronized (mutex)
# Line 1898  public class Collections Line 2230  public class Collections
2230          }          }
2231      }      }
2232    
2233        /**
2234         * Retains all elements, e, of the underlying
2235         * collection for which <code>col.contains(e)</code>
2236         * returns <code>true</code>.  That is, every element that doesn't
2237         * exist in col is removed.  A lock on the mutex is obtained
2238         * before the operation proceeds.
2239         *
2240         * @param col The collection of objects to be removed.
2241         * @return <code>true</code> if this collection was modified as a result of this call.
2242         * @throws UnsupportedOperationException if this collection does not
2243         *   support the removeAll operation.
2244         * @throws ClassCastException if the type of any element in c is not a valid
2245         *   type for this collection.
2246         * @throws NullPointerException if some element of c is null and this
2247         *   collection does not support removing null values.
2248         * @throws NullPointerException if c itself is null.
2249         */
2250      public boolean retainAll(Collection col)      public boolean retainAll(Collection col)
2251      {      {
2252        synchronized (mutex)        synchronized (mutex)
# Line 1906  public class Collections Line 2255  public class Collections
2255          }          }
2256      }      }
2257    
2258        /**
2259         * Retrieves the size of the underlying collection.
2260         * A lock on the mutex is obtained before the collection
2261         * is accessed.
2262         *
2263         * @return The size of the collection.
2264         */
2265      public int size()      public int size()
2266      {      {
2267        synchronized (mutex)        synchronized (mutex)
# Line 1914  public class Collections Line 2270  public class Collections
2270          }          }
2271      }      }
2272    
2273        /**
2274         * Returns an array containing each object within the underlying
2275         * collection.  A lock is obtained on the mutex before the collection
2276         * is accessed.
2277         *
2278         * @return An array of objects, matching the collection in size.  The
2279         *         elements occur in any order.
2280         */
2281      public Object[] toArray()      public Object[] toArray()
2282      {      {
2283        synchronized (mutex)        synchronized (mutex)
# Line 1922  public class Collections Line 2286  public class Collections
2286          }          }
2287      }      }
2288    
2289        /**
2290         * Copies the elements in the underlying collection to the supplied
2291         * array.  If <code>a.length < size()</code>, a new array of the
2292         * same run-time type is created, with a size equal to that of
2293         * the collection.  If <code>a.length > size()</code>, then the
2294         * elements from 0 to <code>size() - 1</code> contain the elements
2295         * from this collection.  The following element is set to null
2296         * to indicate the end of the collection objects.  However, this
2297         * only makes a difference if null is not a permitted value within
2298         * the collection.
2299         * Before the copying takes place, a lock is obtained on the mutex.
2300         *
2301         * @param a An array to copy elements to.
2302         * @return An array containing the elements of the underlying collection.
2303         * @throws ArrayStoreException if the type of any element of the
2304         *         collection is not a subtype of the element type of a.
2305         */
2306      public Object[] toArray(Object[] a)      public Object[] toArray(Object[] a)
2307      {      {
2308        synchronized (mutex)        synchronized (mutex)
# Line 1930  public class Collections Line 2311  public class Collections
2311          }          }
2312      }      }
2313    
2314        /**
2315         * Returns a string representation of the underlying collection.
2316         * A lock is obtained on the mutex before the string is created.
2317         *
2318         * @return A string representation of the collection.
2319         */
2320      public String toString()      public String toString()
2321      {      {
2322        synchronized (mutex)        synchronized (mutex)
# Line 1969  public class Collections Line 2356  public class Collections
2356        mutex = sync;        mutex = sync;
2357      }      }
2358    
2359        /**
2360         * Retrieves the next object in the underlying collection.
2361         * A lock is obtained on the mutex before the collection is accessed.
2362         *
2363         * @return The next object in the collection.
2364         * @throws NoSuchElementException if there are no more elements
2365         */
2366      public Object next()      public Object next()
2367      {      {
2368        synchronized (mutex)        synchronized (mutex)
# Line 1977  public class Collections Line 2371  public class Collections
2371          }          }
2372      }      }
2373    
2374        /**
2375         * Returns <code>true</code> if objects can still be retrieved from the iterator
2376         * using <code>next()</code>.  A lock is obtained on the mutex before
2377         * the collection is accessed.
2378         *
2379         * @return <code>true</code> if at least one element is still to be returned by
2380         *         <code>next()</code>.
2381         */
2382      public boolean hasNext()      public boolean hasNext()
2383      {      {
2384        synchronized (mutex)        synchronized (mutex)
# Line 1985  public class Collections Line 2387  public class Collections
2387          }          }
2388      }      }
2389    
2390        /**
2391         * Removes the object that was last returned by <code>next()</code>
2392         * from the underlying collection.  Only one call to this method is
2393         * allowed per call to the <code>next()</code> method, and it does
2394         * not affect the value that will be returned by <code>next()</code>.
2395         * Thus, if element n was retrieved from the collection by
2396         * <code>next()</code>, it is this element that gets removed.
2397         * Regardless of whether this takes place or not, element n+1 is
2398         * still returned on the subsequent <code>next()</code> call.
2399         *
2400         * @throws IllegalStateException if next has not yet been called or remove
2401         *         has already been called since the last call to next.
2402         * @throws UnsupportedOperationException if this Iterator does not support
2403         *         the remove operation.
2404         */
2405      public void remove()      public void remove()
2406      {      {
2407        synchronized (mutex)        synchronized (mutex)
# Line 2072  public class Collections Line 2489  public class Collections
2489        list = l;        list = l;
2490      }      }
2491    
2492      /**
2493       * Insert an element into the underlying list at a given position (optional
2494       * operation).  This shifts all existing elements from that position to the
2495       * end one index to the right. This version of add has no return, since it is
2496       * assumed to always succeed if there is no exception.  Before the
2497       * addition takes place, a lock is obtained on the mutex.
2498       *
2499       * @param index the location to insert the item
2500       * @param o the object to insert
2501       * @throws UnsupportedOperationException if this list does not support the
2502       *         add operation
2503       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
2504       * @throws ClassCastException if o cannot be added to this list due to its
2505       *         type
2506       * @throws IllegalArgumentException if o cannot be added to this list for
2507       *         some other reason
2508       * @throws NullPointerException if o is null and this list doesn't support
2509       *         the addition of null values.
2510       */
2511      public void add(int index, Object o)      public void add(int index, Object o)
2512      {      {
2513        synchronized (mutex)        synchronized (mutex)
# Line 2080  public class Collections Line 2516  public class Collections
2516          }          }
2517      }      }
2518    
2519      /**
2520       * Add an element to the end of the underlying list (optional operation).
2521       * If the list imposes restraints on what can be inserted, such as no null
2522       * elements, this should be documented.  A lock is obtained on the mutex before
2523       * any of the elements are added.
2524       *
2525       * @param o the object to add
2526       * @return <code>true</code>, as defined by Collection for a modified list
2527       * @throws UnsupportedOperationException if this list does not support the
2528       *         add operation
2529       * @throws ClassCastException if o cannot be added to this list due to its
2530       *         type
2531       * @throws IllegalArgumentException if o cannot be added to this list for
2532       *         some other reason
2533       * @throws NullPointerException if o is null and this list doesn't support
2534       *         the addition of null values.
2535       */
2536      public boolean addAll(int index, Collection c)      public boolean addAll(int index, Collection c)
2537      {      {
2538        synchronized (mutex)        synchronized (mutex)
# Line 2088  public class Collections Line 2541  public class Collections
2541          }          }
2542      }      }
2543    
2544       /**
2545        * Tests whether the underlying list is equal to the supplied object.
2546        * The object is deemed to be equal if it is also a <code>List</code>
2547        * of equal size and with the same elements (i.e. each element, e1,
2548        * in list, l1, and each element, e2, in l2, must return <code>true</code> for
2549        * <code>e1 == null ? e2 == null : e1.equals(e2)</code>.  Before the
2550        * comparison is made, a lock is obtained on the mutex.
2551        *
2552        * @param o The object to test for equality with the underlying list.
2553        * @return <code>true</code> if o is equal to the underlying list under the above
2554        *         definition.
2555        */
2556      public boolean equals(Object o)      public boolean equals(Object o)
2557      {      {
2558        synchronized (mutex)        synchronized (mutex)
# Line 2096  public class Collections Line 2561  public class Collections
2561          }          }
2562      }      }
2563    
2564        /**
2565         * Retrieves the object at the specified index.  A lock
2566         * is obtained on the mutex before the list is accessed.
2567         *
2568         * @param index the index of the element to be returned
2569         * @return the element at index index in this list
2570         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2571         */
2572      public Object get(int index)      public Object get(int index)
2573      {      {
2574        synchronized (mutex)        synchronized (mutex)
# Line 2104  public class Collections Line 2577  public class Collections
2577          }          }
2578      }      }
2579    
2580        /**
2581         * Obtains a hashcode for the underlying list, first obtaining
2582         * a lock on the mutex.  The calculation of the hashcode is
2583         * detailed in the documentation for the <code>List</code>
2584         * interface.
2585         *
2586         * @return The hashcode of the underlying list.
2587         * @see List#hashCode()
2588         */
2589      public int hashCode()      public int hashCode()
2590      {      {
2591        synchronized (mutex)        synchronized (mutex)
# Line 2112  public class Collections Line 2594  public class Collections
2594          }          }
2595      }      }
2596    
2597        /**
2598         * Obtain the first index at which a given object is to be found in the
2599         * underlying list.  A lock is obtained on the mutex before the list is
2600         * accessed.
2601         *
2602         * @param o the object to search for
2603         * @return the least integer n such that <code>o == null ? get(n) == null :
2604         *         o.equals(get(n))</code>, or -1 if there is no such index.
2605         * @throws ClassCastException if the type of o is not a valid
2606         *         type for this list.
2607         * @throws NullPointerException if o is null and this
2608         *         list does not support null values.
2609         */
2610    
2611      public int indexOf(Object o)      public int indexOf(Object o)
2612      {      {
2613        synchronized (mutex)        synchronized (mutex)
# Line 2120  public class Collections Line 2616  public class Collections
2616          }          }
2617      }      }
2618    
2619        /**
2620         * Obtain the last index at which a given object is to be found in this
2621         * underlying list.  A lock is obtained on the mutex before the list
2622         * is accessed.
2623         *
2624         * @return the greatest integer n such that <code>o == null ? get(n) == null
2625         *         : o.equals(get(n))</code>, or -1 if there is no such index.
2626         * @throws ClassCastException if the type of o is not a valid
2627         *         type for this list.
2628         * @throws NullPointerException if o is null and this
2629         *         list does not support null values.
2630         */
2631      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
2632      {      {
2633        synchronized (mutex)        synchronized (mutex)
# Line 2128  public class Collections Line 2636  public class Collections
2636          }          }
2637      }      }
2638    
2639        /**
2640         * Retrieves a synchronized wrapper around the underlying list's
2641         * list iterator.  A lock is obtained on the mutex before the
2642         * list iterator is retrieved.
2643         *
2644         * @return A list iterator over the elements in the underlying list.
2645         *         The list iterator allows additional list-specific operations
2646         *         to be performed, in addition to those supplied by the
2647         *         standard iterator.
2648         */
2649      public ListIterator listIterator()      public ListIterator listIterator()
2650      {      {
2651        synchronized (mutex)        synchronized (mutex)
# Line 2136  public class Collections Line 2654  public class Collections
2654          }          }
2655      }      }
2656    
2657        /**
2658         * Retrieves a synchronized wrapper around the underlying list's
2659         * list iterator.  A lock is obtained on the mutex before the
2660         * list iterator is retrieved.  The iterator starts at the
2661         * index supplied, leading to the element at that index being
2662         * the first one returned by <code>next()</code>.  Calling
2663         * <code>previous()</code> from this initial position returns
2664         * index - 1.
2665         *
2666         * @param index the position, between 0 and size() inclusive, to begin the
2667         *        iteration from
2668         * @return A list iterator over the elements in the underlying list.
2669         *         The list iterator allows additional list-specific operations
2670         *         to be performed, in addition to those supplied by the
2671         *         standard iterator.
2672         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
2673         */
2674      public ListIterator listIterator(int index)      public ListIterator listIterator(int index)
2675      {      {
2676        synchronized (mutex)        synchronized (mutex)
# Line 2144  public class Collections Line 2679  public class Collections
2679          }          }
2680      }      }
2681    
2682        /**
2683         * Remove the element at a given position in the underlying list (optional
2684         * operation).  All remaining elements are shifted to the left to fill the gap.
2685         * A lock on the mutex is obtained before the element is removed.
2686         *
2687         * @param index the position within the list of the object to remove
2688         * @return the object that was removed
2689         * @throws UnsupportedOperationException if this list does not support the
2690         *         remove operation
2691         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2692         */
2693      public Object remove(int index)      public Object remove(int index)
2694      {      {
2695        synchronized (mutex)        synchronized (mutex)
# Line 2152  public class Collections Line 2698  public class Collections
2698          }          }
2699      }      }
2700    
2701      /**
2702       * Replace an element of the underlying list with another object (optional
2703       * operation).  A lock is obtained on the mutex before the element is
2704       * replaced.
2705       *
2706       * @param index the position within this list of the element to be replaced
2707       * @param o the object to replace it with
2708       * @return the object that was replaced
2709       * @throws UnsupportedOperationException if this list does not support the
2710       *         set operation.
2711       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
2712       * @throws ClassCastException if o cannot be added to this list due to its
2713       *         type
2714       * @throws IllegalArgumentException if o cannot be added to this list for
2715       *         some other reason
2716       * @throws NullPointerException if o is null and this
2717       *         list does not support null values.
2718       */
2719      public Object set(int index, Object o)      public Object set(int index, Object o)
2720      {      {
2721        synchronized (mutex)        synchronized (mutex)
# Line 2160  public class Collections Line 2724  public class Collections
2724          }          }
2725      }      }
2726    
2727        /**
2728         * Obtain a List view of a subsection of the underlying list, from fromIndex
2729         * (inclusive) to toIndex (exclusive). If the two indices are equal, the
2730         * sublist is empty. The returned list should be modifiable if and only
2731         * if this list is modifiable. Changes to the returned list should be
2732         * reflected in this list. If this list is structurally modified in
2733         * any way other than through the returned list, the result of any subsequent
2734         * operations on the returned list is undefined.  A lock is obtained
2735         * on the mutex before the creation of the sublist.  The returned list
2736         * is also synchronized, using the same mutex.
2737         *
2738         * @param fromIndex the index that the returned list should start from
2739         *        (inclusive)
2740         * @param toIndex the index that the returned list should go to (exclusive)
2741         * @return a List backed by a subsection of this list
2742         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
2743         *         || toIndex &gt; size() || fromIndex &gt; toIndex
2744         */
2745      public List subList(int fromIndex, int toIndex)      public List subList(int fromIndex, int toIndex)
2746      {      {
2747        synchronized (mutex)        synchronized (mutex)
# Line 2205  public class Collections Line 2787  public class Collections
2787        super(sync, l);        super(sync, l);
2788      }      }
2789    
2790        /**
2791         * Obtain a List view of a subsection of the underlying list, from fromIndex
2792         * (inclusive) to toIndex (exclusive). If the two indices are equal, the
2793         * sublist is empty. The returned list should be modifiable if and only
2794         * if this list is modifiable. Changes to the returned list should be
2795         * reflected in this list. If this list is structurally modified in
2796         * any way other than through the returned list, the result of any subsequent
2797         * operations on the returned list is undefined.    A lock is obtained
2798         * on the mutex before the creation of the sublist.  The returned list
2799         * is also synchronized, using the same mutex.  Random accessibility
2800         * is also extended to the new list.
2801         *
2802         * @param fromIndex the index that the returned list should start from
2803         *        (inclusive)
2804         * @param toIndex the index that the returned list should go to (exclusive)
2805         * @return a List backed by a subsection of this list
2806         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
2807         *         || toIndex &gt; size() || fromIndex &gt; toIndex
2808         */
2809      public List subList(int fromIndex, int toIndex)      public List subList(int fromIndex, int toIndex)
2810      {      {
2811        synchronized (mutex)        synchronized (mutex)
# Line 2242  public class Collections Line 2843  public class Collections
2843        this.li = li;        this.li = li;
2844      }      }
2845    
2846        /**
2847         * Insert an element into the underlying list at the current position of
2848         * the iterator (optional operation). The element is inserted in between
2849         * the element that would be returned by <code>previous()</code> and the
2850         * element that would be returned by <code>next()</code>. After the
2851         * insertion, a subsequent call to next is unaffected, but
2852         * a call to previous returns the item that was added. The values returned
2853         * by nextIndex() and previousIndex() are incremented.  A lock is obtained
2854         * on the mutex before the addition takes place.
2855         *
2856         * @param o the object to insert into the list
2857         * @throws ClassCastException if the object is of a type which cannot be added
2858         *         to this list.
2859         * @throws IllegalArgumentException if some other aspect of the object stops
2860         *         it being added to this list.
2861         * @throws UnsupportedOperationException if this ListIterator does not
2862         *         support the add operation.
2863         */
2864      public void add(Object o)      public void add(Object o)
2865      {      {
2866        synchronized (mutex)        synchronized (mutex)
# Line 2249  public class Collections Line 2868  public class Collections
2868            li.add(o);            li.add(o);
2869          }          }
2870      }      }
2871    
2872        /**
2873         * Tests whether there are elements remaining in the underlying list
2874         * in the reverse direction. In other words, <code>previous()</code>
2875         * will not fail with a NoSuchElementException.  A lock is obtained
2876         * on the mutex before the check takes place.
2877         *
2878         * @return <code>true</code> if the list continues in the reverse direction
2879         */
2880      public boolean hasPrevious()      public boolean hasPrevious()
2881      {      {
2882        synchronized (mutex)        synchronized (mutex)
# Line 2257  public class Collections Line 2885  public class Collections
2885          }          }
2886      }      }
2887    
2888        /**
2889          * Find the index of the element that would be returned by a call to
2890          * <code>next()</code>.  If hasNext() returns <code>false</code>, this
2891          * returns the list size.  A lock is obtained on the mutex before the
2892          * query takes place.
2893          *
2894          * @return the index of the element that would be returned by next()
2895          */
2896      public int nextIndex()      public int nextIndex()
2897      {      {
2898        synchronized (mutex)        synchronized (mutex)
# Line 2265  public class Collections Line 2901  public class Collections
2901          }          }
2902      }      }
2903    
2904        /**
2905         * Obtain the previous element from the underlying list. Repeated
2906         * calls to previous may be used to iterate backwards over the entire list,
2907         * or calls to next and previous may be used together to go forwards and
2908         * backwards. Alternating calls to next and previous will return the same
2909         * element.  A lock is obtained on the mutex before the object is retrieved.
2910         *
2911         * @return the next element in the list in the reverse direction
2912         * @throws NoSuchElementException if there are no more elements
2913         */
2914      public Object previous()      public Object previous()
2915      {      {
2916        synchronized (mutex)        synchronized (mutex)
# Line 2273  public class Collections Line 2919  public class Collections
2919          }          }
2920      }      }
2921    
2922        /**
2923         * Find the index of the element that would be returned by a call to
2924         * previous. If hasPrevious() returns <code>false</code>, this returns -1.
2925         * A lock is obtained on the mutex before the query takes place.
2926         *
2927         * @return the index of the element that would be returned by previous()
2928         */
2929      public int previousIndex()      public int previousIndex()
2930      {      {
2931        synchronized (mutex)        synchronized (mutex)
# Line 2281  public class Collections Line 2934  public class Collections
2934          }          }
2935      }      }
2936    
2937        /**
2938         * Replace the element last returned by a call to <code>next()</code> or
2939         * <code>previous()</code> with a given object (optional operation).  This
2940         * method may only be called if neither <code>add()</code> nor
2941         * <code>remove()</code> have been called since the last call to
2942         * <code>next()</code> or <code>previous</code>.  A lock is obtained
2943         * on the mutex before the list is modified.
2944         *
2945         * @param o the object to replace the element with
2946         * @throws ClassCastException the object is of a type which cannot be added
2947         *         to this list
2948         * @throws IllegalArgumentException some other aspect of the object stops
2949         *         it being added to this list
2950         * @throws IllegalStateException if neither next or previous have been
2951         *         called, or if add or remove has been called since the last call
2952         *         to next or previous
2953         * @throws UnsupportedOperationException if this ListIterator does not
2954         *         support the set operation
2955         */
2956      public void set(Object o)      public void set(Object o)
2957      {      {
2958        synchronized (mutex)        synchronized (mutex)
# Line 2387  public class Collections Line 3059  public class Collections
3059        mutex = sync;        mutex = sync;
3060      }      }
3061    
3062        /**
3063         * Clears all the entries from the underlying map.  A lock is obtained
3064         * on the mutex before the map is cleared.
3065         *
3066         * @throws UnsupportedOperationException if clear is not supported
3067         */
3068      public void clear()      public void clear()
3069      {      {
3070        synchronized (mutex)        synchronized (mutex)
# Line 2395  public class Collections Line 3073  public class Collections
3073          }          }
3074      }      }
3075    
3076        /**
3077         * Returns <code>true</code> if the underlying map contains a entry for the given key.
3078         * A lock is obtained on the mutex before the map is queried.
3079         *
3080         * @param key the key to search for.
3081         * @return <code>true</code> if the underlying map contains the key.
3082         * @throws ClassCastException if the key is of an inappropriate type.
3083         * @throws NullPointerException if key is <code>null</code> but the map
3084         *         does not permit null keys.
3085         */
3086      public boolean containsKey(Object key)      public boolean containsKey(Object key)
3087      {      {
3088        synchronized (mutex)        synchronized (mutex)
# Line 2403  public class Collections Line 3091  public class Collections
3091          }          }
3092      }      }
3093    
3094      /**
3095       * Returns <code>true</code> if the underlying map contains at least one entry with the
3096       * given value.  In other words, returns <code>true</code> if a value v exists where
3097       * <code>(value == null ? v == null : value.equals(v))</code>. This usually
3098       * requires linear time.  A lock is obtained on the mutex before the map
3099       * is queried.
3100       *
3101       * @param value the value to search for
3102       * @return <code>true</code> if the map contains the value
3103       * @throws ClassCastException if the type of the value is not a valid type
3104       *         for this map.
3105       * @throws NullPointerException if the value is null and the map doesn't
3106       *         support null values.
3107       */
3108      public boolean containsValue(Object value)      public boolean containsValue(Object value)
3109      {      {
3110        synchronized (mutex)        synchronized (mutex)
# Line 2425  public class Collections Line 3127  public class Collections
3127          {          {
3128            e = (Map.Entry) o;            e = (Map.Entry) o;
3129          }          }
3130    
3131            /**
3132             * Returns <code>true</code> if the object, o, implements <code>Map.Entry</code>
3133             * with the same key and value as the underlying entry.  A lock is
3134             * obtained on the mutex before the comparison takes place.
3135             *
3136             * @param o The object to compare with this entry.
3137             * @return <code>true</code> if o is equivalent to the underlying map entry.
3138             */
3139          public boolean equals(Object o)          public boolean equals(Object o)
3140          {          {
3141            synchronized (mutex)            synchronized (mutex)
# Line 2432  public class Collections Line 3143  public class Collections
3143                return e.equals(o);                return e.equals(o);
3144              }              }
3145          }          }
3146    
3147            /**
3148             * Returns the key used in the underlying map entry.  A lock is obtained
3149             * on the mutex before the key is retrieved.
3150             *
3151             * @return The key of the underlying map entry.
3152             */
3153          public Object getKey()          public Object getKey()
3154          {          {
3155            synchronized (mutex)            synchronized (mutex)
# Line 2439  public class Collections Line 3157  public class Collections
3157                return e.getKey();                return e.getKey();
3158              }              }
3159          }          }
3160    
3161            /**
3162             * Returns the value used in the underlying map entry.  A lock is obtained
3163             * on the mutex before the value is retrieved.
3164             *
3165             * @return The value of the underlying map entry.
3166             */
3167          public Object getValue()          public Object getValue()
3168          {          {
3169            synchronized (mutex)            synchronized (mutex)
# Line 2446  public class Collections Line 3171  public class Collections
3171                return e.getValue();                return e.getValue();
3172              }              }
3173          }          }
3174    
3175            /**
3176             * Computes the hash code for the underlying map entry.
3177             * This computation is described in the documentation for the
3178             * <code>Map</code> interface.  A lock is obtained on the mutex
3179             * before the underlying map is accessed.
3180             *
3181             * @return The hash code of the underlying map entry.
3182             * @see Map#hashCode()
3183             */
3184          public int hashCode()          public int hashCode()
3185          {          {
3186            synchronized (mutex)            synchronized (mutex)
# Line 2453  public class Collections Line 3188  public class Collections
3188                return e.hashCode();                return e.hashCode();
3189              }              }
3190          }          }
3191    
3192            /**
3193             * Replaces the value in the underlying map entry with the specified
3194             * object (optional operation).  A lock is obtained on the mutex
3195             * before the map is altered.  The map entry, in turn, will alter
3196             * the underlying map object.  The operation is undefined if the
3197             * <code>remove()</code> method of the iterator has been called
3198             * beforehand.
3199             *
3200             * @param value the new value to store
3201             * @return the old value
3202             * @throws UnsupportedOperationException if the operation is not supported.
3203             * @throws ClassCastException if the value is of the wrong type.
3204             * @throws IllegalArgumentException if something about the value
3205             *         prevents it from existing in this map.
3206             * @throws NullPointerException if the map forbids null values.
3207             */
3208          public Object setValue(Object value)          public Object setValue(Object value)
3209          {          {
3210            synchronized (mutex)            synchronized (mutex)
# Line 2460  public class Collections Line 3212  public class Collections
3212                return e.setValue(value);                return e.setValue(value);
3213              }              }
3214          }          }
3215    
3216            /**
3217             * Returns a textual representation of the underlying map entry.
3218             * A lock is obtained on the mutex before the entry is accessed.
3219             *
3220             * @return The contents of the map entry in <code>String</code> form.
3221             */
3222          public String toString()          public String toString()
3223          {          {
3224            synchronized (mutex)            synchronized (mutex)
# Line 2475  public class Collections Line 3234  public class Collections
3234            {            {
3235              entries = new SynchronizedSet(mutex, m.entrySet())              entries = new SynchronizedSet(mutex, m.entrySet())
3236              {              {
3237                public Iterator iterator()                /**
3238                   * Returns an iterator over the set.  The iterator has no specific order,
3239                   * unless further specified.  A lock is obtained on the set's mutex
3240                   * before the iterator is created.  The created iterator is also
3241                   * thread-safe.
3242                   *
3243                   * @return A synchronized set iterator.
3244                   */
3245                  public Iterator iterator()
3246                {                {
3247                  synchronized (super.mutex)                  synchronized (super.mutex)
3248                    {                    {
3249                      return new SynchronizedIterator(super.mutex, c.iterator())                      return new SynchronizedIterator(super.mutex, c.iterator())
3250                      {                      {
3251                          /**
3252                           * Retrieves the next map entry from the iterator.
3253                           * A lock is obtained on the iterator's mutex before
3254                           * the entry is created.  The new map entry is enclosed in
3255                           * a thread-safe wrapper.
3256                           *
3257                           * @return A synchronized map entry.
3258                           */
3259                        public Object next()                        public Object next()
3260                        {                        {
3261                          synchronized (super.mutex)                          synchronized (super.mutex)
# Line 2496  public class Collections Line 3271  public class Collections
3271        return entries;        return entries;
3272      }      }
3273    
3274        /**
3275         * Returns <code>true</code> if the object, o, is also an instance
3276         * of <code>Map</code> and contains an equivalent
3277         * entry set to that of the underlying map.  A lock
3278         * is obtained on the mutex before the objects are
3279         * compared.
3280         *
3281         * @param o The object to compare.
3282         * @return <code>true</code> if o and the underlying map are equivalent.
3283         */
3284      public boolean equals(Object o)      public boolean equals(Object o)
3285      {      {
3286        synchronized (mutex)        synchronized (mutex)
# Line 2504  public class Collections Line 3289  public class Collections
3289          }          }
3290      }      }
3291    
3292        /**
3293         * Returns the value associated with the given key, or null
3294         * if no such mapping exists.  An ambiguity exists with maps
3295         * that accept null values as a return value of null could
3296         * be due to a non-existent mapping or simply a null value
3297         * for that key.  To resolve this, <code>containsKey</code>
3298         * should be used.  A lock is obtained on the mutex before
3299         * the value is retrieved from the underlying map.
3300         *
3301         * @param key The key of the required mapping.
3302         * @return The value associated with the given key, or
3303         *         null if no such mapping exists.
3304         * @throws ClassCastException if the key is an inappropriate type.
3305         * @throws NullPointerException if this map does not accept null keys.
3306         */
3307      public Object get(Object key)      public Object get(Object key)
3308      {      {
3309        synchronized (mutex)        synchronized (mutex)
# Line 2512  public class Collections Line 3312  public class Collections
3312          }          }
3313      }      }
3314    
3315        /**
3316         * Calculates the hash code of the underlying map as the
3317         * sum of the hash codes of all entries.  A lock is obtained
3318         * on the mutex before the hash code is computed.
3319         *
3320         * @return The hash code of the underlying map.
3321         */
3322      public int hashCode()      public int hashCode()
3323      {      {
3324        synchronized (mutex)        synchronized (mutex)
# Line 2520  public class Collections Line 3327  public class Collections
3327          }          }
3328      }      }
3329    
3330        /**
3331         * Returns <code>true</code> if the underlying map contains no entries.
3332         * A lock is obtained on the mutex before the map is examined.
3333         *
3334         * @return <code>true</code> if the map is empty.
3335         */
3336      public boolean isEmpty()      public boolean isEmpty()
3337      {      {
3338        synchronized (mutex)        synchronized (mutex)
# Line 2528  public class Collections Line 3341  public class Collections
3341          }          }
3342      }      }
3343    
3344        /**
3345         * Returns a thread-safe set view of the keys in the underlying map.  The
3346         * set is backed by the map, so that changes in one show up in the other.
3347         * Modifications made while an iterator is in progress cause undefined
3348         * behavior.  If the set supports removal, these methods remove the
3349         * underlying mapping from the map: <code>Iterator.remove</code>,
3350         * <code>Set.remove</code>, <code>removeAll</code>, <code>retainAll</code>,
3351         * and <code>clear</code>.  Element addition, via <code>add</code> or
3352         * <code>addAll</code>, is not supported via this set.  A lock is obtained
3353         * on the mutex before the set is created.
3354         *
3355         * @return A synchronized set containing the keys of the underlying map.
3356         */
3357      public Set keySet()      public Set keySet()
3358      {      {
3359        if (keys == null)        if (keys == null)
# Line 2538  public class Collections Line 3364  public class Collections
3364        return keys;        return keys;
3365      }      }
3366    
3367        /**
3368         * Associates the given key to the given value (optional operation). If the
3369         * underlying map already contains the key, its value is replaced. Be aware
3370         * that in a map that permits <code>null</code> values, a null return does not
3371         * always imply that the mapping was created.  A lock is obtained on the mutex
3372         * before the modification is made.
3373         *
3374         * @param key the key to map.
3375         * @param value the value to be mapped.
3376         * @return the previous value of the key, or null if there was no mapping
3377         * @throws UnsupportedOperationException if the operation is not supported
3378         * @throws ClassCastException if the key or value is of the wrong type
3379         * @throws IllegalArgumentException if something about this key or value
3380         *         prevents it from existing in this map
3381         * @throws NullPointerException if either the key or the value is null,
3382         *         and the map forbids null keys or values
3383         * @see #containsKey(Object)
3384         */
3385      public Object put(Object key, Object value)      public Object put(Object key, Object value)
3386      {      {
3387        synchronized (mutex)        synchronized (mutex)
# Line 2546  public class Collections Line 3390  public class Collections
3390          }          }
3391      }      }
3392    
3393        /**
3394         * Copies all entries of the given map to the underlying one (optional
3395         * operation). If the map already contains a key, its value is replaced.
3396         * A lock is obtained on the mutex before the operation proceeds.
3397         *
3398         * @param m the mapping to load into this map
3399         * @throws UnsupportedOperationException if the operation is not supported
3400         * @throws ClassCastException if a key or value is of the wrong type
3401         * @throws IllegalArgumentException if something about a key or value
3402         *         prevents it from existing in this map
3403         * @throws NullPointerException if the map forbids null keys or values, or
3404         *         if <code>m</code> is null.
3405         * @see #put(Object, Object)
3406         */
3407      public void putAll(Map map)      public void putAll(Map map)
3408      {      {
3409        synchronized (mutex)        synchronized (mutex)
# Line 2554  public class Collections Line 3412  public class Collections
3412          }          }
3413      }      }
3414    
3415        /**
3416         * Removes the mapping for the key, o, if present (optional operation). If
3417         * the key is not present, this returns null. Note that maps which permit
3418         * null values may also return null if the key was removed.  A prior
3419         * <code>containsKey()</code> check is required to avoid this ambiguity.
3420         * Before the mapping is removed, a lock is obtained on the mutex.
3421         *
3422         * @param key the key to remove
3423         * @return the value the key mapped to, or null if not present
3424         * @throws UnsupportedOperationException if deletion is unsupported
3425         * @throws NullPointerException if the key is null and this map doesn't
3426         *         support null keys.
3427         * @throws ClassCastException if the type of the key is not a valid type
3428         *         for this map.
3429         */
3430      public Object remove(Object o)      public Object remove(Object o)
3431      {      {
3432        synchronized (mutex)        synchronized (mutex)
# Line 2562  public class Collections Line 3435  public class Collections
3435          }          }
3436      }      }
3437    
3438        /**
3439         * Retrieves the size of the underlying map.  A lock
3440         * is obtained on the mutex before access takes place.
3441         * Maps with a size greater than <code>Integer.MAX_VALUE</code>
3442         * return <code>Integer.MAX_VALUE</code> instead.
3443         *
3444         * @return The size of the underlying map.
3445         */
3446      public int size()      public int size()
3447      {      {
3448        synchronized (mutex)        synchronized (mutex)
# Line 2570  public class Collections Line 3451  public class Collections
3451          }          }
3452      }      }
3453    
3454        /**
3455         * Returns a textual representation of the underlying
3456         * map.  A lock is obtained on the mutex before the map
3457         * is accessed.
3458         *
3459         * @return The map in <code>String</code> form.
3460         */
3461      public String toString()      public String toString()
3462      {      {
3463        synchronized (mutex)        synchronized (mutex)
# Line 2578  public class Collections Line 3466  public class Collections
3466          }          }
3467      }      }
3468    
3469        /**
3470         * Returns a synchronized collection view of the values in the underlying
3471         * map.  The collection is backed by the map, so that changes in one show up in
3472         * the other.  Modifications made while an iterator is in progress cause
3473         * undefined behavior.  If the collection supports removal, these methods
3474         * remove the underlying mapping from the map: <code>Iterator.remove</code>,
3475         * <code>Collection.remove</code>, <code>removeAll</code>,
3476         * <code>retainAll</code>, and <code>clear</code>. Element addition, via
3477         * <code>add</code> or <code>addAll</code>, is not supported via this
3478         * collection.  A lock is obtained on the mutex before the collection
3479         * is created.
3480         *
3481         * @return the collection of all values in the underlying map.
3482         */
3483      public Collection values()      public Collection values()
3484      {      {
3485        if (values == null)        if (values == null)
# Line 2654  public class Collections Line 3556  public class Collections
3556        super(sync, s);        super(sync, s);
3557      }      }
3558    
3559        /**
3560         * Returns <code>true</code> if the object, o, is a <code>Set</code>
3561         * of the same size as the underlying set, and contains
3562         * each element, e, which occurs in the underlying set.
3563         * A lock is obtained on the mutex before the comparison
3564         * takes place.
3565         *
3566         * @param o The object to compare against.
3567         * @return <code>true</code> if o is an equivalent set.
3568         */
3569      public boolean equals(Object o)      public boolean equals(Object o)
3570      {      {
3571        synchronized (mutex)        synchronized (mutex)
# Line 2662  public class Collections Line 3574  public class Collections
3574          }          }
3575      }      }
3576    
3577        /**
3578         * Computes the hash code for the underlying set as the
3579         * sum of the hash code of all elements within the set.
3580         * A lock is obtained on the mutex before the computation
3581         * occurs.
3582         *
3583         * @return The hash code for the underlying set.
3584         */
3585      public int hashCode()      public int hashCode()
3586      {      {
3587        synchronized (mutex)        synchronized (mutex)
# Line 2685  public class Collections Line 3605  public class Collections
3605     * Set s2 = m2.keySet(); // safe outside a synchronized block     * Set s2 = m2.keySet(); // safe outside a synchronized block
3606     * synchronized (m) // synch on m, not m2, s or s2     * synchronized (m) // synch on m, not m2, s or s2
3607     *   {     *   {
3608     *     Iterator i = s.iterator();  3~3~   *     Iterator i = s.iterator();
3609     *     while (i.hasNext())     *     while (i.hasNext())
3610     *       foo(i.next());     *       foo(i.next());
3611     *     i = s2.iterator();     *     i = s2.iterator();
# Line 2749  public class Collections Line 3669  public class Collections
3669        this.sm = sm;        this.sm = sm;
3670      }      }
3671    
3672        /**
3673         * Returns the comparator used in sorting the underlying map, or null if
3674         * it is the keys' natural ordering.  A lock is obtained on the mutex
3675         * before the comparator is retrieved.
3676         *
3677         * @return the sorting comparator.
3678         */
3679      public Comparator comparator()      public Comparator comparator()
3680      {      {
3681        synchronized (mutex)        synchronized (mutex)
# Line 2757  public class Collections Line 3684  public class Collections
3684          }          }
3685      }      }
3686    
3687        /**
3688         * Returns the first, lowest sorted, key from the underlying map.
3689         * A lock is obtained on the mutex before the map is accessed.
3690         *
3691         * @return the first key.
3692         * @throws NoSuchElementException if this map is empty.
3693         */
3694      public Object firstKey()      public Object firstKey()
3695      {      {
3696        synchronized (mutex)        synchronized (mutex)
# Line 2765  public class Collections Line 3699  public class Collections
3699          }          }
3700      }      }
3701    
3702        /**
3703         * Returns a submap containing the keys from the first
3704         * key (as returned by <code>firstKey()</code>) to
3705         * the key before that specified.  The submap supports all
3706         * operations supported by the underlying map and all actions
3707         * taking place on the submap are also reflected in the underlying
3708         * map.  A lock is obtained on the mutex prior to submap creation.
3709         * This operation is equivalent to <code>subMap(firstKey(), toKey)</code>.
3710         * The submap retains the thread-safe status of this map.
3711         *
3712         * @param toKey the exclusive upper range of the submap.
3713         * @return a submap from <code>firstKey()</code> to the
3714         *         the key preceding toKey.
3715         * @throws ClassCastException if toKey is not comparable to the underlying
3716         *         map's contents.
3717         * @throws IllegalArgumentException if toKey is outside the map's range.
3718         * @throws NullPointerException if toKey is null. but the map does not allow
3719         *         null keys.
3720         */
3721      public SortedMap headMap(Object toKey)      public SortedMap headMap(Object toKey)
3722      {      {
3723        synchronized (mutex)        synchronized (mutex)
# Line 2773  public class Collections Line 3726  public class Collections
3726          }          }
3727      }      }
3728    
3729        /**
3730         * Returns the last, highest sorted, key from the underlying map.
3731         * A lock is obtained on the mutex before the map is accessed.
3732         *
3733         * @return the last key.
3734         * @throws NoSuchElementException if this map is empty.
3735         */
3736      public Object lastKey()      public Object lastKey()
3737      {      {
3738        synchronized (mutex)        synchronized (mutex)
# Line 2781  public class Collections Line 3741  public class Collections
3741          }          }
3742      }      }
3743    
3744        /**
3745         * Returns a submap containing the keys from fromKey to
3746         * the key before toKey.  The submap supports all
3747         * operations supported by the underlying map and all actions
3748         * taking place on the submap are also reflected in the underlying
3749         * map.  A lock is obtained on the mutex prior to submap creation.
3750         * The submap retains the thread-safe status of this map.
3751         *
3752         * @param fromKey the inclusive lower range of the submap.
3753         * @param toKey the exclusive upper range of the submap.
3754         * @return a submap from fromKey to the key preceding toKey.
3755         * @throws ClassCastException if fromKey or toKey is not comparable
3756         *         to the underlying map's contents.
3757         * @throws IllegalArgumentException if fromKey or toKey is outside the map's
3758         *         range.
3759         * @throws NullPointerException if fromKey or toKey is null. but the map does
3760         *         not allow  null keys.
3761         */
3762      public SortedMap subMap(Object fromKey, Object toKey)      public SortedMap subMap(Object fromKey, Object toKey)
3763      {      {
3764        synchronized (mutex)        synchronized (mutex)
# Line 2789  public class Collections Line 3767  public class Collections
3767          }          }
3768      }      }
3769    
3770        /**
3771         * Returns a submap containing all the keys from fromKey onwards.
3772         * The submap supports all operations supported by the underlying
3773         * map and all actions taking place on the submap are also reflected
3774         * in the underlying map.  A lock is obtained on the mutex prior to
3775         * submap creation.  The submap retains the thread-safe status of
3776         * this map.
3777         *
3778         * @param fromKey the inclusive lower range of the submap.
3779         * @return a submap from fromKey to <code>lastKey()</code>.
3780         * @throws ClassCastException if fromKey is not comparable to the underlying
3781         *         map's contents.
3782         * @throws IllegalArgumentException if fromKey is outside the map's range.
3783         * @throws NullPointerException if fromKey is null. but the map does not allow
3784         *         null keys.
3785         */
3786      public SortedMap tailMap(Object fromKey)      public SortedMap tailMap(Object fromKey)
3787      {      {
3788        synchronized (mutex)        synchronized (mutex)
# Line 2871  public class Collections Line 3865  public class Collections
3865        this.ss = ss;        this.ss = ss;
3866      }      }
3867    
3868        /**
3869         * Returns the comparator used in sorting the underlying set, or null if
3870         * it is the elements' natural ordering.  A lock is obtained on the mutex
3871         * before the comparator is retrieved.
3872         *
3873         * @return the sorting comparator.
3874         */
3875      public Comparator comparator()      public Comparator comparator()
3876      {      {
3877        synchronized (mutex)        synchronized (mutex)
# Line 2879  public class Collections Line 3880  public class Collections
3880          }          }
3881      }      }
3882    
3883        /**
3884         * Returns the first, lowest sorted, element from the underlying set.
3885         * A lock is obtained on the mutex before the set is accessed.
3886         *
3887         * @return the first element.
3888         * @throws NoSuchElementException if this set is empty.
3889         */
3890      public Object first()      public Object first()
3891      {      {
3892        synchronized (mutex)        synchronized (mutex)
# Line 2887  public class Collections Line 3895  public class Collections
3895          }          }
3896      }      }
3897    
3898        /**
3899         * Returns a subset containing the element from the first
3900         * element (as returned by <code>first()</code>) to
3901         * the element before that specified.  The subset supports all
3902         * operations supported by the underlying set and all actions
3903         * taking place on the subset are also reflected in the underlying
3904         * set.  A lock is obtained on the mutex prior to subset creation.
3905         * This operation is equivalent to <code>subSet(first(), toElement)</code>.
3906         * The subset retains the thread-safe status of this set.
3907         *
3908         * @param toElement the exclusive upper range of the subset.
3909         * @return a subset from <code>first()</code> to the
3910         *         the element preceding toElement.
3911         * @throws ClassCastException if toElement is not comparable to the underlying
3912         *         set's contents.
3913         * @throws IllegalArgumentException if toElement is outside the set's range.
3914         * @throws NullPointerException if toElement is null. but the set does not allow
3915         *         null elements.
3916         */
3917      public SortedSet headSet(Object toElement)      public SortedSet headSet(Object toElement)
3918      {      {
3919        synchronized (mutex)        synchronized (mutex)
# Line 2895  public class Collections Line 3922  public class Collections
3922          }          }
3923      }      }
3924    
3925        /**
3926         * Returns the last, highest sorted, element from the underlying set.
3927         * A lock is obtained on the mutex before the set is accessed.
3928         *
3929         * @return the last element.
3930         * @throws NoSuchElementException if this set is empty.
3931         */
3932      public Object last()      public Object last()
3933      {      {
3934        synchronized (mutex)        synchronized (mutex)
# Line 2903  public class Collections Line 3937  public class Collections
3937          }          }
3938      }      }
3939    
3940        /**
3941         * Returns a subset containing the elements from fromElement to
3942         * the element before toElement.  The subset supports all
3943         * operations supported by the underlying set and all actions
3944         * taking place on the subset are also reflected in the underlying
3945         * set.  A lock is obtained on the mutex prior to subset creation.
3946         * The subset retains the thread-safe status of this set.
3947         *
3948         * @param fromElement the inclusive lower range of the subset.
3949         * @param toElement the exclusive upper range of the subset.
3950         * @return a subset from fromElement to the element preceding toElement.
3951         * @throws ClassCastException if fromElement or toElement is not comparable
3952         *         to the underlying set's contents.
3953         * @throws IllegalArgumentException if fromElement or toElement is outside the set's
3954         *         range.
3955         * @throws NullPointerException if fromElement or toElement is null. but the set does
3956         *         not allow null elements.
3957         */
3958      public SortedSet subSet(Object fromElement, Object toElement)      public SortedSet subSet(Object fromElement, Object toElement)
3959      {      {
3960        synchronized (mutex)        synchronized (mutex)
# Line 2912  public class Collections Line 3964  public class Collections
3964          }          }
3965      }      }
3966    
3967        /**
3968         * Returns a subset containing all the elements from fromElement onwards.
3969         * The subset supports all operations supported by the underlying
3970         * set and all actions taking place on the subset are also reflected
3971         * in the underlying set.  A lock is obtained on the mutex prior to
3972         * subset creation.  The subset retains the thread-safe status of
3973         * this set.
3974         *
3975         * @param fromElement the inclusive lower range of the subset.
3976         * @return a subset from fromElement to <code>last()</code>.
3977         * @throws ClassCastException if fromElement is not comparable to the underlying
3978         *         set's contents.
3979         * @throws IllegalArgumentException if fromElement is outside the set's range.
3980         * @throws NullPointerException if fromElement is null. but the set does not allow
3981         *         null elements.
3982         */
3983      public SortedSet tailSet(Object fromElement)      public SortedSet tailSet(Object fromElement)
3984      {      {
3985        synchronized (mutex)        synchronized (mutex)
# Line 2926  public class Collections Line 3994  public class Collections
3994     * Returns an unmodifiable view of the given collection. This allows     * Returns an unmodifiable view of the given collection. This allows
3995     * "read-only" access, although changes in the backing collection show up     * "read-only" access, although changes in the backing collection show up
3996     * in this view. Attempts to modify the collection directly or via iterators     * in this view. Attempts to modify the collection directly or via iterators
3997     * will fail with {@link UnsupportedOperationException}.     * will fail with {@link UnsupportedOperationException}.  Although this view
3998       * prevents changes to the structure of the collection and its elements, the values
3999       * referenced by the objects in the collection can still be modified.
4000     * <p>     * <p>
4001     *     *
4002     * 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 2976  public class Collections Line 4046  public class Collections
4046          throw new NullPointerException();          throw new NullPointerException();
4047      }      }
4048    
4049        /**
4050         * Blocks the addition of elements to the underlying collection.
4051         * This method never returns, throwing an exception instead.
4052         *
4053         * @param o the object to add.
4054         * @return <code>true</code> if the collection was modified as a result of this action.
4055         * @throws UnsupportedOperationException as an unmodifiable collection does not
4056         *         support the add operation.
4057         */
4058      public boolean add(Object o)      public boolean add(Object o)
4059      {      {
4060        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4061      }      }
4062    
4063        /**
4064         * Blocks the addition of a collection of elements to the underlying
4065         * collection.  This method never returns, throwing an exception instead.
4066         *
4067         * @param c the collection to add.
4068         * @return <code>true</code> if the collection was modified as a result of this action.
4069         * @throws UnsupportedOperationException as an unmodifiable collection does not
4070         *         support the <code>addAll</code> operation.
4071         */
4072      public boolean addAll(Collection c)      public boolean addAll(Collection c)
4073      {      {
4074        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4075      }      }
4076    
4077        /**
4078         * Blocks the clearing of the underlying collection.  This method never
4079         * returns, throwing an exception instead.
4080         *
4081         * @throws UnsupportedOperationException as an unmodifiable collection does
4082         *         not support the <code>clear()</code> operation.
4083         */
4084      public void clear()      public void clear()
4085      {      {
4086        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4087      }      }
4088    
4089        /**
4090         * Test whether the underlying collection contains a given object as one of its
4091         * elements.
4092         *
4093         * @param o the element to look for.
4094         * @return <code>true</code> if the underlying collection contains at least
4095         *         one element e such that
4096         *         <code>o == null ? e == null : o.equals(e)</code>.
4097         * @throws ClassCastException if the type of o is not a valid type for the
4098         *         underlying collection.
4099         * @throws NullPointerException if o is null and the underlying collection
4100         *         doesn't support null values.
4101         */
4102      public boolean contains(Object o)      public boolean contains(Object o)
4103      {      {
4104        return c.contains(o);        return c.contains(o);
4105      }      }
4106    
4107        /**
4108         * Test whether the underlying collection contains every element in a given
4109         * collection.
4110         *
4111         * @param c the collection to test for.
4112         * @return <code>true</code> if for every element o in c, contains(o) would
4113         *         return <code>true</code>.
4114         * @throws ClassCastException if the type of any element in c is not a valid
4115         *   type for the underlying collection.
4116         * @throws NullPointerException if some element of c is null and the underlying
4117         *   collection does not support null values.
4118         * @throws NullPointerException if c itself is null.
4119         */
4120      public boolean containsAll(Collection c1)      public boolean containsAll(Collection c1)
4121      {      {
4122        return c.containsAll(c1);        return c.containsAll(c1);
4123      }      }
4124    
4125        /**
4126         * Tests whether the underlying collection is empty, that is,
4127         * if size() == 0.
4128         *
4129         * @return <code>true</code> if this collection contains no elements.
4130         */
4131      public boolean isEmpty()      public boolean isEmpty()
4132      {      {
4133        return c.isEmpty();        return c.isEmpty();
4134      }      }
4135    
4136        /**
4137         * Obtain an Iterator over the underlying collection, which maintains
4138         * its unmodifiable nature.
4139         *
4140         * @return an UnmodifiableIterator over the elements of the underlying
4141         *         collection, in any order.
4142         */
4143      public Iterator iterator()      public Iterator iterator()
4144      {      {
4145        return new UnmodifiableIterator(c.iterator());        return new UnmodifiableIterator(c.iterator());
4146      }      }
4147    
4148        /**
4149         * Blocks the removal of an object from the underlying collection.
4150         * This method never returns, throwing an exception instead.
4151         *
4152         * @param o The object to remove.
4153         * @return <code>true</code> if the object was removed (i.e. the underlying
4154         *         collection returned 1 or more instances of o).
4155         * @throws UnsupportedOperationException as an unmodifiable collection
4156         *         does not support the <code>remove()</code> operation.
4157         */
4158      public boolean remove(Object o)      public boolean remove(Object o)
4159      {      {
4160        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4161      }      }
4162    
4163        /**
4164         * Blocks the removal of a collection of objects from the underlying
4165         * collection.  This method never returns, throwing an exception
4166         * instead.
4167         *
4168         * @param c The collection of objects to remove.
4169         * @return <code>true</code> if the collection was modified.
4170         * @throws UnsupportedOperationException as an unmodifiable collection
4171         *         does not support the <code>removeAll()</code> operation.
4172         */
4173      public boolean removeAll(Collection c)      public boolean removeAll(Collection c)
4174      {      {
4175        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4176      }      }
4177    
4178        /**
4179         * Blocks the removal of all elements from the underlying collection,
4180         * except those in the supplied collection.  This method never returns,
4181         * throwing an exception instead.
4182         *
4183         * @param c The collection of objects to retain.
4184         * @return <code>true</code> if the collection was modified.
4185         * @throws UnsupportedOperationException as an unmodifiable collection
4186         *         does not support the <code>retainAll()</code> operation.
4187         */
4188      public boolean retainAll(Collection c)      public boolean retainAll(Collection c)
4189      {      {
4190        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4191      }      }
4192    
4193        /**
4194         * Retrieves the number of elements in the underlying collection.
4195         *
4196         * @return the number of elements in the collection.
4197         */
4198      public int size()      public int size()
4199      {      {
4200        return c.size();        return c.size();
4201      }      }
4202    
4203        /**
4204         * Copy the current contents of the underlying collection into an array.
4205         *
4206         * @return an array of type Object[] with a length equal to the size of the
4207         *         underlying collection and containing the elements currently in
4208         *         the underlying collection, in any order.
4209         */
4210      public Object[] toArray()      public Object[] toArray()
4211      {      {
4212        return c.toArray();        return c.toArray();
4213      }      }
4214    
4215        /**
4216         * Copy the current contents of the underlying collection into an array.  If
4217         * the array passed as an argument has length less than the size of the
4218         * underlying collection, an array of the same run-time type as a, with a length
4219         * equal to the size of the underlying collection, is allocated using reflection.
4220         * Otherwise, a itself is used.  The elements of the underlying collection are
4221         * copied into it, and if there is space in the array, the following element is
4222         * set to null. The resultant array is returned.
4223         * Note: The fact that the following element is set to null is only useful
4224         * if it is known that this collection does not contain any null elements.
4225         *
4226         * @param a the array to copy this collection into.
4227         * @return an array containing the elements currently in the underlying
4228         *         collection, in any order.
4229         * @throws ArrayStoreException if the type of any element of the
4230         *         collection is not a subtype of the element type of a.
4231         */
4232      public Object[] toArray(Object[] a)      public Object[] toArray(Object[] a)
4233      {      {
4234        return c.toArray(a);        return c.toArray(a);
4235      }      }
4236    
4237        /**
4238         * A textual representation of the unmodifiable collection.
4239         *
4240         * @return The unmodifiable collection in the form of a <code>String</code>.
4241         */
4242      public String toString()      public String toString()
4243      {      {
4244        return c.toString();        return c.toString();
# Line 3069  public class Collections Line 4267  public class Collections
4267        this.i = i;        this.i = i;
4268      }      }
4269    
4270        /**
4271         * Obtains the next element in the underlying collection.
4272         *
4273         * @return the next element in the collection.
4274         * @throws NoSuchElementException if there are no more elements.
4275         */
4276      public Object next()      public Object next()
4277      {      {
4278        return i.next();        return i.next();
4279      }      }
4280        /**
4281         * Tests whether there are still elements to be retrieved from the
4282         * underlying collection by <code>next()</code>.  When this method
4283         * returns <code>true</code>, an exception will not be thrown on calling
4284         * <code>next()</code>.
4285         *
4286         * @return <code>true</code> if there is at least one more element in the underlying
4287         *         collection.
4288         */
4289      public boolean hasNext()      public boolean hasNext()
4290      {      {
4291        return i.hasNext();        return i.hasNext();
4292      }      }
4293    
4294        /**
4295         * Blocks the removal of elements from the underlying collection by the
4296         * iterator.
4297         *
4298         * @throws UnsupportedOperationException as an unmodifiable collection
4299         *         does not support the removal of elements by its iterator.
4300         */
4301      public void remove()      public void remove()
4302      {      {
4303        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
# Line 3090  public class Collections Line 4309  public class Collections
4309     * "read-only" access, although changes in the backing list show up     * "read-only" access, although changes in the backing list show up
4310     * in this view. Attempts to modify the list directly, via iterators, or     * in this view. Attempts to modify the list directly, via iterators, or
4311     * via sublists, will fail with {@link UnsupportedOperationException}.     * via sublists, will fail with {@link UnsupportedOperationException}.
4312       * Although this view prevents changes to the structure of the list and
4313       * its elements, the values referenced by the objects in the list can
4314       * still be modified.  
4315     * <p>     * <p>
4316     *     *
4317     * The returned List implements Serializable, but can only be serialized if     * The returned List implements Serializable, but can only be serialized if
# Line 3142  public class Collections Line 4364  public class Collections
4364        list = l;        list = l;
4365      }      }
4366    
4367        /**
4368         * Blocks the addition of an element to the underlying
4369         * list at a specific index.  This method never returns,
4370         * throwing an exception instead.
4371         *
4372         * @param index The index at which to place the new element.
4373         * @param o the object to add.
4374         * @throws UnsupportedOperationException as an unmodifiable
4375         *         list doesn't support the <code>add()</code> operation.
4376         */
4377      public void add(int index, Object o)      public void add(int index, Object o)
4378      {      {
4379        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4380      }      }
4381    
4382        /**
4383         * Blocks the addition of a collection of elements to the
4384         * underlying list at a specific index.  This method never
4385         * returns, throwing an exception instead.
4386         *
4387         * @param index The index at which to place the new element.
4388         * @param c the collections of objects to add.
4389         * @throws UnsupportedOperationException as an unmodifiable
4390         *         list doesn't support the <code>addAll()</code> operation.
4391         */
4392      public boolean addAll(int index, Collection c)      public boolean addAll(int index, Collection c)
4393      {      {
4394        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4395      }      }
4396    
4397        /**
4398         * Returns <code>true</code> if the object, o, is an instance of
4399         * <code>List</code> with the same size and elements
4400         * as the underlying list.
4401         *
4402         * @param o The object to compare.
4403         * @return <code>true</code> if o is equivalent to the underlying list.
4404         */
4405      public boolean equals(Object o)      public boolean equals(Object o)
4406      {      {
4407        return list.equals(o);        return list.equals(o);
4408      }      }
4409    
4410        /**
4411         * Retrieves the element at a given index in the underlying list.
4412         *
4413         * @param index the index of the element to be returned
4414         * @return the element at index index in this list
4415         * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
4416         */
4417      public Object get(int index)      public Object get(int index)
4418      {      {
4419        return list.get(index);        return list.get(index);
4420      }      }
4421    
4422        /**
4423         * Computes the hash code for the underlying list.
4424         * The exact computation is described in the documentation
4425         * of the <code>List</code> interface.
4426         *
4427         * @return The hash code of the underlying list.
4428         * @see List#hashCode()
4429         */
4430      public int hashCode()      public int hashCode()
4431      {      {
4432        return list.hashCode();        return list.hashCode();
4433      }      }
4434    
4435        /**
4436         * Obtain the first index at which a given object is to be found in the
4437         * underlying list.
4438         *
4439         * @param o the object to search for
4440         * @return the least integer n such that <code>o == null ? get(n) == null :
4441         *         o.equals(get(n))</code>, or -1 if there is no such index.
4442         * @throws ClassCastException if the type of o is not a valid
4443         *         type for the underlying list.
4444         * @throws NullPointerException if o is null and the underlying
4445         *         list does not support null values.
4446         */
4447      public int indexOf(Object o)      public int indexOf(Object o)
4448      {      {
4449        return list.indexOf(o);        return list.indexOf(o);
4450      }      }
4451    
4452        /**
4453         * Obtain the last index at which a given object is to be found in the
4454         * underlying list.
4455         *
4456         * @return the greatest integer n such that <code>o == null ? get(n) == null
4457         *         : o.equals(get(n))</code>, or -1 if there is no such index.
4458         * @throws ClassCastException if the type of o is not a valid
4459         *         type for the underlying list.
4460         * @throws NullPointerException if o is null and the underlying
4461         *         list does not support null values.
4462         */
4463      public int lastIndexOf(Object o)      public int lastIndexOf(Object o)
4464      {      {
4465        return list.lastIndexOf(o);        return list.lastIndexOf(o);
4466      }      }
4467    
4468      /**
4469       * Obtains a list iterator over the underlying list, starting at the beginning
4470       * and maintaining the unmodifiable nature of this list.
4471       *
4472       * @return a <code>UnmodifiableListIterator</code> over the elements of the
4473       *         underlying list, in order, starting at the beginning.
4474       */
4475      public ListIterator listIterator()      public ListIterator listIterator()
4476      {      {
4477        return new UnmodifiableListIterator(list.listIterator());        return new UnmodifiableListIterator(list.listIterator());
4478      }      }
4479    
4480      /**
4481       * Obtains a list iterator over the underlying list, starting at the specified
4482       * index and maintaining the unmodifiable nature of this list.  An initial call
4483       * to <code>next()</code> will retrieve the element at the specified index,
4484       * and an initial call to <code>previous()</code> will retrieve the element
4485       * at index - 1.
4486       *
4487       *
4488       * @param index the position, between 0 and size() inclusive, to begin the
4489       *        iteration from.
4490       * @return a <code>UnmodifiableListIterator</code> over the elements of the
4491       *         underlying list, in order, starting at the specified index.
4492       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
4493       */
4494      public ListIterator listIterator(int index)      public ListIterator listIterator(int index)
4495      {      {
4496        return new UnmodifiableListIterator(list.listIterator(index));        return new UnmodifiableListIterator(list.listIterator(index));
4497      }      }
4498    
4499        /**
4500         * Blocks the removal of the element at the specified index.
4501         * This method never returns, throwing an exception instead.
4502         *
4503         * @param index The index of the element to remove.
4504         * @return the removed element.
4505         * @throws UnsupportedOperationException as an unmodifiable
4506         *         list does not support the <code>remove()</code>
4507         *         operation.
4508         */
4509      public Object remove(int index)      public Object remove(int index)
4510      {      {
4511        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4512      }      }
4513    
4514        /**
4515         * Blocks the replacement of the element at the specified index.
4516         * This method never returns, throwing an exception instead.
4517         *
4518         * @param index The index of the element to replace.
4519         * @param o The new object to place at the specified index.
4520         * @return the replaced element.
4521         * @throws UnsupportedOperationException as an unmodifiable
4522         *         list does not support the <code>set()</code>
4523         *         operation.
4524         */
4525      public Object set(int index, Object o)      public Object set(int index, Object o)
4526      {      {
4527        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4528      }      }
4529    
4530        /**
4531         * Obtain a List view of a subsection of the underlying list, from
4532         * fromIndex (inclusive) to toIndex (exclusive). If the two indices
4533         * are equal, the sublist is empty. The returned list will be
4534         * unmodifiable, like this list.  Changes to the elements of the
4535         * returned list will be reflected in the underlying list. No structural
4536         * modifications can take place in either list.
4537         *
4538         * @param fromIndex the index that the returned list should start from
4539         *        (inclusive).
4540         * @param toIndex the index that the returned list should go to (exclusive).
4541         * @return a List backed by a subsection of the underlying list.
4542         * @throws IndexOutOfBoundsException if fromIndex &lt; 0
4543         *         || toIndex &gt; size() || fromIndex &gt; toIndex.
4544         */
4545      public List subList(int fromIndex, int toIndex)      public List subList(int fromIndex, int toIndex)
4546      {      {
4547        return unmodifiableList(list.subList(fromIndex, toIndex));        return unmodifiableList(list.subList(fromIndex, toIndex));
# Line 3253  public class Collections Line 4598  public class Collections
4598        this.li = li;        this.li = li;
4599      }      }
4600    
4601        /**
4602         * Blocks the addition of an object to the list underlying this iterator.
4603         * This method never returns, throwing an exception instead.
4604         *
4605         * @param o The object to add.
4606         * @throws UnsupportedOperationException as the iterator of an unmodifiable
4607         *         list does not support the <code>add()</code> operation.
4608         */
4609      public void add(Object o)      public void add(Object o)
4610      {      {
4611        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4612      }      }
4613    
4614        /**
4615         * Tests whether there are still elements to be retrieved from the
4616         * underlying collection by <code>previous()</code>.  When this method
4617         * returns <code>true</code>, an exception will not be thrown on calling
4618         * <code>previous()</code>.
4619         *
4620         * @return <code>true</code> if there is at least one more element prior to the
4621         *         current position in the underlying list.
4622         */
4623      public boolean hasPrevious()      public boolean hasPrevious()
4624      {      {
4625        return li.hasPrevious();        return li.hasPrevious();
4626      }      }
4627    
4628        /**
4629         * Find the index of the element that would be returned by a call to next.
4630         * If <code>hasNext()</code> returns <code>false</code>, this returns the list size.
4631         *
4632         * @return the index of the element that would be returned by
4633         *         <code>next()</code>.
4634         */
4635      public int nextIndex()      public int nextIndex()
4636      {      {
4637        return li.nextIndex();        return li.nextIndex();
4638      }      }
4639    
4640        /**
4641         * Obtains the previous element in the underlying list.
4642         *
4643         * @return the previous element in the list.
4644         * @throws NoSuchElementException if there are no more prior elements.
4645         */
4646      public Object previous()      public Object previous()
4647      {      {
4648        return li.previous();        return li.previous();
4649      }      }
4650    
4651        /**
4652         * Find the index of the element that would be returned by a call to
4653         * previous. If <code>hasPrevious()</code> returns <code>false</code>,
4654         * this returns -1.
4655         *
4656         * @return the index of the element that would be returned by
4657         *         <code>previous()</code>.
4658         */
4659      public int previousIndex()      public int previousIndex()
4660      {      {
4661        return li.previousIndex();        return li.previousIndex();
4662      }      }
4663    
4664        /**
4665         * Blocks the replacement of an element in the list underlying this
4666         * iterator.  This method never returns, throwing an exception instead.
4667         *
4668         * @param o The new object to replace the existing one.
4669         * @throws UnsupportedOperationException as the iterator of an unmodifiable
4670         *         list does not support the <code>set()</code> operation.
4671         */
4672      public void set(Object o)      public void set(Object o)
4673      {      {
4674        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
# Line 3289  public class Collections Line 4680  public class Collections
4680     * access, although changes in the backing map show up in this view.     * access, although changes in the backing map show up in this view.
4681     * Attempts to modify the map directly, or via collection views or their     * Attempts to modify the map directly, or via collection views or their
4682     * iterators will fail with {@link UnsupportedOperationException}.     * iterators will fail with {@link UnsupportedOperationException}.
4683       * Although this view prevents changes to the structure of the map and its
4684       * entries, the values referenced by the objects in the map can still be
4685       * modified.  
4686     * <p>     * <p>
4687     *     *
4688     * The returned Map implements Serializable, but can only be serialized if     * The returned Map implements Serializable, but can only be serialized if
# Line 3349  public class Collections Line 4743  public class Collections
4743          throw new NullPointerException();          throw new NullPointerException();
4744      }      }
4745    
4746        /**
4747         * Blocks the clearing of entries from the underlying map.
4748         * This method never returns, throwing an exception instead.
4749         *
4750         * @throws UnsupportedOperationException as an unmodifiable
4751         *         map does not support the <code>clear()</code> operation.
4752         */
4753      public void clear()      public void clear()
4754      {      {
4755        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4756      }      }
4757    
4758        /**
4759         * Returns <code>true</code> if the underlying map contains a mapping for
4760         * the given key.
4761         *
4762         * @param key the key to search for
4763         * @return <code>true</code> if the map contains the key
4764         * @throws ClassCastException if the key is of an inappropriate type
4765         * @throws NullPointerException if key is <code>null</code> but the map
4766         *         does not permit null keys
4767         */
4768      public boolean containsKey(Object key)      public boolean containsKey(Object key)
4769      {      {
4770        return m.containsKey(key);        return m.containsKey(key);
4771      }      }
4772    
4773        /**
4774         * Returns <code>true</code> if the underlying map contains at least one mapping with
4775         * the given value.  In other words, it returns <code>true</code> if a value v exists where
4776         * <code>(value == null ? v == null : value.equals(v))</code>. This usually
4777         * requires linear time.
4778         *
4779         * @param value the value to search for
4780         * @return <code>true</code> if the map contains the value
4781         * @throws ClassCastException if the type of the value is not a valid type
4782         *         for this map.
4783         * @throws NullPointerException if the value is null and the map doesn't
4784         *         support null values.
4785         */
4786      public boolean containsValue(Object value)      public boolean containsValue(Object value)
4787      {      {
4788        return m.containsValue(value);        return m.containsValue(value);
4789      }      }
4790    
4791        /**
4792         * Returns a unmodifiable set view of the entries in the underlying map.
4793         * Each element in the set is a unmodifiable variant of <code>Map.Entry</code>.
4794         * The set is backed by the map, so that changes in one show up in the other.
4795         * Modifications made while an iterator is in progress cause undefined
4796         * behavior.  These modifications are again limited to the values of
4797         * the objects.
4798         *
4799         * @return the unmodifiable set view of all mapping entries.
4800         * @see Map.Entry
4801         */
4802      public Set entrySet()      public Set entrySet()
4803      {      {
4804        if (entries == null)        if (entries == null)
# Line 3399  public class Collections Line 4834  public class Collections
4834        {        {
4835          return new UnmodifiableIterator(c.iterator())          return new UnmodifiableIterator(c.iterator())
4836          {          {
4837              /**
4838               * Obtains the next element from the underlying set of
4839               * map entries.
4840               *
4841               * @return the next element in the collection.
4842               * @throws NoSuchElementException if there are no more elements.
4843               */
4844            public Object next()            public Object next()
4845            {            {
4846              final Map.Entry e = (Map.Entry) super.next();              final Map.Entry e = (Map.Entry) super.next();
4847              return new Map.Entry()              return new Map.Entry()
4848              {              {
4849                  /**
4850                   * Returns <code>true</code> if the object, o, is also a map entry with an
4851                   * identical key and value.
4852                   *
4853                   * @param o the object to compare.
4854                   * @return <code>true</code> if o is an equivalent map entry.
4855                   */
4856                public boolean equals(Object o)                public boolean equals(Object o)
4857                {                {
4858                  return e.equals(o);                  return e.equals(o);
4859                }                }
4860                  
4861                  /**
4862                   * Returns the key of this map entry.
4863                   *
4864                   * @return the key.
4865                   */
4866                public Object getKey()                public Object getKey()
4867                {                {
4868                  return e.getKey();                  return e.getKey();
4869                }                }
4870    
4871                  /**
4872                   * Returns the value of this map entry.
4873                   *
4874                   * @return the value.
4875                   */
4876                public Object getValue()                public Object getValue()
4877                {                {
4878                  return e.getValue();                  return e.getValue();
4879                }                }
4880    
4881                  /**
4882                   * Computes the hash code of this map entry.
4883                   * The computation is described in the <code>Map</code>
4884                   * interface documentation.
4885                   *
4886                   * @return the hash code of this entry.
4887                   * @see Map#hashCode()
4888                   */
4889                public int hashCode()                public int hashCode()
4890                {                {
4891                  return e.hashCode();                  return e.hashCode();
4892                }                }
4893    
4894                  /**
4895                   * Blocks the alteration of the value of this map entry.
4896                   * This method never returns, throwing an exception instead.
4897                   *
4898                   * @param value The new value.
4899                   * @throws UnsupportedOperationException as an unmodifiable
4900                   *         map entry does not support the <code>setValue()</code>
4901                   *         operation.
4902                   */
4903                public Object setValue(Object value)                public Object setValue(Object value)
4904                {                {
4905                  throw new UnsupportedOperationException();                  throw new UnsupportedOperationException();
4906                }                }
4907    
4908                  /**
4909                   * Returns a textual representation of the map entry.
4910                   *
4911                   * @return The map entry as a <code>String</code>.
4912                   */
4913                public String toString()                public String toString()
4914                {                {
4915                  return e.toString();                  return e.toString();
# Line 3434  public class Collections Line 4920  public class Collections
4920        }        }
4921      } // class UnmodifiableEntrySet      } // class UnmodifiableEntrySet
4922    
4923        /**
4924         * Returns <code>true</code> if the object, o, is also an instance
4925         * of <code>Map</code> with an equal set of map entries.
4926         *
4927         * @param o The object to compare.
4928         * @return <code>true</code> if o is an equivalent map.
4929         */
4930      public boolean equals(Object o)      public boolean equals(Object o)
4931      {      {
4932        return m.equals(o);        return m.equals(o);
4933      }      }
4934    
4935        /**
4936         * Returns the value associated with the supplied key or
4937         * null if no such mapping exists.  An ambiguity can occur
4938         * if null values are accepted by the underlying map.
4939         * In this case, <code>containsKey()</code> can be used
4940         * to separate the two possible cases of a null result.
4941         *
4942         * @param key The key to look up.
4943         * @return the value associated with the key, or null if key not in map.
4944         * @throws ClassCastException if the key is an inappropriate type.
4945         * @throws NullPointerException if this map does not accept null keys.
4946         * @see #containsKey(Object)
4947         */
4948      public Object get(Object key)      public Object get(Object key)
4949      {      {
4950        return m.get(key);        return m.get(key);
4951      }      }
4952    
4953        /**
4954         * Blocks the addition of a new entry to the underlying map.
4955         * This method never returns, throwing an exception instead.
4956         *
4957         * @param key The new key.
4958         * @param value The new value.
4959         * @return the previous value of the key, or null if there was no mapping.
4960         * @throws UnsupportedOperationException as an unmodifiable
4961         *         map does not support the <code>put()</code> operation.
4962         */
4963      public Object put(Object key, Object value)      public Object put(Object key, Object value)
4964      {      {
4965        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
4966      }      }
4967    
4968        /**
4969         * Computes the hash code for the underlying map, as the sum
4970         * of the hash codes of all entries.
4971         *
4972         * @return The hash code of the underlying map.
4973         * @see Map.Entry#hashCode()
4974         */
4975      public int hashCode()      public int hashCode()
4976      {      {
4977        return m.hashCode();        return m.hashCode();
4978      }      }
4979    
4980        /**
4981         * Returns <code>true</code> if the underlying map contains no entries.
4982         *
4983         * @return <code>true</code> if the map is empty.
4984         */
4985      public boolean isEmpty()      public boolean isEmpty()
4986      {      {
4987        return m.isEmpty();        return m.isEmpty();
4988      }      }
4989    
4990        /**
4991         * Returns a unmodifiable set view of the keys in the underlying map.
4992         * The set is backed by the map, so that changes in one show up in the other.
4993         * Modifications made while an iterator is in progress cause undefined
4994         * behavior.  These modifications are again limited to the values of
4995         * the keys.
4996         *
4997         * @return the set view of all keys.
4998         */
4999      public Set keySet()      public Set keySet()
5000      {      {
5001        if (keys == null)        if (keys == null)
# Line 3466  public class Collections Line 5003  public class Collections
5003        return keys;        return keys;
5004      }      }
5005    
5006        /**
5007         * Blocks the addition of the entries in the supplied map.
5008         * This method never returns, throwing an exception instead.
5009         *
5010         * @param m The map, the entries of which should be added
5011         *          to the underlying map.
5012         * @throws UnsupportedOperationException as an unmodifiable
5013         *         map does not support the <code>putAll</code> operation.
5014         */
5015      public void putAll(Map m)      public void putAll(Map m)
5016      {      {
5017        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
5018      }      }
5019    
5020        /**
5021         * Blocks the removal of an entry from the map.
5022         * This method never returns, throwing an exception instead.
5023         *
5024         * @param o The key of the entry to remove.
5025         * @return The value the key was associated with, or null
5026         *         if no such mapping existed.  Null is also returned
5027         *         if the removed entry had a null key.
5028         * @throws UnsupportedOperationException as an unmodifiable
5029         *         map does not support the <code>remove</code> operation.
5030         */
5031      public Object remove(Object o)      public Object remove(Object o)
5032      {      {
5033        throw new UnsupportedOperationException();        throw new UnsupportedOperationException();
5034      }      }
5035    
5036    
5037        /**
5038         * Returns the number of key-value mappings in the underlying map.
5039         * If there are more than Integer.MAX_VALUE mappings, Integer.MAX_VALUE
5040         * is returned.
5041         *
5042         * @return the number of mappings.
5043         */
5044      public int size()      public int size()
5045      {      {
5046        return m.size();        return m.size();
5047      }      }
5048    
5049        /**
5050         * Returns a textual representation of the map.
5051         *
5052         * @return The map in the form of a <code>String</code>.
5053         */
5054      public String toString()      public String toString()
5055      {      {
5056        return m.toString();        return m.toString();
5057      }      }
5058    
5059        /**
5060         * Returns a unmodifiable collection view of the values in the underlying map.
5061         * The collection is backed by the map, so that changes in one show up in the other.
5062         * Modifications made while an iterator is in progress cause undefined
5063         * behavior.  These modifications are again limited to the values of
5064         * the keys.
5065         *
5066         * @return the collection view of all values.
5067         */
5068      public Collection values()      public Collection values()
5069      {      {
5070        if (values == null)        if (values == null)
# Line 3499  public class Collections Line 5078  public class Collections
5078     * "read-only" access, although changes in the backing set show up     * "read-only" access, although changes in the backing set show up
5079     * in this view. Attempts to modify the set directly or via iterators     * in this view. Attempts to modify the set directly or via iterators
5080     * will fail with {@link UnsupportedOperationException}.     * will fail with {@link UnsupportedOperationException}.
5081       * Although this view prevents changes to the structure of the set and its
5082       * entries, the values referenced by the objects in the set can still be
5083       * modified.  
5084     * <p>     * <p>
5085     *     *
5086     * The returned Set implements Serializable, but can only be serialized if     * The returned Set implements Serializable, but can only be serialized if
# Line 3537  public class Collections Line 5119  public class Collections
5119        super(s);        super(s);
5120      }      }
5121    
5122        /**
5123         * Returns <code>true</code> if the object, o, is also an instance of
5124         * <code>Set</code> of the same size and with the same entries.
5125         *
5126         * @return <code>true</code> if o is an equivalent set.
5127         */
5128      public boolean equals(Object o)      public boolean equals(Object o)
5129      {      {
5130        return c.equals(o);        return c.equals(o);
5131      }      }
5132    
5133        /**
5134         * Computes the hash code of this set, as the sum of the
5135         * hash codes of all elements within the set.
5136         *
5137         * @return the hash code of the set.
5138         */
5139      public int hashCode()      public int hashCode()
5140      {      {
5141        return c.hashCode();        return c.hashCode();
# Line 3553  public class Collections Line 5147  public class Collections
5147     * "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
5148     * view. Attempts to modify the map directly, via subviews, via collection     * view. Attempts to modify the map directly, via subviews, via collection
5149     * views, or iterators, will fail with {@link UnsupportedOperationException}.     * views, or iterators, will fail with {@link UnsupportedOperationException}.
5150       * Although this view prevents changes to the structure of the map and its
5151       * entries, the values referenced by the objects in the map can still be
5152       * modified.  
5153     * <p>     * <p>
5154     *     *
5155     * The returned SortedMap implements Serializable, but can only be     * The returned SortedMap implements Serializable, but can only be
# Line 3599  public class Collections Line 5196  public class Collections
5196        this.sm = sm;        this.sm = sm;
5197      }      }
5198    
5199        /**
5200         * Returns the comparator used in sorting the underlying map,
5201         * or null if it is the keys' natural ordering.
5202         *
5203         * @return the sorting comparator.
5204         */
5205      public Comparator comparator()      public Comparator comparator()
5206      {      {
5207        return sm.comparator();        return sm.comparator();
5208      }      }
5209    
5210        /**
5211         * Returns the first (lowest sorted) key in the map.
5212         *
5213         * @return the first key.
5214         * @throws NoSuchElementException if this map is empty.
5215         */
5216      public Object firstKey()      public Object firstKey()
5217      {      {
5218        return sm.firstKey();        return sm.firstKey();
5219      }      }
5220    
5221        /**
5222         * Returns a unmodifiable view of the portion of the map strictly less
5223         * than toKey. The view is backed by the underlying map, so changes in
5224         * one show up in the other.  The submap supports all optional operations
5225         * of the original.  This operation is equivalent to
5226         * <code>subMap(firstKey(), toKey)</code>.
5227         * <p>
5228         *
5229         * The returned map throws an IllegalArgumentException any time a key is
5230         * used which is out of the range of toKey. Note that the endpoint, toKey,
5231         * is not included; if you want this value to be included, pass its successor
5232         * object in to toKey.  For example, for Integers, you could request
5233         * <code>headMap(new Integer(limit.intValue() + 1))</code>.
5234         *
5235         * @param toKey the exclusive upper range of the submap.
5236         * @return the submap.
5237         * @throws ClassCastException if toKey is not comparable to the map contents.
5238         * @throws IllegalArgumentException if this is a subMap, and toKey is out
5239         *         of range.
5240         * @throws NullPointerException if toKey is null but the map does not allow
5241         *         null keys.
5242         */
5243      public SortedMap headMap(Object toKey)      public SortedMap headMap(Object toKey)
5244      {      {
5245        return new UnmodifiableSortedMap(sm.headMap(toKey));        return new UnmodifiableSortedMap(sm.headMap(toKey));
5246      }      }
5247    
5248        /**
5249         * Returns the last (highest sorted) key in the map.
5250         *
5251         * @return the last key.
5252         * @throws NoSuchElementException if this map is empty.
5253         */
5254      public Object lastKey()      public Object lastKey()
5255      {      {
5256        return sm.lastKey();        return sm.lastKey();
5257      }      }
5258    
5259        /**
5260         * Returns a unmodifiable view of the portion of the map greater than or
5261         * equal to fromKey, and strictly less than toKey. The view is backed by
5262         * the underlying map, so changes in one show up in the other. The submap
5263         * supports all optional operations of the original.
5264         * <p>
5265         *
5266         * The returned map throws an IllegalArgumentException any time a key is
5267         * used which is out of the range of fromKey and toKey. Note that the
5268         * lower endpoint is included, but the upper is not; if you want to
5269         * change the inclusion or exclusion of an endpoint, pass its successor
5270         * object in instead.  For example, for Integers, you could request
5271         * <code>subMap(new Integer(lowlimit.intValue() + 1),
5272         * new Integer(highlimit.intValue() + 1))</code> to reverse
5273         * the inclusiveness of both endpoints.
5274         *
5275         * @param fromKey the inclusive lower range of the submap.
5276         * @param toKey the exclusive upper range of the submap.
5277         * @return the submap.
5278         * @throws ClassCastException if fromKey or toKey is not comparable to
5279         *         the map contents.
5280         * @throws IllegalArgumentException if this is a subMap, and fromKey or
5281         *         toKey is out of range.
5282         * @throws NullPointerException if fromKey or toKey is null but the map
5283         *         does not allow null keys.
5284         */
5285      public SortedMap subMap(Object fromKey, Object toKey)      public SortedMap subMap(Object fromKey, Object toKey)
5286      {      {
5287        return new UnmodifiableSortedMap(sm.subMap(fromKey, toKey));        return new UnmodifiableSortedMap(sm.subMap(fromKey, toKey));
5288      }      }
5289    
5290        /**
5291         * Returns a unmodifiable view of the portion of the map greater than or
5292         * equal to fromKey. The view is backed by the underlying map, so changes
5293         * in one show up in the other. The submap supports all optional operations
5294         * of the original.
5295         * <p>
5296         *
5297         * The returned map throws an IllegalArgumentException any time a key is
5298         * used which is out of the range of fromKey. Note that the endpoint, fromKey, is
5299         * included; if you do not want this value to be included, pass its successor object in
5300         * to fromKey.  For example, for Integers, you could request
5301         * <code>tailMap(new Integer(limit.intValue() + 1))</code>.
5302         *
5303         * @param fromKey the inclusive lower range of the submap
5304         * @return the submap
5305         * @throws ClassCastException if fromKey is not comparable to the map
5306         *         contents
5307         * @throws IllegalArgumentException if this is a subMap, and fromKey is out
5308         *         of range
5309         * @throws NullPointerException if fromKey is null but the map does not allow
5310         *         null keys
5311         */
5312      public SortedMap tailMap(Object fromKey)      public SortedMap tailMap(Object fromKey)
5313      {      {
5314        return new UnmodifiableSortedMap(sm.tailMap(fromKey));        return new UnmodifiableSortedMap(sm.tailMap(fromKey));
# Line 3635  public class Collections Line 5320  public class Collections
5320     * "read-only" access, although changes in the backing set show up     * "read-only" access, although changes in the backing set show up
5321     * 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
5322     * iterators, will fail with {@link UnsupportedOperationException}.     * iterators, will fail with {@link UnsupportedOperationException}.
5323       * Although this view prevents changes to the structure of the set and its
5324       * entries, the values referenced by the objects in the set can still be
5325       * modified.  
5326     * <p>     * <p>
5327     *     *
5328     * The returns SortedSet implements Serializable, but can only be     * The returns SortedSet implements Serializable, but can only be
# Line 3681  public class Collections Line 5369  public class Collections
5369        this.ss = ss;        this.ss = ss;
5370      }      }
5371    
5372        /**
5373         * Returns the comparator used in sorting the underlying set,
5374         * or null if it is the elements' natural ordering.
5375         *
5376         * @return the sorting comparator
5377         */
5378      public Comparator comparator()      public Comparator comparator()
5379      {      {
5380        return ss.comparator();        return ss.comparator();
5381      }      }
5382    
5383        /**
5384         * Returns the first (lowest sorted) element in the underlying
5385         * set.
5386         *
5387         * @return the first element.
5388         * @throws NoSuchElementException if the set is empty.
5389         */
5390      public Object first()      public Object first()
5391      {      {
5392        return ss.first();        return ss.first();
5393      }      }
5394    
5395        /**
5396         * Returns a unmodifiable view of the portion of the set strictly
5397         * less than toElement. The view is backed by the underlying set,
5398         * so changes in one show up in the other.  The subset supports
5399         * all optional operations of the original.  This operation
5400         * is equivalent to <code>subSet(first(), toElement)</code>.
5401         * <p>
5402         *
5403         * The returned set throws an IllegalArgumentException any time an element is
5404         * used which is out of the range of toElement. Note that the endpoint, toElement,
5405         * is not included; if you want this value included, pass its successor object in to
5406         * toElement.  For example, for Integers, you could request
5407         * <code>headSet(new Integer(limit.intValue() + 1))</code>.
5408         *
5409         * @param toElement the exclusive upper range of the subset
5410         * @return the subset.
5411         * @throws ClassCastException if toElement is not comparable to the set
5412         *         contents.
5413         * @throws IllegalArgumentException if this is a subSet, and toElement is out
5414         *         of range.
5415         * @throws NullPointerException if toElement is null but the set does not
5416         *         allow null elements.
5417         */
5418      public SortedSet headSet(Object toElement)      public SortedSet headSet(Object toElement)
5419      {      {
5420        return new UnmodifiableSortedSet(ss.headSet(toElement));        return new UnmodifiableSortedSet(ss.headSet(toElement));
5421      }      }
5422    
5423        /**
5424         * Returns the last (highest sorted) element in the underlying
5425         * set.
5426         *
5427         * @return the last element.
5428         * @throws NoSuchElementException if the set is empty.
5429         */
5430      public Object last()      public Object last()
5431      {      {
5432        return ss.last();        return ss.last();
5433      }      }
5434    
5435        /**
5436         * Returns a unmodifiable view of the portion of the set greater than or
5437         * equal to fromElement, and strictly less than toElement. The view is backed by
5438         * the underlying set, so changes in one show up in the other. The subset
5439         * supports all optional operations of the original.
5440         * <p>
5441         *
5442         * The returned set throws an IllegalArgumentException any time an element is
5443         * used which is out of the range of fromElement and toElement. Note that the
5444         * lower endpoint is included, but the upper is not; if you want to
5445         * change the inclusion or exclusion of an endpoint, pass its successor
5446         * object in instead.  For example, for Integers, you can request
5447         * <code>subSet(new Integer(lowlimit.intValue() + 1),
5448         * new Integer(highlimit.intValue() + 1))</code> to reverse
5449         * the inclusiveness of both endpoints.
5450         *
5451         * @param fromElement the inclusive lower range of the subset.
5452         * @param toElement the exclusive upper range of the subset.
5453         * @return the subset.
5454         * @throws ClassCastException if fromElement or toElement is not comparable
5455         *         to the set contents.
5456         * @throws IllegalArgumentException if this is a subSet, and fromElement or
5457         *         toElement is out of range.
5458         * @throws NullPointerException if fromElement or toElement is null but the
5459         *         set does not allow null elements.
5460         */
5461      public SortedSet subSet(Object fromElement, Object toElement)      public SortedSet subSet(Object fromElement, Object toElement)
5462      {      {
5463        return new UnmodifiableSortedSet(ss.subSet(fromElement, toElement));        return new UnmodifiableSortedSet(ss.subSet(fromElement, toElement));
5464      }      }
5465    
5466        /**
5467         * Returns a unmodifiable view of the portion of the set greater than or equal to
5468         * fromElement. The view is backed by the underlying set, so changes in one show up
5469         * in the other. The subset supports all optional operations of the original.
5470         * <p>
5471         *
5472         * The returned set throws an IllegalArgumentException any time an element is
5473         * used which is out of the range of fromElement. Note that the endpoint,
5474         * fromElement, is included; if you do not want this value to be included, pass its
5475         * successor object in to fromElement.  For example, for Integers, you could request
5476         * <code>tailSet(new Integer(limit.intValue() + 1))</code>.
5477         *
5478         * @param fromElement the inclusive lower range of the subset
5479         * @return the subset.
5480         * @throws ClassCastException if fromElement is not comparable to the set
5481         *         contents.
5482         * @throws IllegalArgumentException if this is a subSet, and fromElement is
5483         *         out of range.
5484         * @throws NullPointerException if fromElement is null but the set does not
5485         *         allow null elements.
5486         */
5487      public SortedSet tailSet(Object fromElement)      public SortedSet tailSet(Object fromElement)
5488      {      {
5489        return new UnmodifiableSortedSet(ss.tailSet(fromElement));        return new UnmodifiableSortedSet(ss.tailSet(fromElement));

Legend:
Removed from v.1.31  
changed lines
  Added in v.1.32

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