## org.apache.commons.collections.collection
Class CompositeCollection

    java.lang.Object
      org.apache.commons.collections.collection.CompositeCollection

All Implemented Interfaces:
  java.lang.Iterable, java.util.Collection

Direct Known Subclasses:
  CompositeSet

    public class CompositeCollection

extends java.lang.Object
implements java.util.Collection

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:
  Commons Collections 3.0
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Brian McCallister, Stephen Colebourne, Phil Steitz

Nested Class Summary
`static interface` `CompositeCollection.CollectionMutator` Pluggable strategy to handle changes to the composite.

Field Summary
`protected java.util.Collection[]` `all` Collections in the composite
`protected CompositeCollection.CollectionMutator` `mutator` CollectionMutator to handle changes to the collection

Constructor Summary
`CompositeCollection()` Create an empty CompositeCollection.
`CompositeCollection(java.util.Collection coll)` Create a Composite Collection with only coll composited.
`CompositeCollection(java.util.Collection[] colls)` Create a CompositeCollection with colls as the initial list of composited collections.

Method Summary
`boolean` `add(java.lang.Object obj)` Adds an object to the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
`boolean` `addAll(java.util.Collection coll)` Adds a collection of elements to this collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
`void` `addComposited(java.util.Collection c)` Add an additional collection to this composite.
`void` `addComposited(java.util.Collection[] comps)` Add these Collections to the list of collections in this composite
`void` `addComposited(java.util.Collection c, java.util.Collection d)` Add two additional collections to this composite.
`void` `clear()` Removes all of the elements from this collection .
`boolean` `contains(java.lang.Object obj)` Checks whether this composite collection contains the object.
`boolean` `containsAll(java.util.Collection coll)` Checks whether this composite contains all the elements in the specified collection.
`java.util.Collection` `getCollections()` Gets the collections being decorated.
`boolean` `isEmpty()` Checks whether this composite collection is empty.
`java.util.Iterator` `iterator()` Gets an iterator over all the collections in this composite.
`boolean` `remove(java.lang.Object obj)` Removes an object from the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
`boolean` `removeAll(java.util.Collection coll)` Removes the elements in the specified collection from this composite collection.
`void` `removeComposited(java.util.Collection coll)` Removes a collection from the those being decorated in this composite.
`boolean` `retainAll(java.util.Collection coll)` Retains all the elements in the specified collection in this composite collection, removing all others.
`void` `setMutator(CompositeCollection.CollectionMutator mutator)` Specify a CollectionMutator strategy instance to handle changes.
`int` `size()` Gets the size of this composite collection.
`java.lang.Object[]` `toArray()` Returns an array containing all of the elements in this composite.
`java.lang.Object[]` `toArray(java.lang.Object[] array)` Returns an object array, populating the supplied array if possible.
`java.util.Collection` `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`

Field Detail

### mutator

    protected CompositeCollection.CollectionMutator mutator

  CollectionMutator to handle changes to the collection

### all

    protected java.util.Collection[] all

  Collections in the composite

Constructor Detail

### CompositeCollection

    public CompositeCollection()

  Create an empty CompositeCollection.

### CompositeCollection

    public CompositeCollection(java.util.Collection coll)

  Create a Composite Collection with only coll composited.

  Parameters:
    `coll` - a collection to decorate

### CompositeCollection

    public CompositeCollection(java.util.Collection[] colls)

  Create a CompositeCollection with colls as the initial list of composited collections.

  Parameters:
    `colls` - an array of collections to decorate

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 `java.util.Collection`
  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 `java.util.Collection`
  Returns:
    true if all of the contained collections are empty

### contains

    public boolean contains(java.lang.Object obj)

  Checks whether this composite collection contains the object.

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

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

### iterator

    public java.util.Iterator iterator()

  Gets an iterator over all the collections in this composite.

  This implementation uses an `IteratorChain`.

  Specified by:
    `iterator` in interface `java.lang.Iterable`
  Specified by:
    `iterator` in interface `java.util.Collection`
  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 java.lang.Object[] toArray()

  Returns an array containing all of the elements in this composite.

  Specified by:
    `toArray` in interface `java.util.Collection`
  Returns:
    an object array of all the elements in the collection

### toArray

    public java.lang.Object[] toArray(java.lang.Object[] array)

  Returns an object array, populating the supplied array if possible. See `Collection` interface for full details.

  Specified by:
    `toArray` in interface `java.util.Collection`
  Parameters:
    `array` - the array to use, populating if possible
  Returns:
    an array of all the elements in the collection

### add

    public boolean add(java.lang.Object obj)

  Adds an object to the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.

  Specified by:
    `add` in interface `java.util.Collection`
  Parameters:
    `obj` - the object to add
  Returns:
    true if the collection was modified
  Throws:
    `java.lang.UnsupportedOperationException` - if CollectionMutator hasn't been set
    `java.lang.UnsupportedOperationException` - if add is unsupported
    `java.lang.ClassCastException` - if the object cannot be added due to its type
    `java.lang.NullPointerException` - if the object cannot be added because its null
    `java.lang.IllegalArgumentException` - if the object cannot be added

### remove

    public boolean remove(java.lang.Object obj)

  Removes an object from the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.

  Specified by:
    `remove` in interface `java.util.Collection`
  Parameters:
    `obj` - the object being removed
  Returns:
    true if the collection is changed
  Throws:
    `java.lang.UnsupportedOperationException` - if removed is unsupported
    `java.lang.ClassCastException` - if the object cannot be removed due to its type
    `java.lang.NullPointerException` - if the object cannot be removed because its null
    `java.lang.IllegalArgumentException` - if the object cannot be removed

### containsAll

    public boolean containsAll(java.util.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 `java.util.Collection`
  Parameters:
    `coll` - the collection to check for
  Returns:
    true if all elements contained

### addAll

    public boolean addAll(java.util.Collection coll)

  Adds a collection of elements to this collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.

  Specified by:
    `addAll` in interface `java.util.Collection`
  Parameters:
    `coll` - the collection to add
  Returns:
    true if the collection was modified
  Throws:
    `java.lang.UnsupportedOperationException` - if CollectionMutator hasn't been set
    `java.lang.UnsupportedOperationException` - if add is unsupported
    `java.lang.ClassCastException` - if the object cannot be added due to its type
    `java.lang.NullPointerException` - if the object cannot be added because its null
    `java.lang.IllegalArgumentException` - if the object cannot be added

### removeAll

    public boolean removeAll(java.util.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 `java.util.Collection`
  Parameters:
    `coll` - the collection to remove
  Returns:
    true if the collection was modified
  Throws:
    `java.lang.UnsupportedOperationException` - if removeAll is unsupported

### retainAll

    public boolean retainAll(java.util.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 `java.util.Collection`
  Parameters:
    `coll` - the collection to remove
  Returns:
    true if the collection was modified
  Throws:
    `java.lang.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 `java.util.Collection`
  Throws:
    `java.lang.UnsupportedOperationException` - if clear is unsupported

### setMutator

    public void setMutator(CompositeCollection.CollectionMutator mutator)

  Specify a CollectionMutator strategy instance to handle changes.

  Parameters:
    `mutator` - the mutator to use

### addComposited

    public void addComposited(java.util.Collection[] comps)

  Add these Collections to the list of collections in this composite

  Parameters:
    `comps` - Collections to be appended to the composite

### addComposited

    public void addComposited(java.util.Collection c)

  Add an additional collection to this composite.

  Parameters:
    `c` - the collection to add

### addComposited

    public void addComposited(java.util.Collection c,
                              java.util.Collection d)

  Add two additional collections to this composite.

  Parameters:
    `c` - the first collection to add
    `d` - the second collection to add

### removeComposited

    public void removeComposited(java.util.Collection coll)

  Removes a collection from the those being decorated in this composite.

  Parameters:
    `coll` - collection to be removed

### toCollection

    public java.util.Collection 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 java.util.Collection getCollections()

  Gets the collections being decorated.

  Returns:
    Unmodifiable collection of all collections in this composite.

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.