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

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

All Implemented Interfaces:
  Collection

Direct Known Subclasses:
  CompositeSet

public class CompositeCollection
extends Object
implements 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: 1.7 $ $Date: 2004/05/26 21:58:02 $
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 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(Collection coll)` Create a Composite Collection with only coll composited.
`CompositeCollection(Collection[] colls)` Create a CompositeCollection with colls as the initial list of composited collections.

Method Summary
`boolean` `add(Object obj)` Adds an object to the collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
`boolean` `addAll(Collection coll)` Adds a collection of elements to this collection, throwing UnsupportedOperationException unless a CollectionMutator strategy is specified.
`void` `addComposited(Collection c)` Add an additional collection to this composite.
`void` `addComposited(Collection[] comps)` Add these Collections to the list of collections in this composite
`void` `addComposited(Collection c, Collection d)` Add two additional collections 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` `getCollections()` Gets the collections being decorated.
`boolean` `isEmpty()` Checks whether this composite collection is empty.
`Iterator` `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 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 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.
`Object[]` `toArray(Object[] array)` Returns an object array, populating the supplied array if possible.
`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 Collection[] all

  Collections in the composite

Constructor Detail

### CompositeCollection

    public CompositeCollection()

  Create an empty CompositeCollection.

### CompositeCollection

    public CompositeCollection(Collection coll)

  Create a Composite Collection with only coll composited.

Parameters:
  `coll` - a collection to decorate

### CompositeCollection

    public CompositeCollection(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 `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 `Collection`
  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`
  Parameters:
    `obj` - the object to search for
  Returns:
    true if obj is contained in any of the contained collections

### iterator

    public Iterator iterator()

  Gets an iterator over all the collections in this composite.

  This implementation uses an `IteratorChain`.

  Specified by:
    `iterator` in interface `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 Object[] toArray()

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

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

### toArray

    public Object[] toArray(Object[] array)

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

  Specified by:
    `toArray` in interface `Collection`
  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`
  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`
  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`
  Parameters:
    `coll` - the collection to check for
  Returns:
    true if all elements contained

### addAll

    public boolean addAll(Collection coll)

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

  Specified by:
    `addAll` in interface `Collection`
  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`
  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`
  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`
  Throws:
    `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(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(Collection c)

  Add an additional collection to this composite.

  Parameters:
    `c` - the collection to add

### addComposited

    public void addComposited(Collection c,
                              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(Collection coll)

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

  Parameters:
    `coll` - collection to be removed

### toCollection

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

  Gets the collections being decorated.

  Returns:
    Unmodifiable collection of all collections in this composite.

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.