[all packages]
[package java.util]
[class hierarchy]
[index]
java.lang.Object | +----java.util.Collection<A>
public interface Collection<A>
The interfaces that comprise the collection hierarchy are designed to allow manipulation of collections in an implementation-independent fashion. This allows for interoperability among unrelated APIs that take collections as input or return them as output. It reduces the effort in learning new APIs that would otherwise have their own collection interfaces, reduces the effort in designing such APIs, and fosters software reuse.
The collection hierarchy consists of four interfaces, the core collection intefaces. Two of these interfaces, Set and List, are children of the Collection interface; they add further constraints on the contracts imposed by the methods in this interface, as well as adding new methods. The final core collection interface, Map, is not a child of Collection, as it represents a mapping rather than a true collection.
All of the methods in Collection and the other core interfaces that modify the collection are labeled optional. Some implementations may not perform one or more of these operations, throwing a runtime exception,n UnsupportedOperationException, if they are attempted. Implementations should specify in their documentation which optional operations they support. Several terms are introduced to aid in this specification:
Some implementations may restrict what elements (or in the case of Maps, keys and values) may be stored. Possible restrictions include requiring elements to:
All general-purpose Collection implementation classes 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. Similarly, all general-purpose Map implementations should provide a void (no arguments) constructor and a constructor that takes a single argument of type Map. There is no way to enforce these recommendations (as interfaces cannot contain constructors) but all of the general-purpose Collection and Map implementations in the JDK comply.
Collection implementation classes typically have names of the form <Implementation><Interface>. Set implementations in the JDK include HashSet, TreeSet, and ArraySet. List implementations include ArrayList, LinkedList and Vector. Map implementations include HashMap, TreeMap, ArrayMap, and Hashtable. (The JDK contains no class that implements Collection directly.) All of the JDK implementations with "new style" (<Implementation><Interface>) names are unsynchronized. The Collections class contains static factories that may be used to add synchronization to any unsynchronized collection.
The AbstractCollection, AbstractSet, AbstractList and AbstractSequentialList classes provide skeletal implementations of the core collection interfaces, to minimize the effort required to implement them. The Iterator, ListIterator, Comparable and Comparator interfaces provide the required "infrastructure."
add(A)
addAll(Collection<A>)
clear()
contains(A)
containsAll(Collection<A>)
equals(Object)
hashCode()
isEmpty()
iterator()
remove(A)
removeAll(Collection<A>)
retainAll(Collection<A>)
size()
toArray(A[])
toArray()
sizepublic abstract int size();
public abstract boolean isEmpty();
public abstract boolean contains(A o);
e such that (o==null ? e==null :
o.equals(e)).
public abstract Iterator<A> iterator();
public abstract Object[] toArray();
This method acts as bridge between array-based and Collection-based APIs.
public abstract A[] toArray(A[] a);
If the Collection fits in the specified array with room to spare (i.e., the array has more elements than the Collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of the Collection only if the caller knows that the Collection does not contain any null elements.)
If this Collection makes any guarantees as to what order its elements are returned by its Iterator, this method must return the elements in the same order.
Like toArray(), this method acts as bridge between
array-based and Collection-based APIs. Further, this method allows
precise control over the runtime type of the output array, and
may, under certain circumstances, be used to save allocation costs
Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String:
String[] x = (String[]) v.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in
function to toArray().
public abstract boolean add(A o);
public abstract boolean remove(A o);
e such that (o==null ? e==null :
o.equals(e)), if the Collection contains one or more such
elements. Returns true if the Collection contained the specified
element (or equivalently, if the Collection changed as a result of the
call).
public abstract boolean containsAll(Collection<A> c);
public abstract boolean addAll(Collection<A> c);
public abstract boolean removeAll(Collection<A> c);
public abstract boolean retainAll(Collection<A> c);
public abstract void clear();
public abstract boolean equals(Object o);
While Collection adds no stipulations to the general contract for Object.equals, programmers who implement Collection "directly" (in other words, create a class that is a Collection but is not a Set or a List) must exercise care if they choose to override Object.equals. It is not necessary to do so, and the simplest course of action is to rely on Object's implementation, but the implementer may wish to implement a "value comparison" in place of the default "reference comparison." (Lists and Sets mandate such value comparisons.)
The general contract for Object.equals states that equals
must be reflexive (in other words, a.equals(b) if and only
if b.equals(a)). The contracts for List.equals and
Set.equals state that Lists are only equal to other Lists, and
Sets to other Sets. Thus, a custom equals method for a Collection
that is neither a List nor a Set must return false when this
Collection is compared to any List or Set.
public abstract int hashCode();
c1.equals(c2) implies that
c1.hashCode()==c2.hashCode().
[all packages]
[package java.util]
[class hierarchy]
[index]