Package org.apache.commons.collections4.collection

# Class CompositeCollection<E>

java.lang.Object
org.apache.commons.collections4.collection.CompositeCollection<E>

Type Parameters:
  `E` - The type of the elements in the collection.

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

public class CompositeCollection<E> extends Object implements Collection<E>, Serializable
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:
  3.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `CompositeCollection.CollectionMutator<E>`
  Pluggable strategy to handle changes to the composite.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CompositeCollection()`
  Constructs an empty CompositeCollection.
  `CompositeCollection(Collection<E> compositeCollection)`
  Constructs a Composite Collection with one collection.
  `CompositeCollection(Collection<E>... compositeCollections)`
  Constructs a Composite Collection with an array of collections.
  `CompositeCollection(Collection<E> compositeCollection1, Collection<E> compositeCollection2)`
  Constructs a Composite Collection with two collections.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E 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> compositeCollection)`
  Add these Collections to the list of collections in this composite.
  `void`
  `addComposited(Collection<E>... compositeCollections)`
  Add these Collections to the list of collections in this composite.
  `void`
  `addComposited(Collection<E> compositeCollection1, Collection<E> compositeCollection2)`
  Add these Collections to the list of collections in 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.
  `List<Collection<E>>`
  `getCollections()`
  Gets the collections being decorated.
  `protected CompositeCollection.CollectionMutator<E>`
  `getMutator()`
  Gets the collection mutator to be used for this CompositeCollection.
  `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`
  `removeIf(Predicate<? super E> filter)`
  Removes all of the elements of this collection that satisfy the given predicate from this composite collection.
  `boolean`
  `retainAll(Collection<?> coll)`
  Retains all the elements in the specified collection in this composite collection, removing all others.
  `void`
  `setMutator(CompositeCollection.CollectionMutator<E> mutator)`
  Specify a CollectionMutator strategy instance to handle changes.
  `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.
  `Collection<E>`
  `toCollection()`
  Returns a new collection containing all of the elements.

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.Collection

  `equals, hashCode, parallelStream, spliterator, stream`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

- ## Constructor Details

  - ### CompositeCollection

    public CompositeCollection()
    Constructs an empty CompositeCollection.

  - ### CompositeCollection

    public CompositeCollection(Collection<E> compositeCollection)
    Constructs a Composite Collection with one collection.
    Parameters:
      `compositeCollection` - The Collection to be appended to the composite.

  - ### CompositeCollection

    public CompositeCollection(Collection<E>... compositeCollections)
    Constructs a Composite Collection with an array of collections.
    Parameters:
      `compositeCollections` - The collections to composite.

  - ### CompositeCollection

    public CompositeCollection(Collection<E> compositeCollection1, Collection<E> compositeCollection2)
    Constructs a Composite Collection with two collections.
    Parameters:
      `compositeCollection1` - The Collection to be appended to the composite.
      `compositeCollection2` - The Collection to be appended to the composite.

- ## Method Details

  - ### add

    public boolean add(E 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.

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

  - ### addComposited

    public void addComposited(Collection<E> compositeCollection)
    Add these Collections to the list of collections in this composite.
    Parameters:
      `compositeCollection` - The Collection to be appended to the composite.

  - ### addComposited

    public void addComposited(Collection<E>... compositeCollections)
    Add these Collections to the list of collections in this composite.
    Parameters:
      `compositeCollections` - The Collections to be appended to the composite.

  - ### addComposited

    public void addComposited(Collection<E> compositeCollection1, Collection<E> compositeCollection2)
    Add these Collections to the list of collections in this composite.
    Parameters:
      `compositeCollection1` - The Collection to be appended to the composite.
      `compositeCollection2` - The Collection to be appended to the composite.

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

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

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

  - ### getCollections

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

  - ### getMutator

    protected CompositeCollection.CollectionMutator<E> getMutator()
    Gets the collection mutator to be used for this CompositeCollection.
    Returns:
      CollectionMutator<E>

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

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

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

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

  - ### removeComposited

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

  - ### removeIf

    public boolean removeIf(Predicate<? super E> filter)
    Removes all of the elements of this collection that satisfy the given predicate from this composite collection.

    This implementation calls `removeIf` on each collection.

    Specified by:
      `removeIf` in interface `Collection<E>`
    Parameters:
      `filter` - A predicate which returns true for elements to be removed.
    Returns:
      true if the collection was modified.
    Throws:
      `UnsupportedOperationException` - if removeIf is unsupported.
    Since:
      4.4

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

  - ### setMutator

    public void setMutator(CompositeCollection.CollectionMutator<E> mutator)
    Specify a CollectionMutator strategy instance to handle changes.
    Parameters:
      `mutator` - The mutator to use

  - ### 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, or `Integer.MAX_VALUE` if the total exceeds it.

  - ### 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>`
    Type Parameters:
      `T` - the type of the elements in the collection.
    Parameters:
      `array` - The array to use, populating if possible.
    Returns:
      An array of all the elements in the collection.

  - ### toCollection

    public Collection<E> toCollection()
    Returns a new collection containing all of the elements.
    Returns:
      A new ArrayList containing all of the elements in this composite. The new collection is not backed by this composite.