--- jsr166/src/main/java/util/AbstractList.java 2006/05/28 23:36:29 1.11 +++ jsr166/src/main/java/util/AbstractList.java 2006/06/26 00:46:50 1.12 @@ -8,37 +8,37 @@ package java.util; /** - * This class provides a skeletal implementation of the List + * This class provides a skeletal implementation of the {@code List} * interface to minimize the effort required to implement this interface * backed by a "random access" data store (such as an array). For sequential - * access data (such as a linked list), AbstractSequentialList should - * be used in preference to this class.

+ * access data (such as a linked list), {@code AbstractSequentialList} should + * be used in preference to this class. * - * To implement an unmodifiable list, the programmer needs only to extend this - * class and provide implementations for the get(int index) and - * size() methods.

+ *

To implement an unmodifiable list, the programmer needs only to extend this + * class and provide implementations for the {@code get(int index)} and + * {@code size()} methods. * - * To implement a modifiable list, the programmer must additionally override - * the set(int index, Object element) method (which otherwise throws - * an UnsupportedOperationException. If the list is variable-size - * the programmer must additionally override the add(int index, Object - * element) and remove(int index) methods.

+ *

To implement a modifiable list, the programmer must additionally override + * the {@code set(int index, Object element)} method (which otherwise throws + * an {@code UnsupportedOperationException}. If the list is variable-size + * the programmer must additionally override the {@code add(int index, Object + * element)} and {@code remove(int index)} methods. * - * The programmer should generally provide a void (no argument) and collection - * constructor, as per the recommendation in the Collection interface - * specification.

+ *

The programmer should generally provide a void (no argument) and collection + * constructor, as per the recommendation in the {@code Collection} interface + * specification. * - * Unlike the other abstract collection implementations, the programmer does + *

Unlike the other abstract collection implementations, the programmer does * not have to provide an iterator implementation; the iterator and * list iterator are implemented by this class, on top of the "random access" - * methods: get(int index), set(int index, E element), - * add(int index, E element) and remove(int index).

+ * methods: {@code get(int index)}, {@code set(int index, E element)}, + * {@code add(int index, E element)} and {@code remove(int index)}. * - * The documentation for each non-abstract methods in this class describes its + *

The documentation for each non-abstract methods in this class describes its * implementation in detail. Each of these methods may be overridden if the - * collection being implemented admits a more efficient implementation.

+ * collection being implemented admits a more efficient implementation. * - * This class is a member of the + *

This class is a member of the * * Java Collections Framework. * @@ -71,15 +71,15 @@ public abstract class AbstractList ex * classes should clearly specify in their documentation any restrictions * on what elements may be added. * - *

This implementation calls add(size(), e). + *

This implementation calls {@code add(size(), e)}. * *

Note that this implementation throws an - * UnsupportedOperationException unless add(int, Object) + * {@code UnsupportedOperationException} unless {@code add(int, Object)} * is overridden. * * @param e element to be appended to this list - * @return true (as specified by {@link Collection#add}) - * @throws UnsupportedOperationException if the add operation + * @return {@code true} (as specified by {@link Collection#add}) + * @throws UnsupportedOperationException if the {@code add} operation * is not supported by this list * @throws ClassCastException if the class of the specified element * prevents it from being added to this list @@ -104,7 +104,7 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation always throws an - * UnsupportedOperationException. + * {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException {@inheritDoc} * @throws ClassCastException {@inheritDoc} @@ -120,7 +120,7 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation always throws an - * UnsupportedOperationException. + * {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException {@inheritDoc} * @throws ClassCastException {@inheritDoc} @@ -136,7 +136,7 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation always throws an - * UnsupportedOperationException. + * {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException {@inheritDoc} * @throws IndexOutOfBoundsException {@inheritDoc} @@ -152,7 +152,7 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation first gets a list iterator (with - * listIterator()). Then, it iterates over the list until the + * {@code listIterator()}). Then, it iterates over the list until the * specified element is found or the end of the list is reached. * * @throws ClassCastException {@inheritDoc} @@ -176,7 +176,7 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation first gets a list iterator that points to the end - * of the list (with listIterator(size())). Then, it iterates + * of the list (with {@code listIterator(size())}). Then, it iterates * backwards over the list until the specified element is found, or the * beginning of the list is reached. * @@ -204,14 +204,14 @@ public abstract class AbstractList ex * Removes all of the elements from this list (optional operation). * The list will be empty after this call returns. * - *

This implementation calls removeRange(0, size()). + *

This implementation calls {@code removeRange(0, size())}. * *

Note that this implementation throws an - * UnsupportedOperationException unless remove(int - * index) or removeRange(int fromIndex, int toIndex) is + * {@code UnsupportedOperationException} unless {@code remove(int + * index)} or {@code removeRange(int fromIndex, int toIndex)} is * overridden. * - * @throws UnsupportedOperationException if the clear operation + * @throws UnsupportedOperationException if the {@code clear} operation * is not supported by this list */ public void clear() { @@ -224,11 +224,11 @@ public abstract class AbstractList ex *

This implementation gets an iterator over the specified collection and * iterates over it, inserting the elements obtained from the iterator * into this list at the appropriate position, one at a time, using - * add(int, Object). Many implementations will override this + * {@code add(int, Object)}. Many implementations will override this * method for efficiency. * *

Note that this implementation throws an - * UnsupportedOperationException unless add(int, Object) + * {@code UnsupportedOperationException} unless {@code add(int, Object)} * is overridden. * * @throws UnsupportedOperationException {@inheritDoc} @@ -255,17 +255,17 @@ public abstract class AbstractList ex * sequence.

* * This implementation returns a straightforward implementation of the - * iterator interface, relying on the backing list's size(), - * get(int), and remove(int) methods.

+ * iterator interface, relying on the backing list's {@code size()}, + * {@code get(int)}, and {@code remove(int)} methods.

* * Note that the iterator returned by this method will throw an - * UnsupportedOperationException in response to its - * remove method unless the list's remove(int) method is + * {@code UnsupportedOperationException} in response to its + * {@code remove} method unless the list's {@code remove(int)} method is * overridden.

* * This implementation can be made to throw runtime exceptions in the face * of concurrent modification, as described in the specification for the - * (protected) modCount field. + * (protected) {@code modCount} field. * * @return an iterator over the elements in this list in proper sequence * @@ -278,7 +278,7 @@ public abstract class AbstractList ex /** * {@inheritDoc} * - *

This implementation returns listIterator(0). + *

This implementation returns {@code listIterator(0)}. * * @see #listIterator(int) */ @@ -290,21 +290,21 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation returns a straightforward implementation of the - * ListIterator interface that extends the implementation of the - * Iterator interface returned by the iterator() method. - * The ListIterator implementation relies on the backing list's - * get(int), set(int, Object), add(int, Object) - * and remove(int) methods. + * {@code ListIterator} interface that extends the implementation of the + * {@code Iterator} interface returned by the {@code iterator()} method. + * The {@code ListIterator} implementation relies on the backing list's + * {@code get(int)}, {@code set(int, Object)}, {@code add(int, Object)} + * and {@code remove(int)} methods. * *

Note that the list iterator returned by this implementation will - * throw an UnsupportedOperationException in response to its - * remove, set and add methods unless the - * list's remove(int), set(int, Object), and - * add(int, Object) methods are overridden. + * throw an {@code UnsupportedOperationException} in response to its + * {@code remove}, {@code set} and {@code add} methods unless the + * list's {@code remove(int)}, {@code set(int, Object)}, and + * {@code add(int, Object)} methods are overridden. * *

This implementation can be made to throw runtime exceptions in the * face of concurrent modification, as described in the specification for - * the (protected) modCount field. + * the (protected) {@code modCount} field. * * @throws IndexOutOfBoundsException {@inheritDoc} * @@ -437,36 +437,36 @@ public abstract class AbstractList ex * {@inheritDoc} * *

This implementation returns a list that subclasses - * AbstractList. The subclass stores, in private fields, the + * {@code AbstractList}. The subclass stores, in private fields, the * offset of the subList within the backing list, the size of the subList * (which can change over its lifetime), and the expected - * modCount value of the backing list. There are two variants - * of the subclass, one of which implements RandomAccess. - * If this list implements RandomAccess the returned list will - * be an instance of the subclass that implements RandomAccess. - * - *

The subclass's set(int, Object), get(int), - * add(int, Object), remove(int), addAll(int, - * Collection) and removeRange(int, int) methods all + * {@code modCount} value of the backing list. There are two variants + * of the subclass, one of which implements {@code RandomAccess}. + * If this list implements {@code RandomAccess} the returned list will + * be an instance of the subclass that implements {@code RandomAccess}. + * + *

The subclass's {@code set(int, Object)}, {@code get(int)}, + * {@code add(int, Object)}, {@code remove(int)}, {@code addAll(int, + * Collection)} and {@code removeRange(int, int)} methods all * delegate to the corresponding methods on the backing abstract list, * after bounds-checking the index and adjusting for the offset. The - * addAll(Collection c) method merely returns addAll(size, - * c). + * {@code addAll(Collection c)} method merely returns {@code addAll(size, + * c)}. * - *

The listIterator(int) method returns a "wrapper object" + *

The {@code listIterator(int)} method returns a "wrapper object" * over a list iterator on the backing list, which is created with the - * corresponding method on the backing list. The iterator method - * merely returns listIterator(), and the size method - * merely returns the subclass's size field. + * corresponding method on the backing list. The {@code iterator} method + * merely returns {@code listIterator()}, and the {@code size} method + * merely returns the subclass's {@code size} field. * - *

All methods first check to see if the actual modCount of + *

All methods first check to see if the actual {@code modCount} of * the backing list is equal to its expected value, and throw a - * ConcurrentModificationException if it is not. + * {@code ConcurrentModificationException} if it is not. * * @throws IndexOutOfBoundsException endpoint index value out of range - * (fromIndex < 0 || toIndex > size) + * {@code (fromIndex < 0 || toIndex > size)} * @throws IllegalArgumentException if the endpoint indices are out of order - * (fromIndex > toIndex) + * {@code (fromIndex > toIndex)} */ public List subList(int fromIndex, int toIndex) { return (this instanceof RandomAccess ? @@ -478,24 +478,24 @@ public abstract class AbstractList ex /** * Compares the specified object with this list for equality. Returns - * true if and only if the specified object is also a list, both + * {@code true} if and only if the specified object is also a list, both * lists have the same size, and all corresponding pairs of elements in - * the two lists are equal. (Two elements e1 and - * e2 are equal if (e1==null ? e2==null : - * e1.equals(e2)).) In other words, two lists are defined to be + * the two lists are equal. (Two elements {@code e1} and + * {@code e2} are equal if {@code (e1==null ? e2==null : + * e1.equals(e2))}.) In other words, two lists are defined to be * equal if they contain the same elements in the same order.

* * This implementation first checks if the specified object is this - * list. If so, it returns true; if not, it checks if the - * specified object is a list. If not, it returns false; if so, + * list. If so, it returns {@code true}; if not, it checks if the + * specified object is a list. If not, it returns {@code false}; if so, * it iterates over both lists, comparing corresponding pairs of elements. - * If any comparison returns false, this method returns - * false. If either iterator runs out of elements before the - * other it returns false (as the lists are of unequal length); - * otherwise it returns true when the iterations complete. + * If any comparison returns {@code false}, this method returns + * {@code false}. If either iterator runs out of elements before the + * other it returns {@code false} (as the lists are of unequal length); + * otherwise it returns {@code true} when the iterations complete. * * @param o the object to be compared for equality with this list - * @return true if the specified object is equal to this list + * @return {@code true} if the specified object is equal to this list */ public boolean equals(Object o) { if (o == this) @@ -535,22 +535,22 @@ public abstract class AbstractList ex /** * Removes from this list all of the elements whose index is between - * fromIndex, inclusive, and toIndex, exclusive. + * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. * Shifts any succeeding elements to the left (reduces their index). - * This call shortens the ArrayList by (toIndex - fromIndex) - * elements. (If toIndex==fromIndex, this operation has no + * This call shortens the ArrayList by {@code (toIndex - fromIndex)} + * elements. (If {@code toIndex==fromIndex}, this operation has no * effect.)

* - * This method is called by the clear operation on this list + * This method is called by the {@code clear} operation on this list * and its subLists. Overriding this method to take advantage of * the internals of the list implementation can substantially - * improve the performance of the clear operation on this list + * improve the performance of the {@code clear} operation on this list * and its subLists.

* * This implementation gets a list iterator positioned before - * fromIndex, and repeatedly calls ListIterator.next - * followed by ListIterator.remove until the entire range has - * been removed. Note: if ListIterator.remove requires linear + * {@code fromIndex}, and repeatedly calls {@code ListIterator.next} + * followed by {@code ListIterator.remove} until the entire range has + * been removed. Note: if {@code ListIterator.remove} requires linear * time, this implementation requires quadratic time. * * @param fromIndex index of first element to be removed @@ -571,22 +571,22 @@ public abstract class AbstractList ex * progress may yield incorrect results.

* * This field is used by the iterator and list iterator implementation - * returned by the iterator and listIterator methods. + * returned by the {@code iterator} and {@code listIterator} methods. * If the value of this field changes unexpectedly, the iterator (or list - * iterator) will throw a ConcurrentModificationException in - * response to the next, remove, previous, - * set or add operations. This provides + * iterator) will throw a {@code ConcurrentModificationException} in + * response to the {@code next}, {@code remove}, {@code previous}, + * {@code set} or {@code add} operations. This provides * fail-fast behavior, rather than non-deterministic behavior in * the face of concurrent modification during iteration.

* * Use of this field by subclasses is optional. If a subclass * wishes to provide fail-fast iterators (and list iterators), then it - * merely has to increment this field in its add(int, Object) and - * remove(int) methods (and any other methods that it overrides + * merely has to increment this field in its {@code add(int, Object)} and + * {@code remove(int)} methods (and any other methods that it overrides * that result in structural modifications to the list). A single call to - * add(int, Object) or remove(int) must add no more than + * {@code add(int, Object)} or {@code remove(int)} must add no more than * one to this field, or the iterators (and list iterators) will throw - * bogus ConcurrentModificationExceptions. If an implementation + * bogus {@code ConcurrentModificationExceptions}. If an implementation * does not wish to provide fail-fast iterators, this field may be * ignored. */