CollectionE

Collection<E>

java.util

---

Java 1.2

collection

This interface represents a group , or collection, of objects. In Java 5.0 this is a generic interface and the type variable E represents the type of the objects in the collection. The objects may or may not be ordered, and the collection may or may not contain duplicate objects. Collection is not often implemented directly. Instead, most collection classes implement one of the more specific subinterfaces: Set , an unordered collection that does not allow duplicates, or List , an ordered collection that does allow duplicates.

The Collection type provides a general way to refer to any set, list, or other collection of objects; it defines generic methods that work with any collection. contains( ) and containsAll( ) test whether the Collection contains a specified object or all the objects in a given collection. isEmpty( ) returns true if the Collection has no elements, or false otherwise . size ( ) returns the number of elements in the Collection . iterator( ) returns an Iterator object that allows you to iterate through the objects in the collection. toArray( ) returns the objects in the Collection in a new array of type Object . Another version of toArray( ) takes an array as an argument and stores all elements of the Collection (which must all be compatible with the array) into that array. If the array is not big enough, the method allocates a new, larger array of the same type. If the array is too big, the method stores null into the first empty element of the array. This version of toArray( ) returns the array that was passed in or the new array, if one was allocated.

The previous methods all query or extract the contents of a collection. The Collection interface also defines methods for modifying the contents of the collection. add( ) and addAll( ) add an object or a collection of objects to a Collection . remove( ) and removeAll( ) remove an object or collection. retainAll( ) is a variant that removes all objects except those in a specified Collection . clear( ) removes all objects from the collection. All these modification methods except clear( ) return true if the collection was modified as a result of the call. An interface cannot specify constructors, but it is conventional that all implementations of Collection provide at least two standard constructors: one that takes no arguments and creates an empty collection, and a copy constructor that accepts a Collection object that specifies the initial contents of the new Collection .

Implementations of Collection and its subinterfaces are not required to support all operations defined by the Collection interface. All modification methods listed above are optional; an implementation (such as an immutable Set implementation) that does not support them simply throws java.lang.UnsupportedOperationException for these methods. Furthermore, implementations are free to impose restrictions on the types of objects that can be members of a collection. Some implementations might require elements to be of a particular type, for example, and others might not allow null as an element.

See also Set , List , Map , and Collections .

Figure 16-10. java.util.Collection<E>

 public interface  Collection<E>  extends Iterable<E> {  // Public Instance Methods  boolean  add  (E  o  );        boolean  addAll  (Collection<? extends E>  c  );        void  clear  ( );        boolean  contains  (Object  o  );        boolean  containsAll  (Collection<?>  c  );        boolean  equals  (Object  o  );        int  hashCode  ( );        boolean  isEmpty  ( );        Iterator<E>  iterator  ( );        boolean  remove  (Object  o  );        boolean  removeAll  (Collection<?>  c  );        boolean  retainAll  (Collection<?>  c  );        int  size  ( );        Object[ ]  toArray  ( );        <T> T[ ]  toArray  (T[ ]  a  );   } 

Implementations

AbstractCollection , List , Queue , Set

Passed To

Too many methods to list.

Returned By

Too many methods to list.