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:

  • 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:

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