public interface

Collection

implements Iterable<T>
java.util.Collection<E>
Known Indirect Subclasses

Class Overview

Collection is the root of the collection hierarchy. It defines operations on data collections and the behavior that they will have in all implementations of Collections. All direct or indirect implementations of Collection should implement at least two constructors. One with no parameters which creates an empty collection and one with a parameter of type Collection. This second constructor can be used to create a collection of different type as the initial collection but with the same elements. Implementations of Collection cannot be forced to implement these two constructors but at least all implementations under java.util do. Methods that change the content of a collection throw an UnsupportedOperationException if the underlying collection does not support that operation, though it's not mandatory to throw such an Exception in cases where the requested operation would not change the collection. In these cases it's up to the implementation whether it throws an UnsupportedOperationException or not. Methods marked with (optional) can throw an UnsupportedOperationException if the underlying collection doesn't support that method.

Summary

Public Methods
abstract boolean add(E object)
Attempts to add object to the contents of this Collection (optional).
abstract boolean addAll(Collection<? extends E> collection)
Attempts to add all of the objects contained in Collection to the contents of this Collection (optional).
abstract void clear()
Removes all elements from this Collection, leaving it empty (optional).
abstract boolean contains(Object object)
Tests whether this Collection contains the specified object.
abstract boolean containsAll(Collection<?> collection)
Tests whether this Collection contains all objects contained in the specified Collection.
abstract boolean equals(Object object)
Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
abstract int hashCode()
Returns an integer hash code for the receiver.
abstract boolean isEmpty()
Returns if this Collection contains no elements.
abstract Iterator<E> iterator()
Returns an instance of Iterator that may be used to access the objects contained by this Collection.
abstract boolean remove(Object object)
Removes one instance of the specified object from this Collection if one is contained (optional).
abstract boolean removeAll(Collection<?> collection)
Removes all occurrences in this Collection of each object in the specified Collection (optional).
abstract boolean retainAll(Collection<?> collection)
Removes all objects from this Collection that are not also found in the Collection passed (optional).
abstract int size()
Returns a count of how many objects this Collection contains.
abstract <T> T[] toArray(T[] a)
Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
abstract Object[] toArray()
Returns an array containing all of the elements in this collection.
[Expand]
Inherited Methods
From interface java.lang.Iterable

Public Methods

public abstract boolean add (E object)

Attempts to add object to the contents of this Collection (optional). After this method finishes successfully it is guaranteed that the object is contained in the collection. If the collection was modified it returns true, false if no changes were made. An implementation of Collection may narrow the set of accepted objects, but it has to specify this in the documentation. If the object to be added does not meet this restriction, then an IllegalArgumentException is thrown. If a collection does not yet contain an object that is to be added and adding the object fails, this method must throw an appropriate unchecked Exception. Returning false is not permitted in this case because it would violate the postcondition that the element will be part of the collection after this method finishes.

Parameters
object the object to add.
Returns
  • true if this Collection is modified, false otherwise.
Throws
UnsupportedOperationException if adding to this Collection is not supported.
ClassCastException if the class of the object is inappropriate for this collection.
IllegalArgumentException if the object cannot be added to this Collection.
NullPointerException if null elements cannot be added to the Collection.

public abstract boolean addAll (Collection<? extends E> collection)

Attempts to add all of the objects contained in Collection to the contents of this Collection (optional). If the passed Collection is changed during the process of adding elements to this Collection, the behavior is not defined.

Parameters
collection the Collection of objects.
Returns
  • true if this Collection is modified, false otherwise.
Throws
UnsupportedOperationException if adding to this Collection is not supported.
ClassCastException if the class of an object is inappropriate for this Collection.
IllegalArgumentException if an object cannot be added to this Collection.
NullPointerException if collection is null, or if it contains null elements and this Collection does not support such elements.

public abstract void clear ()

Removes all elements from this Collection, leaving it empty (optional).

Throws
UnsupportedOperationException if removing from this Collection is not supported.
See Also

public abstract boolean contains (Object object)

Tests whether this Collection contains the specified object. Returns true if and only if at least one element elem in this Collection meets following requirement: (object==null ? elem==null : object.equals(elem)).

Parameters
object the object to search for.
Returns
  • true if object is an element of this Collection, false otherwise.
Throws
ClassCastException if the object to look for isn't of the correct type.
NullPointerException if the object to look for is null and this Collection doesn't support null elements.

public abstract boolean containsAll (Collection<?> collection)

Tests whether this Collection contains all objects contained in the specified Collection. If an element elem is contained several times in the specified Collection, the method returns true even if elem is contained only once in this Collection.

Parameters
collection the collection of objects.
Returns
  • true if all objects in the specified Collection are elements of this Collection, false otherwise.
Throws
ClassCastException if one or more elements of collection isn't of the correct type.
NullPointerException if collection contains at least one null element and this Collection doesn't support null elements.
NullPointerException if collection is null.

public abstract boolean equals (Object object)

Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.

Parameters
object the object to compare with this object.
Returns
  • true if the object is the same as this object and false if it is different from this object.
See Also

public abstract int hashCode ()

Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

Returns
  • the receiver's hash.
See Also

public abstract boolean isEmpty ()

Returns if this Collection contains no elements.

Returns
  • true if this Collection has no elements, false otherwise.
See Also

public abstract Iterator<E> iterator ()

Returns an instance of Iterator that may be used to access the objects contained by this Collection. The order in which the elements are returned by the iterator is not defined. Only if the instance of the Collection has a defined order the elements are returned in that order.

Returns
  • an iterator for accessing the Collection contents.

public abstract boolean remove (Object object)

Removes one instance of the specified object from this Collection if one is contained (optional). The element elem that is removed complies with (object==null ? elem==null : object.equals(elem).

Parameters
object the object to remove.
Returns
  • true if this Collection is modified, false otherwise.
Throws
UnsupportedOperationException if removing from this Collection is not supported.
ClassCastException if the object passed is not of the correct type.
NullPointerException if object is null and this Collection doesn't support null elements.

public abstract boolean removeAll (Collection<?> collection)

Removes all occurrences in this Collection of each object in the specified Collection (optional). After this method returns none of the elements in the passed Collection can be found in this Collection anymore.

Parameters
collection the collection of objects to remove.
Returns
  • true if this Collection is modified, false otherwise.
Throws
UnsupportedOperationException if removing from this Collection is not supported.
ClassCastException if one or more elements of collection isn't of the correct type.
NullPointerException if collection contains at least one null element and this Collection doesn't support null elements.
NullPointerException if collection is null.

public abstract boolean retainAll (Collection<?> collection)

Removes all objects from this Collection that are not also found in the Collection passed (optional). After this method returns this Collection will only contain elements that also can be found in the Collection passed to this method.

Parameters
collection the collection of objects to retain.
Returns
  • true if this Collection is modified, false otherwise.
Throws
UnsupportedOperationException if removing from this Collection is not supported.
ClassCastException if one or more elements of collection isn't of the correct type.
NullPointerException if collection contains at least one null element and this Collection doesn't support null elements.
NullPointerException if collection is null.

public abstract int size ()

Returns a count of how many objects this Collection contains.

Returns
  • how many objects this Collection contains, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in this Collection.

public abstract T[] toArray (T[] a)

Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If this collection fits in the specified array with room to spare (i.e., the array has more elements than this 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 this collection only if the caller knows that this 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 the toArray() method, 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 x is a collection known to contain only strings. The following code can be used to dump the collection into a newly allocated array of String: 

 String[] y = x.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to toArray().

Parameters
a the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
Returns
  • an array containing all of the elements in this collection
Throws
ArrayStoreException if the runtime type of the specified array is not a supertype of the runtime type of every element in this collection
NullPointerException if the specified array is null

public abstract Object[] toArray ()

Returns an array containing all of the elements in this collection. 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.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns
  • an array containing all of the elements in this collection