java 泛型类_java中的泛型类及其使用

1 /*

2 * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.3 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.4 *5 *6 *7 *8 *9 *10 *11 *12 *13 *14 *15 *16 *17 *18 *19 *20 *21 *22 *23 *24 */

25

26 packagejava.util;27

28 /**

29 * An ordered collection (also known as a sequence). The user of this30 * interface has precise control over where in the list each element is31 * inserted. The user can access elements by their integer index (position in32 * the list), and search for elements in the list.

33 *34 * Unlike sets, lists typically allow duplicate elements. More formally,35 * lists typically allow pairs of elements e1 and e236 * such that e1.equals(e2), and they typically allow multiple37 * null elements if they allow null elements at all. It is not inconceivable38 * that someone might wish to implement a list that prohibits duplicates, by39 * throwing runtime exceptions when the user attempts to insert them, but we40 * expect this usage to be rare.

41 *42 * The List interface places additional stipulations, beyond those43 * specified in the Collection interface, on the contracts of the44 * iterator, add, remove, equals, and45 * hashCode methods. Declarations for other inherited methods are46 * also included here for convenience.

47 *48 * The List interface provides four methods for positional (indexed)49 * access to list elements. Lists (like Java arrays) are zero based. Note50 * that these operations may execute in time proportional to the index value51 * for some implementations (the LinkedList class, for52 * example). Thus, iterating over the elements in a list is typically53 * preferable to indexing through it if the caller does not know the54 * implementation.

55 *56 * The List interface provides a special iterator, called a57 * ListIterator, that allows element insertion and replacement, and58 * bidirectional access in addition to the normal operations that the59 * Iterator interface provides. A method is provided to obtain a60 * list iterator that starts at a specified position in the list.

61 *62 * The List interface provides two methods to search for a specified63 * object. From a performance standpoint, these methods should be used with64 * caution. In many implementations they will perform costly linear65 * searches.

66 *67 * The List interface provides two methods to efficiently insert and68 * remove multiple elements at an arbitrary point in the list.

69 *70 * Note: While it is permissible for lists to contain themselves as elements,71 * extreme caution is advised: the equals and hashCode72 * methods are no longer well defined on such a list.73 *74 *

Some list implementations have restrictions on the elements that75 * they may contain. For example, some implementations prohibit null elements,76 * and some have restrictions on the types of their elements. Attempting to77 * add an ineligible element throws an unchecked exception, typically78 * NullPointerException or ClassCastException. Attempting79 * to query the presence of an ineligible element may throw an exception,80 * or it may simply return false; some implementations will exhibit the former81 * behavior and some will exhibit the latter. More generally, attempting an82 * operation on an ineligible element whose completion would not result in83 * the insertion of an ineligible element into the list may throw an84 * exception or it may succeed, at the option of the implementation.85 * Such exceptions are marked as "optional" in the specification for this86 * interface.87 *88 *

This interface is a member of the89 * 90 * Java Collections Framework.91 *92 *@param the type of elements in this list93 *94 *@authorJosh Bloch95 *@authorNeal Gafter96 *@seeCollection97 *@seeSet98 *@seeArrayList99 *@seeLinkedList100 *@seeVector101 *@seeArrays#asList(Object[])102 *@seeCollections#nCopies(int, Object)103 *@seeCollections#EMPTY_LIST104 *@seeAbstractList105 *@seeAbstractSequentialList106 *@since1.2107 */

108

109 public interface List extends Collection{110 //Query Operations

111

112 /**

113 * Returns the number of elements in this list. If this list contains114 * more than Integer.MAX_VALUE elements, returns115 * Integer.MAX_VALUE.116 *117 *@returnthe number of elements in this list118 */

119 intsize();120

121 /**

122 * Returns true if this list contains no elements.123 *124 *@returntrue if this list contains no elements125 */

126 booleanisEmpty();127

128 /**

129 * Returns true if this list contains the specified element.130 * More formally, returns true if and only if this list contains131 * at least one element e such that132 * (o==null ? e==null : o.equals(e)).133 *134 *@paramo element whose presence in this list is to be tested135 *@returntrue if this list contains the specified element136 *@throwsClassCastException if the type of the specified element137 * is incompatible with this list138 * (optional)139 *@throwsNullPointerException if the specified element is null and this140 * list does not permit null elements141 * (optional)142 */

143 booleancontains(Object o);144

145 /**

146 * Returns an iterator over the elements in this list in proper sequence.147 *148 *@returnan iterator over the elements in this list in proper sequence149 */

150 Iteratoriterator();151

152 /**

153 * Returns an array containing all of the elements in this list in proper154 * sequence (from first to last element).155 *156 *

The returned array will be "safe" in that no references to it are157 * maintained by this list. (In other words, this method must158 * allocate a new array even if this list is backed by an array).159 * The caller is thus free to modify the returned array.160 *161 *

This method acts as bridge between array-based and collection-based162 * APIs.163 *164 *@returnan array containing all of the elements in this list in proper165 * sequence166 *@seeArrays#asList(Object[])167 */

168 Object[] toArray();169

170 /**

171 * Returns an array containing all of the elements in this list in172 * proper sequence (from first to last element); the runtime type of173 * the returned array is that of the specified array. If the list fits174 * in the specified array, it is returned therein. Otherwise, a new175 * array is allocated with the runtime type of the specified array and176 * the size of this list.177 *178 *

If the list fits in the specified array with room to spare (i.e.,179 * the array has more elements than the list), the element in the array180 * immediately following the end of the list is set to null.181 * (This is useful in determining the length of the list only if182 * the caller knows that the list does not contain any null elements.)183 *184 *

Like the {@link#toArray()} method, this method acts as bridge between185 * array-based and collection-based APIs. Further, this method allows186 * precise control over the runtime type of the output array, and may,187 * under certain circumstances, be used to save allocation costs.188 *189 *

Suppose x is a list known to contain only strings.190 * The following code can be used to dump the list into a newly191 * allocated array of String:192 *193 *

194 *     String[] y = x.toArray(new String[0]);

195 *196 * Note that toArray(new Object[0]) is identical in function to197 * toArray().198 *199 *@parama the array into which the elements of this list are to200 * be stored, if it is big enough; otherwise, a new array of the201 * same runtime type is allocated for this purpose.202 *@returnan array containing the elements of this list203 *@throwsArrayStoreException if the runtime type of the specified array204 * is not a supertype of the runtime type of every element in205 * this list206 *@throwsNullPointerException if the specified array is null207 */

208 T[] toArray(T[] a);209

210

211 //Modification Operations

212

213 /**

214 * Appends the specified element to the end of this list (optional215 * operation).216 *217 *

Lists that support this operation may place limitations on what218 * elements may be added to this list. In particular, some219 * lists will refuse to add null elements, and others will impose220 * restrictions on the type of elements that may be added. List221 * classes should clearly specify in their documentation any restrictions222 * on what elements may be added.223 *224 *@parame element to be appended to this list225 *@returntrue (as specified by {@linkCollection#add})226 *@throwsUnsupportedOperationException if the add operation227 * is not supported by this list228 *@throwsClassCastException if the class of the specified element229 * prevents it from being added to this list230 *@throwsNullPointerException if the specified element is null and this231 * list does not permit null elements232 *@throwsIllegalArgumentException if some property of this element233 * prevents it from being added to this list234 */

235 booleanadd(E e);236

237 /**

238 * Removes the first occurrence of the specified element from this list,239 * if it is present (optional operation). If this list does not contain240 * the element, it is unchanged. More formally, removes the element with241 * the lowest index i such that242 * (o==null ? get(i)==null : o.equals(get(i)))243 * (if such an element exists). Returns true if this list244 * contained the specified element (or equivalently, if this list changed245 * as a result of the call).246 *247 *@paramo element to be removed from this list, if present248 *@returntrue if this list contained the specified element249 *@throwsClassCastException if the type of the specified element250 * is incompatible with this list251 * (optional)252 *@throwsNullPointerException if the specified element is null and this253 * list does not permit null elements254 * (optional)255 *@throwsUnsupportedOperationException if the remove operation256 * is not supported by this list257 */

258 booleanremove(Object o);259

260

261 //Bulk Modification Operations

262

263 /**

264 * Returns true if this list contains all of the elements of the265 * specified collection.266 *267 *@paramc collection to be checked for containment in this list268 *@returntrue if this list contains all of the elements of the269 * specified collection270 *@throwsClassCastException if the types of one or more elements271 * in the specified collection are incompatible with this272 * list273 * (optional)274 *@throwsNullPointerException if the specified collection contains one275 * or more null elements and this list does not permit null276 * elements277 * (optional),278 * or if the specified collection is null279 *@see#contains(Object)280 */

281 boolean containsAll(Collection>c);282

283 /**

284 * Appends all of the elements in the specified collection to the end of285 * this list, in the order that they are returned by the specified286 * collection's iterator (optional operation). The behavior of this287 * operation is undefined if the specified collection is modified while288 * the operation is in progress. (Note that this will occur if the289 * specified collection is this list, and it's nonempty.)290 *291 *@paramc collection containing elements to be added to this list292 *@returntrue if this list changed as a result of the call293 *@throwsUnsupportedOperationException if the addAll operation294 * is not supported by this list295 *@throwsClassCastException if the class of an element of the specified296 * collection prevents it from being added to this list297 *@throwsNullPointerException if the specified collection contains one298 * or more null elements and this list does not permit null299 * elements, or if the specified collection is null300 *@throwsIllegalArgumentException if some property of an element of the301 * specified collection prevents it from being added to this list302 *@see#add(Object)303 */

304 boolean addAll(Collection extends E>c);305

306 /**

307 * Inserts all of the elements in the specified collection into this308 * list at the specified position (optional operation). Shifts the309 * element currently at that position (if any) and any subsequent310 * elements to the right (increases their indices). The new elements311 * will appear in this list in the order that they are returned by the312 * specified collection's iterator. The behavior of this operation is313 * undefined if the specified collection is modified while the314 * operation is in progress. (Note that this will occur if the specified315 * collection is this list, and it's nonempty.)316 *317 *@paramindex index at which to insert the first element from the318 * specified collection319 *@paramc collection containing elements to be added to this list320 *@returntrue if this list changed as a result of the call321 *@throwsUnsupportedOperationException if the addAll operation322 * is not supported by this list323 *@throwsClassCastException if the class of an element of the specified324 * collection prevents it from being added to this list325 *@throwsNullPointerException if the specified collection contains one326 * or more null elements and this list does not permit null327 * elements, or if the specified collection is null328 *@throwsIllegalArgumentException if some property of an element of the329 * specified collection prevents it from being added to this list330 *@throwsIndexOutOfBoundsException if the index is out of range331 * (index < 0 || index > size())332 */

333 boolean addAll(int index, Collection extends E>c);334

335 /**

336 * Removes from this list all of its elements that are contained in the337 * specified collection (optional operation).338 *339 *@paramc collection containing elements to be removed from this list340 *@returntrue if this list changed as a result of the call341 *@throwsUnsupportedOperationException if the removeAll operation342 * is not supported by this list343 *@throwsClassCastException if the class of an element of this list344 * is incompatible with the specified collection345 * (optional)346 *@throwsNullPointerException if this list contains a null element and the347 * specified collection does not permit null elements348 * (optional),349 * or if the specified collection is null350 *@see#remove(Object)351 *@see#contains(Object)352 */

353 boolean removeAll(Collection>c);354

355 /**

356 * Retains only the elements in this list that are contained in the357 * specified collection (optional operation). In other words, removes358 * from this list all of its elements that are not contained in the359 * specified collection.360 *361 *@paramc collection containing elements to be retained in this list362 *@returntrue if this list changed as a result of the call363 *@throwsUnsupportedOperationException if the retainAll operation364 * is not supported by this list365 *@throwsClassCastException if the class of an element of this list366 * is incompatible with the specified collection367 * (optional)368 *@throwsNullPointerException if this list contains a null element and the369 * specified collection does not permit null elements370 * (optional),371 * or if the specified collection is null372 *@see#remove(Object)373 *@see#contains(Object)374 */

375 boolean retainAll(Collection>c);376

377 /**

378 * Removes all of the elements from this list (optional operation).379 * The list will be empty after this call returns.380 *381 *@throwsUnsupportedOperationException if the clear operation382 * is not supported by this list383 */

384 voidclear();385

386

387 //Comparison and hashing

388

389 /**

390 * Compares the specified object with this list for equality. Returns391 * true if and only if the specified object is also a list, both392 * lists have the same size, and all corresponding pairs of elements in393 * the two lists are equal. (Two elements e1 and394 * e2 are equal if (e1==null ? e2==null :395 * e1.equals(e2)).) In other words, two lists are defined to be396 * equal if they contain the same elements in the same order. This397 * definition ensures that the equals method works properly across398 * different implementations of the List interface.399 *400 *@paramo the object to be compared for equality with this list401 *@returntrue if the specified object is equal to this list402 */

403 booleanequals(Object o);404

405 /**

406 * Returns the hash code value for this list. The hash code of a list407 * is defined to be the result of the following calculation:408 *

409 *  int hashCode = 1;410 *  for (E e : list)411 *      hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());412 * 

413 * This ensures that list1.equals(list2) implies that414 * list1.hashCode()==list2.hashCode() for any two lists,415 * list1 and list2, as required by the general416 * contract of {@linkObject#hashCode}.417 *418 *@returnthe hash code value for this list419 *@seeObject#equals(Object)420 *@see#equals(Object)421 */

422 inthashCode();423

424

425 //Positional Access Operations

426

427 /**

428 * Returns the element at the specified position in this list.429 *430 *@paramindex index of the element to return431 *@returnthe element at the specified position in this list432 *@throwsIndexOutOfBoundsException if the index is out of range433 * (index < 0 || index >= size())434 */

435 E get(intindex);436

437 /**

438 * Replaces the element at the specified position in this list with the439 * specified element (optional operation).440 *441 *@paramindex index of the element to replace442 *@paramelement element to be stored at the specified position443 *@returnthe element previously at the specified position444 *@throwsUnsupportedOperationException if the set operation445 * is not supported by this list446 *@throwsClassCastException if the class of the specified element447 * prevents it from being added to this list448 *@throwsNullPointerException if the specified element is null and449 * this list does not permit null elements450 *@throwsIllegalArgumentException if some property of the specified451 * element prevents it from being added to this list452 *@throwsIndexOutOfBoundsException if the index is out of range453 * (index < 0 || index >= size())454 */

455 E set(intindex, E element);456

457 /**

458 * Inserts the specified element at the specified position in this list459 * (optional operation). Shifts the element currently at that position460 * (if any) and any subsequent elements to the right (adds one to their461 * indices).462 *463 *@paramindex index at which the specified element is to be inserted464 *@paramelement element to be inserted465 *@throwsUnsupportedOperationException if the add operation466 * is not supported by this list467 *@throwsClassCastException if the class of the specified element468 * prevents it from being added to this list469 *@throwsNullPointerException if the specified element is null and470 * this list does not permit null elements471 *@throwsIllegalArgumentException if some property of the specified472 * element prevents it from being added to this list473 *@throwsIndexOutOfBoundsException if the index is out of range474 * (index < 0 || index > size())475 */

476 void add(intindex, E element);477

478 /**

479 * Removes the element at the specified position in this list (optional480 * operation). Shifts any subsequent elements to the left (subtracts one481 * from their indices). Returns the element that was removed from the482 * list.483 *484 *@paramindex the index of the element to be removed485 *@returnthe element previously at the specified position486 *@throwsUnsupportedOperationException if the remove operation487 * is not supported by this list488 *@throwsIndexOutOfBoundsException if the index is out of range489 * (index < 0 || index >= size())490 */

491 E remove(intindex);492

493

494 //Search Operations

495

496 /**

497 * Returns the index of the first occurrence of the specified element498 * in this list, or -1 if this list does not contain the element.499 * More formally, returns the lowest index i such that500 * (o==null ? get(i)==null : o.equals(get(i))),501 * or -1 if there is no such index.502 *503 *@paramo element to search for504 *@returnthe index of the first occurrence of the specified element in505 * this list, or -1 if this list does not contain the element506 *@throwsClassCastException if the type of the specified element507 * is incompatible with this list508 * (optional)509 *@throwsNullPointerException if the specified element is null and this510 * list does not permit null elements511 * (optional)512 */

513 intindexOf(Object o);514

515 /**

516 * Returns the index of the last occurrence of the specified element517 * in this list, or -1 if this list does not contain the element.518 * More formally, returns the highest index i such that519 * (o==null ? get(i)==null : o.equals(get(i))),520 * or -1 if there is no such index.521 *522 *@paramo element to search for523 *@returnthe index of the last occurrence of the specified element in524 * this list, or -1 if this list does not contain the element525 *@throwsClassCastException if the type of the specified element526 * is incompatible with this list527 * (optional)528 *@throwsNullPointerException if the specified element is null and this529 * list does not permit null elements530 * (optional)531 */

532 intlastIndexOf(Object o);533

534

535 //List Iterators

536

537 /**

538 * Returns a list iterator over the elements in this list (in proper539 * sequence).540 *541 *@returna list iterator over the elements in this list (in proper542 * sequence)543 */

544 ListIteratorlistIterator();545

546 /**

547 * Returns a list iterator over the elements in this list (in proper548 * sequence), starting at the specified position in the list.549 * The specified index indicates the first element that would be550 * returned by an initial call to {@linkListIterator#next next}.551 * An initial call to {@linkListIterator#previous previous} would552 * return the element with the specified index minus one.553 *554 *@paramindex index of the first element to be returned from the555 * list iterator (by a call to {@linkListIterator#next next})556 *@returna list iterator over the elements in this list (in proper557 * sequence), starting at the specified position in the list558 *@throwsIndexOutOfBoundsException if the index is out of range559 * ({@codeindex < 0 || index > size()})560 */

561 ListIterator listIterator(intindex);562

563 //View

564

565 /**

566 * Returns a view of the portion of this list between the specified567 * fromIndex, inclusive, and toIndex, exclusive. (If568 * fromIndex and toIndex are equal, the returned list is569 * empty.) The returned list is backed by this list, so non-structural570 * changes in the returned list are reflected in this list, and vice-versa.571 * The returned list supports all of the optional list operations supported572 * by this list.

573 *574 * This method eliminates the need for explicit range operations (of575 * the sort that commonly exist for arrays). Any operation that expects576 * a list can be used as a range operation by passing a subList view577 * instead of a whole list. For example, the following idiom578 * removes a range of elements from a list:579 *

580 *      list.subList(from, to).clear();581 * 

582 * Similar idioms may be constructed for indexOf and583 * lastIndexOf, and all of the algorithms in the584 * Collections class can be applied to a subList.

585 *586 * The semantics of the list returned by this method become undefined if587 * the backing list (i.e., this list) is structurally modified in588 * any way other than via the returned list. (Structural modifications are589 * those that change the size of this list, or otherwise perturb it in such590 * a fashion that iterations in progress may yield incorrect results.)591 *592 *@paramfromIndex low endpoint (inclusive) of the subList593 *@paramtoIndex high endpoint (exclusive) of the subList594 *@returna view of the specified range within this list595 *@throwsIndexOutOfBoundsException for an illegal endpoint index value596 * (fromIndex < 0 || toIndex > size ||597 * fromIndex > toIndex)598 */

599 List subList(int fromIndex, inttoIndex);600 }