# Class AbstractCollection<E>

java.lang.Object
java.util.AbstractCollection<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>`

Direct Known Subclasses:
  `AbstractList, AbstractQueue, AbstractSet, ArrayDeque`

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
  Description
  `protected`
  `AbstractCollection()`
  Constructs a new instance of this AbstractCollection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Attempts to add `object` to the contents of this `Collection` (optional).
  `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 a new array containing all elements contained in this `ArrayList`.
  `<T> T[]`
  `toArray(T[] contents)`
  Returns an array containing all elements contained in this `ArrayList`.
  `String`
  `toString()`
  Returns the string representation of this `Collection`.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Collection

  `equals, hashCode`

- ## Constructor Details

  - ### AbstractCollection

    protected AbstractCollection()
    Constructs a new instance of this AbstractCollection.

- ## Method Details

  - ### add

    public boolean add(E object)
    Description copied from interface: `Collection`
    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.
    Specified by:
      `add` in interface `Collection<E>`
    Parameters:
      `object` - the object to add.
    Returns:
      `true` if this `Collection` is modified, `false` otherwise.

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

  - ### 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`.

  - ### 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 `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<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`.

  - ### 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`.

  - ### 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`.

  - ### 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`.

  - ### toArray

    public Object[] toArray()
    Returns a new array containing all elements contained in this `ArrayList`.
    Specified by:
      `toArray` in interface `Collection<E>`
    Returns:
      an array of the elements from this `ArrayList`

  - ### toArray

    public <T> T[] toArray(T[] contents)
    Returns an array containing all elements contained in this `ArrayList`. If the specified array is large enough to hold the elements, the specified array is used, otherwise an array of the same type is created. If the specified array is used and is larger than this `ArrayList`, the array element following the collection elements is set to null.
    Specified by:
      `toArray` in interface `Collection<E>`
    Parameters:
      `contents` - the array.
    Returns:
      an array of the elements from this `ArrayList`.
    Throws:
      `ArrayStoreException` - when the type of an element in this `ArrayList` cannot be stored in the type of the specified array.