java.util

Class AbstractCollection<E>

java.lang.Object

java.util.AbstractCollection<E>

All Implemented Interfaces:

Iterable<E>, Collection<E>

Direct Known Subclasses:

AbstractList, AbstractQueue, AbstractSet, ArrayDeque, ConcurrentLinkedDeque

public abstract class AbstractCollection<E>
extends Object
implements Collection<E>

Class AbstractCollection is an abstract implementation of the Collection interface. A subclass must implement the abstract methods iterator() and size() to create an immutable collection. To create a modifiable collection it's necessary to override the add() method that currently throws an UnsupportedOperationException.

Since:

1.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractCollection() Constructs a new instance of this AbstractCollection.

Method Summary

Modifier and Type	Method and Description
boolean	add(E object) Ensures that this collection contains the specified element (optional operation).
boolean	addAll(Collection<? extends E> collection) Attempts to add all of the objects contained in collection to the contents of this Collection (optional).
void	clear() Removes all elements from this Collection, leaving it empty (optional).
boolean	contains(Object object) Tests whether this Collection contains the specified object.
boolean	containsAll(Collection<?> collection) Tests whether this Collection contains all objects contained in the specified Collection.
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.
boolean	remove(Object object) Removes one instance of the specified object from this Collection if one is contained (optional).
boolean	removeAll(Collection<?> collection) Removes all occurrences in this Collection of each object in the specified Collection (optional).
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.
Object[]	toArray() Returns an array containing all of the elements in this collection.
<T> T[]	toArray(T[] contents) Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
String	toString() Returns the string representation of this Collection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, forEach, hashCode, parallelStream, removeIf, spliterator, stream, toArray

Constructor Detail

AbstractCollection

protected AbstractCollection()

Constructs a new instance of this AbstractCollection.

Method Detail

add

public boolean add(E object)

Description copied from interface: Collection

Ensures that this collection contains the specified element (optional operation). Returns true if this collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.)

Collections that support this operation may place limitations on what elements may be added to this collection. In particular, some collections will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added.

If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns.

Specified by:

add in interface Collection<E>

Parameters:

object - element whose presence in this collection is to be ensured

Returns:

true if this collection changed as a result of the call

addAll

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

Attempts to add all of the objects contained in collection to the contents of this Collection (optional). This implementation iterates over the given Collection and calls add for each element. If any of these calls return true, then true is returned as result of this method call, false otherwise. If this Collection does not support adding elements, an UnsupportedOperationException is thrown.

If the passed Collection is changed during the process of adding elements to this Collection, the behavior depends on the behavior of the passed Collection.

Specified by:

addAll in interface Collection<E>

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.

See Also:

Collection.add(Object)

clear

public void clear()

Removes all elements from this Collection, leaving it empty (optional). This implementation iterates over this Collection and calls the remove method on each element. If the iterator does not support removal of elements, an UnsupportedOperationException is thrown.

Concrete implementations usually can clear a Collection more efficiently and should therefore overwrite this method.

Specified by:

clear in interface Collection<E>

Throws:

UnsupportedOperationException - it the iterator does not support removing elements from this Collection

See Also:

iterator(), isEmpty(), size()

contains

public boolean contains(Object object)

Tests whether this Collection contains the specified object. This implementation iterates over this Collection and tests, whether any element is equal to the given object. If object != null then object.equals(e) is called for each element e returned by the iterator until the element is found. If object == null then each element e returned by the iterator is compared with the test e == null.

Specified by:

contains in interface Collection<E>

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.

containsAll

public boolean containsAll(Collection<?> collection)

Tests whether this Collection contains all objects contained in the specified Collection. This implementation iterates over the specified Collection. If one element returned by the iterator is not contained in this Collection, then false is returned; true otherwise.

Specified by:

containsAll in interface Collection<E>

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.

See Also:

Collection.contains(Object)

isEmpty

public boolean isEmpty()

Returns if this Collection contains no elements. This implementation tests, whether size returns 0.

Specified by:

isEmpty in interface Collection<E>

Returns:

true if this Collection has no elements, false otherwise.

See Also:

size()

iterator

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 unless the instance of the Collection has a defined order. In that case, the elements are returned in that order.

In this class this method is declared abstract and has to be implemented by concrete Collection implementations.

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Returns:

an iterator for accessing the Collection contents.

remove

public boolean remove(Object object)

Removes one instance of the specified object from this Collection if one is contained (optional). This implementation iterates over this Collection and tests for each element e returned by the iterator, whether e is equal to the given object. If object != null then this test is performed using object.equals(e), otherwise using object == null. If an element equal to the given object is found, then the remove method is called on the iterator and true is returned, false otherwise. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Specified by:

remove in interface Collection<E>

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.

removeAll

public 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.

This implementation iterates over this Collection and tests for each element e returned by the iterator, whether it is contained in the specified Collection. If this test is positive, then the remove method is called on the iterator. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Specified by:

removeAll in interface Collection<E>

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.

See Also:

Collection.remove(Object), Collection.contains(Object)

retainAll

public 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.

This implementation iterates over this Collection and tests for each element e returned by the iterator, whether it is contained in the specified Collection. If this test is negative, then the remove method is called on the iterator. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Specified by:

retainAll in interface Collection<E>

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.

See Also:

Collection.remove(Object), Collection.contains(Object)

size

public abstract int size()

Returns a count of how many objects this Collection contains.

In this class this method is declared abstract and has to be implemented by concrete Collection implementations.

Specified by:

size in interface Collection<E>

Returns:

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

toArray

public Object[] toArray()

Description copied from interface: Collection

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.

Specified by:

toArray in interface Collection<E>

Returns:

an array containing all of the elements in this collection

toArray

public <T> T[] toArray(T[] contents)

Description copied from interface: Collection

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 Collection.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().

Specified by:

toArray in interface Collection<E>

Type Parameters:

T - the runtime type of the array to contain the collection

Parameters:

contents - 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

toString

public String toString()

Returns the string representation of this Collection. The presentation has a specific format. It is enclosed by square brackets ("[]"). Elements are separated by ', ' (comma and space).

Overrides:

toString in class Object

Returns:

the string representation of this Collection.