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