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

    ###### Parameters

    - `object`: the object to add.

    ###### Returns

    Specified by:
      `add` in interface `Collection<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if adding to this `Collection` is not supported.

      - `ClassCastException`: @throws 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`.

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

    ###### Parameters

    - `collection`: the collection of objects.

    ###### Returns

    Specified by:
      `addAll` in interface `Collection<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if adding to this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if the class of an object is inappropriate for this `Collection`.

      - `IllegalArgumentException`: if an object cannot be added to this `Collection`.

      - `NullPointerException`: @throws 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.

    ###### Throws

    - `UnsupportedOperationException`: @throws UnsupportedOperationException it the iterator does not support removing elements from this `Collection`

    ###### See also

    - #iterator

    - #isEmpty

    - #size

    Specified by:
      `clear` in interface `Collection<E>`

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

    ###### 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`: @throws NullPointerException if the object to look for is `null` and this `Collection` doesn't support `null` elements.

    Specified by:
      `contains` in interface `Collection<E>`
    Returns:

      `true` if object is an element of this `Collection`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException if the object to look for isn't of the correct type.

      - `NullPointerException`: @throws 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.

    ###### Parameters

    - `collection`: the collection of objects.

    ###### Returns

    Specified by:
      `containsAll` in interface `Collection<E>`
    Returns:

      `true` if all objects in the specified `Collection` are elements of this `Collection`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws 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.

    ###### Returns

    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.

    ###### Returns

    an iterator for accessing the `Collection` contents.

    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`

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

    ###### Parameters

    - `object`: the object to remove.

    ###### Returns

    Specified by:
      `remove` in interface `Collection<E>`
    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`: @throws 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.

    ###### Parameters

    - `collection`: the collection of objects to remove.

    ###### Returns

    Specified by:
      `removeAll` in interface `Collection<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws 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.

    ###### Parameters

    - `collection`: the collection of objects to retain.

    ###### Returns

    Specified by:
      `retainAll` in interface `Collection<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws 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.

    ###### Returns

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

    ###### Returns

    the string representation of this `Collection`.

    Overrides:
      `toString` in class `Object`

  - ### toArray

    public Object[] toArray()

    Returns a new array containing all elements contained in this `ArrayList`.

    ###### Returns

    an array of the elements from this `ArrayList`

    Specified by:
      `toArray` in interface `Collection<E>`

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

    ###### Parameters

    - `contents`: the array.

    ###### Returns

    an array of the elements from this `ArrayList`.

    ###### Throws

    - `ArrayStoreException`: @throws ArrayStoreException when the type of an element in this `ArrayList` cannot be stored in the type of the specified array.
    Specified by:
      `toArray` in interface `Collection<E>`