Java Reference
In-Depth Information
provided classes do not fill. Finally, we cover the "legacy collections" in
java.util
that predate the overall collection system, but which you will
find in some existing code. One of these legacy collection types
Proper-
ties
continues in common use.
For simplicity, we usually refer to the various interfaces without men-
tioning their type parametersfor example,
Iterator
or
Collection
except
where it is necessary to show that the same type parameter is being
usedfor example, that
iterator
has a return type
Iterator<E>
for a
Col-
lection<E>
.
21.1.1. Exception Conventions
A few conventions related to exceptions are used throughout the collec-
tions classes and interfaces, and we do not wish to document them for
every constructor and method where they may occur:
•
Methods that are optional in an implementation of an interface
throw
UnsupportedOperationException
when not implemented. We
indicate which methods are optional as we go throughusing "(Op-
tional)" at the end of the method description.
•
Methods or constructors that accept elements (either individually
or as part of other collections) to be added to the current collec-
tion can throw
ClassCastException
if the element is not of an ap-
propriate type for the collection, or for sorted collections, if the
element cannot be compared with other elements. Methods that
check for the existence of elements or try to remove them may
also throw
ClassCastException
.
•
Methods or constructors that accept elements (either individually
or as part of other collections) to be added to the current collec-
tion throw
IllegalArgumentException
if the element's value is not
appropriate for the collectionfor example, some collections, such
as subsets, define restricted ranges on the values of elements al-
lowed in the collection.
