java.util
public interface Collection<E> extends Iterable<E>
All methods of this interface that are defined to modify the collection are defined as optional. An optional operation may throw an UnsupportedOperationException if the data backing this collection does not support such a modification. This may mean that the data structure is immutable, or that it is read-only but may change ("unmodifiable"), or that it is modifiable but of fixed size (such as an array), or any number of other combinations.
A class that wishes to implement this interface should consider subclassing AbstractCollection, which provides basic implementations of most of the methods of this interface. Classes that are prepared to make guarantees about ordering or about absence of duplicate elements should consider implementing List or Set respectively, both of which are subinterfaces of Collection.
A general-purpose implementation of the Collection interface should in most cases provide at least two constructors: One which takes no arguments and creates an empty collection, and one which takes a Collection as an argument and returns a collection containing the same elements (that is, creates a copy of the argument using its own implementation).
Since: 1.2
See Also: List Set Map SortedSet SortedMap HashSet TreeSet ArrayList LinkedList Vector Collections Arrays AbstractCollection
UNKNOWN: updated to 1.4
| Method Summary | |
|---|---|
| boolean | add(E o)
Add an element to this collection.
|
| boolean | addAll(Collection<? extends E> c)
Add the contents of a given collection to this collection.
|
| void | clear()
Clear the collection, such that a subsequent call to isEmpty() would
return true.
|
| boolean | contains(Object o)
Test whether this collection contains a given object as one of its
elements.
|
| boolean | containsAll(Collection<?> c)
Test whether this collection contains every element in a given collection.
|
| boolean | equals(Object o)
Test whether this collection is equal to some object. |
| int | hashCode()
Obtain a hash code for this collection. |
| boolean | isEmpty()
Test whether this collection is empty, that is, if size() == 0.
|
| Iterator<E> | iterator()
Obtain an Iterator over this collection.
|
| boolean | remove(Object o)
Remove a single occurrence of an object from this collection. |
| boolean | removeAll(Collection<?> c)
Remove all elements of a given collection from this collection. |
| boolean | retainAll(Collection<?> c)
Remove all elements of this collection that are not contained in a given
collection. |
| int | size()
Get the number of elements in this collection.
|
| Object[] | toArray()
Copy the current contents of this collection into an array.
|
| <T> T[] | toArray(T[] a)
Copy the current contents of this collection into an array. |
Parameters: o the object to add.
Returns: true if the collection was modified as a result of this action.
Throws: UnsupportedOperationException if this collection does not support the add operation. ClassCastException if o cannot be added to this collection due to its type. NullPointerException if o is null and this collection doesn't support the addition of null values. IllegalArgumentException if o cannot be added to this collection for some other reason.
Parameters: c the collection to add.
Returns: true if the collection was modified as a result of this action.
Throws: UnsupportedOperationException if this collection does not support the addAll operation. ClassCastException if some element of c cannot be added to this collection due to its type. NullPointerException if some element of c is null and this collection does not support the addition of null values. NullPointerException if c itself is null. IllegalArgumentException if some element of c cannot be added to this collection for some other reason.
Throws: UnsupportedOperationException if this collection does not support the clear operation.
Parameters: o the element to look for.
Returns: true if this collection contains at least one element e such that
o == null ? e == null : o.equals(e).
Throws: ClassCastException if the type of o is not a valid type for this collection. NullPointerException if o is null and this collection doesn't support null values.
Parameters: c the collection to test for.
Returns: true if for every element o in c, contains(o) would return true.
Throws: ClassCastException if the type of any element in c is not a valid type for this collection. NullPointerException if some element of c is null and this collection does not support null values. NullPointerException if c itself is null.
If an implementation of Collection, which is not also an implementation of Set or List, should choose to implement this method, it should take care to obey the contract of the equals method of Object. In particular, care should be taken to return false when o is a Set or a List, in order to preserve the symmetry of the relation.
Parameters: o the object to compare to this collection.
Returns: true if the o is equal to this collection.
If an implementation of Collection, which is not also an implementation of Set or List, should choose to implement this method, it should take care to obey the contract of the hashCode method of Object. Note that this method renders it impossible to correctly implement both Set and List, as the required implementations are mutually exclusive.
Returns: a hash code for this collection.
Returns: true if this collection contains no elements.
Returns: an Iterator over the elements of this collection, in any order.
o == null ? e == null
: o.equals(e).
Parameters: o the object to remove.
Returns: true if the collection changed as a result of this call, that is, if the collection contained at least one occurrence of o.
Throws: UnsupportedOperationException if this collection does not support the remove operation. ClassCastException if the type of o is not a valid type for this collection. NullPointerException if o is null and the collection doesn't support null values.
Parameters: c The collection of objects to be removed.
Returns: true if this collection was modified as a result of this call.
Throws: UnsupportedOperationException if this collection does not support the removeAll operation. ClassCastException if the type of any element in c is not a valid type for this collection. NullPointerException if some element of c is null and this collection does not support removing null values. NullPointerException if c itself is null.
Parameters: c The collection of objects to be retained.
Returns: true if this collection was modified as a result of this call.
Throws: UnsupportedOperationException if this collection does not support the retainAll operation. ClassCastException if the type of any element in c is not a valid type for this collection. NullPointerException if some element of c is null and this collection does not support retaining null values. NullPointerException if c itself is null.
Returns: the number of elements in the collection.
Returns: an array of type Object[] and length equal to the size of this collection, containing the elements currently in this collection, in any order.
Parameters: a the array to copy this collection into.
Returns: an array containing the elements currently in this collection, in any order.
Throws: ArrayStoreException if the type of any element of the collection is not a subtype of the element type of a.