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; |
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 |
{ |
{ |
130 |
|
|
131 |
/** |
/** |
132 |
* The size: always 0! |
* The size: always 0! |
133 |
|
* @return 0. |
134 |
*/ |
*/ |
135 |
public int size() |
public int size() |
136 |
{ |
{ |
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() |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
523 |
|
|
524 |
/** |
/** |
525 |
* No entries. |
* No entries. |
526 |
|
* @return The empty set. |
527 |
*/ |
*/ |
528 |
public Set keySet() |
public Set keySet() |
529 |
{ |
{ |
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 |
{ |
{ |
542 |
|
|
543 |
/** |
/** |
544 |
* Size is always 0. |
* Size is always 0. |
545 |
|
* @return 0. |
546 |
*/ |
*/ |
547 |
public int size() |
public int size() |
548 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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(); |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
*/ |
*/ |
1411 |
|
|
1412 |
/** |
/** |
1413 |
* The size: always 1! |
* The size: always 1! |
1414 |
|
* @return 1. |
1415 |
*/ |
*/ |
1416 |
public int size() |
public int size() |
1417 |
{ |
{ |
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) |
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(); |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
1584 |
|
|
1585 |
/** |
/** |
1586 |
* The size: always 1! |
* The size: always 1! |
1587 |
|
* @return 1. |
1588 |
*/ |
*/ |
1589 |
public int size() |
public int size() |
1590 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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(); |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
1861 |
|
|
1862 |
/** |
/** |
1863 |
* The size: always 1! |
* The size: always 1! |
1864 |
|
* |
1865 |
|
* @return 1. |
1866 |
*/ |
*/ |
1867 |
public int size() |
public int size() |
1868 |
{ |
{ |
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 |
{ |
{ |
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 |
{ |
{ |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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 < 0 || index > 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) |
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) |
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) |
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 < 0 || index >= size() |
2571 |
|
*/ |
2572 |
public Object get(int index) |
public Object get(int index) |
2573 |
{ |
{ |
2574 |
synchronized (mutex) |
synchronized (mutex) |
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) |
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) |
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) |
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) |
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 < 0 || index > size() |
2673 |
|
*/ |
2674 |
public ListIterator listIterator(int index) |
public ListIterator listIterator(int index) |
2675 |
{ |
{ |
2676 |
synchronized (mutex) |
synchronized (mutex) |
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 < 0 || index >= size() |
2692 |
|
*/ |
2693 |
public Object remove(int index) |
public Object remove(int index) |
2694 |
{ |
{ |
2695 |
synchronized (mutex) |
synchronized (mutex) |
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 < 0 || index >= 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) |
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 < 0 |
2743 |
|
* || toIndex > size() || fromIndex > toIndex |
2744 |
|
*/ |
2745 |
public List subList(int fromIndex, int toIndex) |
public List subList(int fromIndex, int toIndex) |
2746 |
{ |
{ |
2747 |
synchronized (mutex) |
synchronized (mutex) |
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 < 0 |
2807 |
|
* || toIndex > size() || fromIndex > toIndex |
2808 |
|
*/ |
2809 |
public List subList(int fromIndex, int toIndex) |
public List subList(int fromIndex, int toIndex) |
2810 |
{ |
{ |
2811 |
synchronized (mutex) |
synchronized (mutex) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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(); |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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) |
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 |
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(); |
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(); |
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 |
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 < 0 || index >= 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 < 0 || index > 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 < 0 |
4543 |
|
* || toIndex > size() || fromIndex > 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)); |
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(); |
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 |
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) |
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(); |
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) |
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) |
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 |
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(); |
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 |
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)); |
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 |
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)); |