java.util.AbstractCollection< E > Class Template Reference

Inheritance diagram for java.util.AbstractCollection< E >:

Public Member Functions
boolean	add (E object)
boolean	addAll (Collection<? extends E > collection)
void	clear ()
boolean	contains (Object object)
boolean	containsAll (Collection<?> collection)
boolean	isEmpty ()
abstract Iterator< E >	iterator ()
boolean	remove (Object object)
boolean	removeAll (Collection<?> collection)
boolean	retainAll (Collection<?> collection)
abstract int	size ()
Object []	toArray ()
String	toString ()
Public Member Functions inherited from java.util.Collection< E >
boolean	equals (Object object)
int	hashCode ()

Protected Member Functions
	AbstractCollection ()

Detailed Description

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 & Destructor Documentation

AbstractCollection()

java.util.AbstractCollection< E >.AbstractCollection ( )

inlineprotected

Constructs a new instance of this AbstractCollection.

Member Function Documentation

add()

boolean java.util.AbstractCollection< E >.add ( E  object )

inline

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.

Exceptions

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 .

Implements java.util.Collection< E >.

addAll()

boolean java.util.AbstractCollection< E >.addAll ( Collection<? extends E >  collection )

inline

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 

.

Parameters

collection

the collection of objects.

Returns

true 

if this

Collection 

is modified,

false 

otherwise.

Exceptions

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.

Implements java.util.Collection< E >.

clear()

void java.util.AbstractCollection< E >.clear ( )

inline

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.

Exceptions

UnsupportedOperationException

it the iterator does not support removing elements from this Collection

See also

iterator

isEmpty

size

Implements java.util.Collection< E >.

contains()

boolean java.util.AbstractCollection< E >.contains ( Object  object )

inline

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 

.

Parameters

object

the object to search for.

Returns

true 

if object is an element of this

Collection 

,

false 

otherwise.

Exceptions

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.

Implements java.util.Collection< E >.

containsAll()

boolean java.util.AbstractCollection< E >.containsAll ( Collection<?>  collection )

inline

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.

Parameters

collection

the collection of objects.

Returns

true 

if all objects in the specified

Collection 

are elements of this

Collection 

,

false 

otherwise.

Exceptions

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 .

Implements java.util.Collection< E >.

isEmpty()

boolean java.util.AbstractCollection< E >.isEmpty ( )

inline

Returns if this

Collection 

contains no elements. This implementation tests, whether

size 

returns 0.

Returns

true 

if this

Collection 

has no elements,

false 

otherwise.

See also

size

Implements java.util.Collection< E >.

iterator()

abstract Iterator<E> java.util.AbstractCollection< E >.iterator ( )

abstract

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.

Returns

an iterator for accessing the

Collection 

contents.

Implements java.util.Collection< E >.

remove()

boolean java.util.AbstractCollection< E >.remove ( Object  object )

inline

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.

Parameters

object

the object to remove.

Returns

true 

if this

Collection 

is modified,

false 

otherwise.

Exceptions

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.

Implements java.util.Collection< E >.

removeAll()

boolean java.util.AbstractCollection< E >.removeAll ( Collection<?>  collection )

inline

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.

Parameters

collection

the collection of objects to remove.

Returns

true 

if this

Collection 

is modified,

false 

otherwise.

Exceptions

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 .

Implements java.util.Collection< E >.

retainAll()

boolean java.util.AbstractCollection< E >.retainAll ( Collection<?>  collection )

inline

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.

Parameters

collection

the collection of objects to retain.

Returns

true 

if this

Collection 

is modified,

false 

otherwise.

Exceptions

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 .

Implements java.util.Collection< E >.

size()

abstract int java.util.AbstractCollection< E >.size ( )

abstract

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.

Returns

how many objects this

Collection 

contains, or

Integer.MAX_VALUE 

if there are more than

Integer.MAX_VALUE 

elements in this

Collection 

.

Implements java.util.Collection< E >.

toArray()

Object [] java.util.AbstractCollection< E >.toArray ( )

inline

Returns a new array containing all elements contained in this

Collection 

.

If the implementation has ordered elements it will return the element array in the same order as an iterator would return them.

The array returned does not reflect any changes of the

Collection 

. A new array is created even if the underlying data structure is already an array.

Returns

an array of the elements from this

Collection 

.

Implements java.util.Collection< E >.

toString()

String java.util.AbstractCollection< E >.toString ( )

inline

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

Returns

the string representation of this

Collection 

.

---

The documentation for this class was generated from the following file:

• src/java/util/AbstractCollection.java