The root interface in the
collection hierarchy. A collection represents a group of objects, known as its
elements. Some collections allow duplicate elements and others do not. Some are ordered and others unordered. The JDK does not provide any
direct implementations of this interface: it provides implementations of more specific subinterfaces like
Set and
List. This interface is typically used to pass collections around and manipulate them where maximum generality is desired.
Bags or multisets (unordered collections that may contain duplicate elements) should implement this interface directly.
All general-purpose Collection implementation classes (which typically implement Collection indirectly through one of its subinterfaces) should provide two "standard" constructors: a void (no arguments) constructor, which creates an empty collection, and a constructor with a single argument of type Collection, which creates a new collection with the same elements as its argument. In effect, the latter constructor allows the user to copy any collection, producing an equivalent collection of the desired implementation type. There is no way to enforce this convention (as interfaces cannot contain constructors) but all of the general-purpose Collection implementations in the Java platform libraries comply.
The "destructive" methods contained in this interface, that is, the methods that modify the collection on which they operate, are specified to throw UnsupportedOperationException if this collection does not support the operation. If this is the case, these methods may, but are not required to, throw an UnsupportedOperationException if the invocation would have no effect on the collection. For example, invoking the {@link #addAll(Collection)} method on an unmodifiable collection may,but is not required to, throw the exception if the collection to be added is empty.
Some collection implementations have restrictions on the elements that they may contain. For example, some implementations prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or ClassCastException. Attempting to query the presence of an ineligible element may throw an exception, or it may simply return false; some implementations will exhibit the former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible element whose completion would not result in the insertion of an ineligible element into the collection may throw an exception or it may succeed, at the option of the implementation. Such exceptions are marked as "optional" in the specification for this interface.
It is up to each collection to determine its own synchronization policy. In the absence of a stronger guarantee by the implementation, undefined behavior may result from the invocation of any method on a collection that is being mutated by another thread; this includes direct invocations, passing the collection to a method that might perform invocations, and using an existing iterator to examine the collection.
Many methods in Collections Framework interfaces are defined in terms of the {@link Object#equals(Object) equals} method. For example,the specification for the {@link #contains(Object) contains(Object o)}method says: "returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e))." This specification should not be construed to imply that invoking Collection.contains with a non-null argument o will cause o.equals(e) to be invoked for any element e. Implementations are free to implement optimizations whereby the equals invocation is avoided, for example, by first comparing the hash codes of the two elements. (The {@link Object#hashCode()} specification guarantees that two objects withunequal hash codes cannot be equal.) More generally, implementations of the various Collections Framework interfaces are free to take advantage of the specified behavior of underlying {@link Object} methods wherever theimplementor deems it appropriate.
This interface is a member of the Java Collections Framework.
@author Josh Bloch
@author Neal Gafter
@version 1.55, 04/21/06
@see Set
@see List
@see Map
@see SortedSet
@see SortedMap
@see HashSet
@see TreeSet
@see ArrayList
@see LinkedList
@see Vector
@see Collections
@see Arrays
@see AbstractCollection
@since 1.2