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
  Version:
    $Id: CompositeCollection.java 1683951 2015-06-06 20:19:03Z tn $
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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>... compositeCollections)` Add these Collections to the list of collections in this composite
    `void` | `addComposited(Collection<E> compositeCollection)` 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()` Get 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` | `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`

- - ### Constructor Detail

    - #### CompositeCollection

          public CompositeCollection()

      Create an empty CompositeCollection.

    - #### CompositeCollection

          public CompositeCollection(Collection<E> compositeCollection)

      Create a Composite Collection with one collection.
      Parameters:
        `compositeCollection` - the Collection to be appended to the composite

    - #### CompositeCollection

          public CompositeCollection(Collection<E> compositeCollection1,
                             Collection<E> compositeCollection2)

      Create 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

    - #### CompositeCollection

          public CompositeCollection(Collection<E>... compositeCollections)

      Create a Composite Collection with an array of collections.
      Parameters:
        `compositeCollections` - the collections to composite

  - ### Method Detail

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

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

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

    - #### setMutator

          public void setMutator(CompositeCollection.CollectionMutator<E> mutator)

      Specify a CollectionMutator strategy instance to handle changes.
      Parameters:
        `mutator` - the mutator to use

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

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

    - #### removeComposited

          public void removeComposited(Collection<E> coll)

      Removes a collection from the those being decorated in this composite.
      Parameters:
        `coll` - collection to be removed

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

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

      Get the collection mutator to be used for this CompositeCollection.
      Returns:
        CollectionMutator

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.