org.apache.commons.collections4.set

## Class CompositeSet<E>

- java.lang.Object
- - org.apache.commons.collections4.set.CompositeSet<E>

- All Implemented Interfaces:
    Serializable, Iterable<E>, Collection<E>, Set<E>

      public class CompositeSet<E>
      extends Object
      implements Set<E>, Serializable

  Decorates a set of other sets to provide a single unified view.

  Changes made to this set will actually be made on the decorated set. Add operations require the use of a pluggable strategy. If no strategy is provided then add is unsupported.

  From version 4.0, this class does not extend `CompositeCollection` anymore due to its input restrictions (only accepts Sets). See COLLECTIONS-424 for more details.

  Since:
    3.0
  Version:
    $Id: CompositeSet.java 1543273 2013-11-19 00:52:40Z ggregory $
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `CompositeSet.SetMutator<E>` Define callbacks for mutation operations.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CompositeSet()` Create an empty CompositeSet.
    `CompositeSet(Set<E>... sets)` Create a composite set with sets as the initial set of composited Sets.
    `CompositeSet(Set<E> set)` Create a CompositeSet with just `set` composited.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(E obj)` Adds an object to the collection, throwing UnsupportedOperationException unless a SetMutator strategy is specified.
    `boolean` | `addAll(Collection<? extends E> coll)` Adds a collection of elements to this composite, throwing UnsupportedOperationException unless a SetMutator strategy is specified.
    `void` | `addComposited(Set<E>... sets)` Add these Sets to the list of sets in this composite
    `void` | `addComposited(Set<E> set)` Add a Set to this composite.
    `void` | `addComposited(Set<E> set1, Set<E> set2)` Add these Sets to the list of sets in this composite.
    `void` | `clear()` Removes all of the elements from this composite set.
    `boolean` | `contains(Object obj)` Checks whether this composite set contains the object.
    `boolean` | `containsAll(Collection<?> coll)` Checks whether this composite contains all the elements in the specified collection.
    `boolean` | `equals(Object obj)`
    `protected CompositeSet.SetMutator<E>` | `getMutator()` Get the set mutator to be used for this CompositeSet.
    `List<Set<E>>` | `getSets()` Gets the sets being decorated.
    `int` | `hashCode()`
    `boolean` | `isEmpty()` Checks whether this composite set is empty.
    `Iterator<E>` | `iterator()` Gets an iterator over all the sets in this composite.
    `boolean` | `remove(Object obj)` If a `CollectionMutator` is defined for this CompositeSet then this method will be called anyway.
    `boolean` | `removeAll(Collection<?> coll)` Removes the elements in the specified collection from this composite set.
    `void` | `removeComposited(Set<E> set)` Removes a set from those being decorated in this composite.
    `boolean` | `retainAll(Collection<?> coll)` Retains all the elements in the specified collection in this composite set, removing all others.
    `void` | `setMutator(CompositeSet.SetMutator<E> mutator)` Specify a SetMutator strategy instance to handle changes.
    `int` | `size()` Gets the size of this composite set.
    `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.
    `Set<E>` | `toSet()` Returns a new Set containing all of the elements.

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

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

- - ### Constructor Detail

    - #### CompositeSet

          public CompositeSet()

      Create an empty CompositeSet.

    - #### CompositeSet

          public CompositeSet(Set<E> set)

      Create a CompositeSet with just `set` composited.
      Parameters:
        `set` - the initial set in the composite

    - #### CompositeSet

          public CompositeSet(Set<E>... sets)

      Create a composite set with sets as the initial set of composited Sets.
      Parameters:
        `sets` - the initial sets in the composite

  - ### Method Detail

    - #### size

          public int size()

      Gets the size of this composite set.

      This implementation calls `size()` on each set.

      Specified by:
        `size` in interface `Collection<E>`
      Specified by:
        `size` in interface `Set<E>`
      Returns:
        total number of elements in all contained containers

    - #### isEmpty

          public boolean isEmpty()

      Checks whether this composite set is empty.

      This implementation calls `isEmpty()` on each set.

      Specified by:
        `isEmpty` in interface `Collection<E>`
      Specified by:
        `isEmpty` in interface `Set<E>`
      Returns:
        true if all of the contained sets are empty

    - #### contains

          public boolean contains(Object obj)

      Checks whether this composite set contains the object.

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

      Specified by:
        `contains` in interface `Collection<E>`
      Specified by:
        `contains` in interface `Set<E>`
      Parameters:
        `obj` - the object to search for
      Returns:
        true if obj is contained in any of the contained sets

    - #### iterator

          public Iterator<E> iterator()

      Gets an iterator over all the sets in this composite.

      This implementation uses an `IteratorChain`.

      Specified by:
        `iterator` in interface `Iterable<E>`
      Specified by:
        `iterator` in interface `Collection<E>`
      Specified by:
        `iterator` in interface `Set<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>`
      Specified by:
        `toArray` in interface `Set<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>`
      Specified by:
        `toArray` in interface `Set<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 SetMutator strategy is specified.
      Specified by:
        `add` in interface `Collection<E>`
      Specified by:
        `add` in interface `Set<E>`
      Parameters:
        `obj` - the object to add
      Returns:
        `true` if the collection was modified
      Throws:
        `UnsupportedOperationException` - if SetMutator hasn't been set or 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)

      If a `CollectionMutator` is defined for this CompositeSet then this method will be called anyway.
      Specified by:
        `remove` in interface `Collection<E>`
      Specified by:
        `remove` in interface `Set<E>`
      Parameters:
        `obj` - object to be removed
      Returns:
        true if the object is removed, false otherwise

    - #### 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>`
      Specified by:
        `containsAll` in interface `Set<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 composite, throwing UnsupportedOperationException unless a SetMutator strategy is specified.
      Specified by:
        `addAll` in interface `Collection<E>`
      Specified by:
        `addAll` in interface `Set<E>`
      Parameters:
        `coll` - the collection to add
      Returns:
        true if the composite was modified
      Throws:
        `UnsupportedOperationException` - if SetMutator hasn't been set or 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 set.

      This implementation calls `removeAll` on each collection.

      Specified by:
        `removeAll` in interface `Collection<E>`
      Specified by:
        `removeAll` in interface `Set<E>`
      Parameters:
        `coll` - the collection to remove
      Returns:
        true if the composite 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 set, removing all others.

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

      Specified by:
        `retainAll` in interface `Collection<E>`
      Specified by:
        `retainAll` in interface `Set<E>`
      Parameters:
        `coll` - the collection to remove
      Returns:
        true if the composite was modified
      Throws:
        `UnsupportedOperationException` - if retainAll is unsupported

    - #### clear

          public void clear()

      Removes all of the elements from this composite set.

      This implementation calls `clear()` on each set.

      Specified by:
        `clear` in interface `Collection<E>`
      Specified by:
        `clear` in interface `Set<E>`
      Throws:
        `UnsupportedOperationException` - if clear is unsupported

    - #### setMutator

          public void setMutator(CompositeSet.SetMutator<E> mutator)

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

    - #### addComposited

          public void addComposited(Set<E> set)

      Add a Set to this composite.
      Parameters:
        `set` - the set to add
      Throws:
        `IllegalArgumentException` - if a SetMutator is set, but fails to resolve a collision
        `UnsupportedOperationException` - if there is no SetMutator set
        `NullPointerException` - if `set` is null
      See Also:
        `CompositeSet.SetMutator`

    - #### addComposited

          public void addComposited(Set<E> set1,
                           Set<E> set2)

      Add these Sets to the list of sets in this composite.
      Parameters:
        `set1` - the first Set to be appended to the composite
        `set2` - the second Set to be appended to the composite

    - #### addComposited

          public void addComposited(Set<E>... sets)

      Add these Sets to the list of sets in this composite
      Parameters:
        `sets` - the Sets to be appended to the composite

    - #### removeComposited

          public void removeComposited(Set<E> set)

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

    - #### toSet

          public Set<E> toSet()

      Returns a new Set containing all of the elements.
      Returns:
        A new HashSet containing all of the elements in this composite. The new collection is not backed by this composite.

    - #### getSets

          public List<Set<E>> getSets()

      Gets the sets being decorated.
      Returns:
        Unmodifiable list of all sets in this composite.

    - #### getMutator

          protected CompositeSet.SetMutator<E> getMutator()

      Get the set mutator to be used for this CompositeSet.
      Returns:
        the set mutator

    - #### equals

          public boolean equals(Object obj)

      Specified by:
        `equals` in interface `Collection<E>`
      Specified by:
        `equals` in interface `Set<E>`
      Overrides:
        `equals` in class `Object`
      See Also:
        `Set.equals(java.lang.Object)`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `Collection<E>`
      Specified by:
        `hashCode` in interface `Set<E>`
      Overrides:
        `hashCode` in class `Object`
      See Also:
        `Set.hashCode()`

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