stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8031142: AbstractCollection and AbstractList should specify their default implementation using @implSpec

Browse Source 
Reviewed-by: martin, psandoz
This commit is contained in:
Chris Hegarty 2014-01-07 12:59:32 +00:00
parent 9a9add8825
commit f27b377f0e
2 changed files with 52 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
jdk/src/share/classes/java/util/AbstractCollection.java
View File

@ -80,7 +80,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns <tt>size() == 0</tt>. * @implSpec
* This implementation returns <tt>size() == 0</tt>.
*/ */
public boolean isEmpty() { public boolean isEmpty() {
return size() == 0; return size() == 0;
@ -89,7 +90,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over the elements in the collection, * @implSpec
* This implementation iterates over the elements in the collection,
* checking each element in turn for equality with the specified element. * checking each element in turn for equality with the specified element.
* *
* @throws ClassCastException {@inheritDoc} * @throws ClassCastException {@inheritDoc}
@ -112,7 +114,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns an array containing all the elements * @implSpec
* This implementation returns an array containing all the elements
* returned by this collection's iterator, in the same order, stored in * returned by this collection's iterator, in the same order, stored in
* consecutive elements of the array, starting with index {@code 0}. * consecutive elements of the array, starting with index {@code 0}.
* The length of the returned array is equal to the number of elements * The length of the returned array is equal to the number of elements
@ -146,7 +149,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns an array containing all the elements * @implSpec
* This implementation returns an array containing all the elements
* returned by this collection's iterator in the same order, stored in * returned by this collection's iterator in the same order, stored in
* consecutive elements of the array, starting with index {@code 0}. * consecutive elements of the array, starting with index {@code 0}.
* If the number of elements returned by the iterator is too large to * If the number of elements returned by the iterator is too large to
@ -249,7 +253,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation always throws an * @implSpec
* This implementation always throws an
* <tt>UnsupportedOperationException</tt>. * <tt>UnsupportedOperationException</tt>.
* *
* @throws UnsupportedOperationException {@inheritDoc} * @throws UnsupportedOperationException {@inheritDoc}
@ -265,7 +270,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over the collection looking for the * @implSpec
* This implementation iterates over the collection looking for the
* specified element. If it finds the element, it removes the element * specified element. If it finds the element, it removes the element
* from the collection using the iterator's remove method. * from the collection using the iterator's remove method.
* *
@ -304,7 +310,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over the specified collection, * @implSpec
* This implementation iterates over the specified collection,
* checking each element returned by the iterator in turn to see * checking each element returned by the iterator in turn to see
* if it's contained in this collection. If all elements are so * if it's contained in this collection. If all elements are so
* contained <tt>true</tt> is returned, otherwise <tt>false</tt>. * contained <tt>true</tt> is returned, otherwise <tt>false</tt>.
@ -323,7 +330,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over the specified collection, and adds * @implSpec
* This implementation iterates over the specified collection, and adds
* each object returned by the iterator to this collection, in turn. * each object returned by the iterator to this collection, in turn.
* *
* <p>Note that this implementation will throw an * <p>Note that this implementation will throw an
@ -349,7 +357,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over this collection, checking each * @implSpec
* This implementation iterates over this collection, checking each
* element returned by the iterator in turn to see if it's contained * element returned by the iterator in turn to see if it's contained
* in the specified collection. If it's so contained, it's removed from * in the specified collection. If it's so contained, it's removed from
* this collection with the iterator's <tt>remove</tt> method. * this collection with the iterator's <tt>remove</tt> method.
@ -383,7 +392,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over this collection, checking each * @implSpec
* This implementation iterates over this collection, checking each
* element returned by the iterator in turn to see if it's contained * element returned by the iterator in turn to see if it's contained
* in the specified collection. If it's not so contained, it's removed * in the specified collection. If it's not so contained, it's removed
* from this collection with the iterator's <tt>remove</tt> method. * from this collection with the iterator's <tt>remove</tt> method.
@ -417,7 +427,8 @@ public abstract class AbstractCollection<E> implements Collection<E> {
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation iterates over this collection, removing each * @implSpec
* This implementation iterates over this collection, removing each
* element using the <tt>Iterator.remove</tt> operation. Most * element using the <tt>Iterator.remove</tt> operation. Most
* implementations will probably choose to override this method for * implementations will probably choose to override this method for
* efficiency. * efficiency.

45
jdk/src/share/classes/java/util/AbstractList.java
View File

@ -87,7 +87,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
* classes should clearly specify in their documentation any restrictions * classes should clearly specify in their documentation any restrictions
* on what elements may be added. * on what elements may be added.
* *
* <p>This implementation calls {@code add(size(), e)}. * @implSpec
* This implementation calls {@code add(size(), e)}.
* *
* <p>Note that this implementation throws an * <p>Note that this implementation throws an
* {@code UnsupportedOperationException} unless * {@code UnsupportedOperationException} unless
@ -119,7 +120,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation always throws an * @implSpec
* This implementation always throws an
* {@code UnsupportedOperationException}. * {@code UnsupportedOperationException}.
* *
* @throws UnsupportedOperationException {@inheritDoc} * @throws UnsupportedOperationException {@inheritDoc}
@ -135,7 +137,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation always throws an * @implSpec
* This implementation always throws an
* {@code UnsupportedOperationException}. * {@code UnsupportedOperationException}.
* *
* @throws UnsupportedOperationException {@inheritDoc} * @throws UnsupportedOperationException {@inheritDoc}
@ -151,7 +154,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation always throws an * @implSpec
* This implementation always throws an
* {@code UnsupportedOperationException}. * {@code UnsupportedOperationException}.
* *
* @throws UnsupportedOperationException {@inheritDoc} * @throws UnsupportedOperationException {@inheritDoc}
@ -167,7 +171,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation first gets a list iterator (with * @implSpec
* This implementation first gets a list iterator (with
* {@code 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. * specified element is found or the end of the list is reached.
* *
@ -191,7 +196,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation first gets a list iterator that points to the end * @implSpec
* This implementation first gets a list iterator that points to the end
* of the list (with {@code 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 * backwards over the list until the specified element is found, or the
* beginning of the list is reached. * beginning of the list is reached.
@ -220,7 +226,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
* Removes all of the elements from this list (optional operation). * Removes all of the elements from this list (optional operation).
* The list will be empty after this call returns. * The list will be empty after this call returns.
* *
* <p>This implementation calls {@code removeRange(0, size())}. * @implSpec
* This implementation calls {@code removeRange(0, size())}.
* *
* <p>Note that this implementation throws an * <p>Note that this implementation throws an
* {@code UnsupportedOperationException} unless {@code remove(int * {@code UnsupportedOperationException} unless {@code remove(int
@ -237,7 +244,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation gets an iterator over the specified collection * @implSpec
* This implementation gets an iterator over the specified collection
* and iterates over it, inserting the elements obtained from the * and iterates over it, inserting the elements obtained from the
* iterator into this list at the appropriate position, one at a time, * iterator into this list at the appropriate position, one at a time,
* using {@code add(int, E)}. * using {@code add(int, E)}.
@ -269,7 +277,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* Returns an iterator over the elements in this list in proper sequence. * Returns an iterator over the elements in this list in proper sequence.
* *
* <p>This implementation returns a straightforward implementation of the * @implSpec
* This implementation returns a straightforward implementation of the
* iterator interface, relying on the backing list's {@code size()}, * iterator interface, relying on the backing list's {@code size()},
* {@code get(int)}, and {@code remove(int)} methods. * {@code get(int)}, and {@code remove(int)} methods.
* *
@ -291,7 +300,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns {@code listIterator(0)}. * @implSpec
* This implementation returns {@code listIterator(0)}.
* *
* @see #listIterator(int) * @see #listIterator(int)
*/ */
@ -302,7 +312,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns a straightforward implementation of the * @implSpec
* This implementation returns a straightforward implementation of the
* {@code ListIterator} interface that extends the implementation of the * {@code ListIterator} interface that extends the implementation of the
* {@code Iterator} interface returned by the {@code iterator()} method. * {@code Iterator} interface returned by the {@code iterator()} method.
* The {@code ListIterator} implementation relies on the backing list's * The {@code ListIterator} implementation relies on the backing list's
@ -448,7 +459,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* {@inheritDoc} * {@inheritDoc}
* *
* <p>This implementation returns a list that subclasses * @implSpec
* This implementation returns a list that subclasses
* {@code 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 * offset of the subList within the backing list, the size of the subList
* (which can change over its lifetime), and the expected * (which can change over its lifetime), and the expected
@ -495,8 +507,9 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
* the two lists are <i>equal</i>. (Two elements {@code e1} and * the two lists are <i>equal</i>. (Two elements {@code e1} and
* {@code e2} are <i>equal</i> if {@code (e1==null ? e2==null : * {@code e2} are <i>equal</i> if {@code (e1==null ? e2==null :
* e1.equals(e2))}.) In other words, two lists are defined to be * e1.equals(e2))}.) In other words, two lists are defined to be
* equal if they contain the same elements in the same order.<p> * equal if they contain the same elements in the same order.
* *
* @implSpec
* This implementation first checks if the specified object is this * This implementation first checks if the specified object is this
* list. If so, it returns {@code true}; if not, it checks if the * 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, * specified object is a list. If not, it returns {@code false}; if so,
@ -529,7 +542,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
/** /**
* Returns the hash code value for this list. * Returns the hash code value for this list.
* *
* <p>This implementation uses exactly the code that is used to define the * @implSpec
* This implementation uses exactly the code that is used to define the
* list hash function in the documentation for the {@link List#hashCode} * list hash function in the documentation for the {@link List#hashCode}
* method. * method.
* *
@ -555,7 +569,8 @@ public abstract class AbstractList<E> extends AbstractCollection<E> implements L
* improve the performance of the {@code clear} operation on this list * improve the performance of the {@code clear} operation on this list
* and its subLists. * and its subLists.
* *
* <p>This implementation gets a list iterator positioned before * @implSpec
* This implementation gets a list iterator positioned before
* {@code fromIndex}, and repeatedly calls {@code ListIterator.next} * {@code fromIndex}, and repeatedly calls {@code ListIterator.next}
* followed by {@code ListIterator.remove} until the entire range has * followed by {@code ListIterator.remove} until the entire range has
* been removed. <b>Note: if {@code ListIterator.remove} requires linear * been removed. <b>Note: if {@code ListIterator.remove} requires linear