The collection interfaces have exception specifications like

     * @throws UnsupportedOperationException <tt>add</tt> is not supported by
     * this collection.
     * @throws ClassCastException class of the specified element prevents it
     * from being added to this collection.
     * @throws NullPointerException if the specified element is null and this
     * collection does not support null elements.
     * @throws IllegalArgumentException some aspect of this element prevents
     * it from being added to this collection.
     */
    boolean add(E o);

When this method is doc'ed in extending/implementing classes/interfaces,
a different set of exceptions must be spec'ed. Often IllegalArgumentException
is never thrown, and often NullPointerException is a mandatory exception
because null elements are never permitted.

All such methods in all the collection classes must be carefully audited for
correctness of all unchecked exceptions.

javadoc by default does not inherit unchecked exception specifications,
so a reader might assume from reading the specs that e.g. NullPointerException
is never thrown.
###@###.### 2005-05-12 22:40:45 GMT