CompositeCollection (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.util.commons, class: CompositeCollection

# Class CompositeCollection<E>

java.lang.Object
org.apache.cayenne.util.commons.CompositeCollection<E>

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

public class CompositeCollection<E> extends Object implements Collection<E>
Decorates a collection of other collections to provide a single unified view.

Changes made to this collection will actually be made on the decorated collection. Add and remove operations require the use of a pluggable strategy. If no strategy is provided then add and remove are unsupported.

Since:
  4.1 NOTE: this is a simplified and type-safe version of CompositeCollection found in commons-collections v3.2.1
Author:
  Brian McCallister, Stephen Colebourne, Phil Steitz

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected ArrayList<Collection<E>>`
  `all`
  Collections in the composite

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CompositeCollection()`
  Create an empty CompositeCollection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(Object obj)`
  Adds an object to the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
  `boolean`
  `addAll(Collection<? extends E> coll)`
  Adds a collection of elements to this collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
  `void`
  `addComposited(Collection<E> c)`
  Add an additional collection to this composite.
  `void`
  `clear()`
  Removes all of the elements from this collection .
  `boolean`
  `contains(Object obj)`
  Checks whether this composite collection contains the object.
  `boolean`
  `containsAll(Collection<?> coll)`
  Checks whether this composite contains all the elements in the specified collection.
  `Collection<Collection<E>>`
  `getCollections()`
  Gets the collections being decorated.
  `boolean`
  `isEmpty()`
  Checks whether this composite collection is empty.
  `Iterator<E>`
  `iterator()`
  Gets an iterator over all the collections in this composite.
  `boolean`
  `remove(Object obj)`
  Removes an object from the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
  `boolean`
  `removeAll(Collection<?> coll)`
  Removes the elements in the specified collection from this composite collection.
  `void`
  `removeComposited(Collection<E> coll)`
  Removes a collection from the those being decorated in this composite.
  `boolean`
  `retainAll(Collection<?> coll)`
  Retains all the elements in the specified collection in this composite collection, removing all others.
  `int`
  `size()`
  Gets the size of this composite collection.
  `Object[]`
  `toArray()`
  Returns an array containing all of the elements in this composite.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an object array, populating the supplied array if possible.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Collection

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

  ### Methods inherited from interface Iterable

  `forEach`

- ## Field Details

  - ### all

    protected ArrayList<Collection<E>> all
    Collections in the composite

- ## Constructor Details

  - ### CompositeCollection

    public CompositeCollection()
    Create an empty CompositeCollection.

- ## Method Details

  - ### size

    public int size()
    Gets the size of this composite collection.

    This implementation calls `size()` on each collection.

    Specified by:
      `size` in interface `Collection<E>`
    Returns:
      total number of elements in all contained containers

  - ### isEmpty

    public boolean isEmpty()
    Checks whether this composite collection is empty.

    This implementation calls `isEmpty()` on each collection.

    Specified by:
      `isEmpty` in interface `Collection<E>`
    Returns:
      true if all of the contained collections are empty

  - ### contains

    public boolean contains(Object obj)
    Checks whether this composite collection contains the object.

    This implementation calls `contains()` on each collection.

    Specified by:
      `contains` in interface `Collection<E>`
    Parameters:
      `obj` - the object to search for
    Returns:
      true if obj is contained in any of the contained collections

  - ### iterator

    public Iterator<E> iterator()
    Gets an iterator over all the collections in this composite.

    This implementation uses an `IteratorChain`.

    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Returns:
      an `IteratorChain` instance which supports `remove()`. Iteration occurs over contained collections in the order they were added, but this behavior should not be relied upon.
    See Also:
      - `IteratorChain`

  - ### toArray

    public Object[] toArray()
    Returns an array containing all of the elements in this composite.
    Specified by:
      `toArray` in interface `Collection<E>`
    Returns:
      an object array of all the elements in the collection

  - ### toArray

    public <T> T[] toArray(T[] array)
    Returns an object array, populating the supplied array if possible. See `Collection` interface for full details.
    Specified by:
      `toArray` in interface `Collection<E>`
    Parameters:
      `array` - the array to use, populating if possible
    Returns:
      an array of all the elements in the collection

  - ### add

    public boolean add(Object obj)
    Adds an object to the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
    Specified by:
      `add` in interface `Collection<E>`
    Parameters:
      `obj` - the object to add
    Returns:
      true if the collection was modified
    Throws:
      `UnsupportedOperationException` - if CollectionMutator hasn't been set
      `UnsupportedOperationException` - if add is unsupported
      `ClassCastException` - if the object cannot be added due to its type
      `NullPointerException` - if the object cannot be added because its null
      `IllegalArgumentException` - if the object cannot be added

  - ### remove

    public boolean remove(Object obj)
    Removes an object from the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
    Specified by:
      `remove` in interface `Collection<E>`
    Parameters:
      `obj` - the object being removed
    Returns:
      true if the collection is changed
    Throws:
      `UnsupportedOperationException` - if removed is unsupported
      `ClassCastException` - if the object cannot be removed due to its type
      `NullPointerException` - if the object cannot be removed because its null
      `IllegalArgumentException` - if the object cannot be removed

  - ### containsAll

    public boolean containsAll(Collection<?> coll)
    Checks whether this composite contains all the elements in the specified collection.

    This implementation calls `contains()` for each element in the specified collection.

    Specified by:
      `containsAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to check for
    Returns:
      true if all elements contained

  - ### addAll

    public boolean addAll(Collection<? extends E> coll)
    Adds a collection of elements to this collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
    Specified by:
      `addAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to add
    Returns:
      true if the collection was modified
    Throws:
      `UnsupportedOperationException` - if CollectionMutator hasn't been set
      `UnsupportedOperationException` - if add is unsupported
      `ClassCastException` - if the object cannot be added due to its type
      `NullPointerException` - if the object cannot be added because its null
      `IllegalArgumentException` - if the object cannot be added

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    Removes the elements in the specified collection from this composite collection.

    This implementation calls `removeAll` on each collection.

    Specified by:
      `removeAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to remove
    Returns:
      true if the collection was modified
    Throws:
      `UnsupportedOperationException` - if removeAll is unsupported

  - ### retainAll

    public boolean retainAll(Collection<?> coll)
    Retains all the elements in the specified collection in this composite collection, removing all others.

    This implementation calls `retainAll()` on each collection.

    Specified by:
      `retainAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to remove
    Returns:
      true if the collection was modified
    Throws:
      `UnsupportedOperationException` - if retainAll is unsupported

  - ### clear

    public void clear()
    Removes all of the elements from this collection .

    This implementation calls `clear()` on each collection.

    Specified by:
      `clear` in interface `Collection<E>`
    Throws:
      `UnsupportedOperationException` - if clear is unsupported

  - ### addComposited

    public void addComposited(Collection<E> c)
    Add an additional collection to this composite.
    Parameters:
      `c` - the collection to add

  - ### removeComposited

    public void removeComposited(Collection<E> coll)
    Removes a collection from the those being decorated in this composite.
    Parameters:
      `coll` - collection to be removed

  - ### getCollections

    public Collection<Collection<E>> getCollections()
    Gets the collections being decorated.
    Returns:
      Unmodifiable collection of all collections in this composite.