Package org.apache.commons.collections4.set

# Class CompositeSet<E>

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

Type Parameters:
  `E` - the type of the elements in this set

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
See Also:
  - Serialized Form

- ## Nested Class Summary

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

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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> set)`
  Adds a Set to this composite.
  `void`
  `addComposited(Set<E>... sets)`
  Adds these Sets to the list of sets in this composite
  `void`
  `addComposited(Set<E> set1, Set<E> set2)`
  Adds 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()`
  Gets 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`
  `removeIf(Predicate<? super E> filter)`
  `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`

  ### Methods inherited from interface java.util.Collection

  `parallelStream, stream`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

  ### Methods inherited from interface java.util.Set

  `spliterator`

- ## Constructor Details

  - ### CompositeSet

    public CompositeSet()
    Creates an empty CompositeSet.

  - ### CompositeSet

    public CompositeSet(Set<E> set)
    Creates a CompositeSet with just `set` composited.
    Parameters:
      `set` - the initial set in the composite

  - ### CompositeSet

    public CompositeSet(Set<E>... sets)
    Creates a composite set with sets as the initial set of composited Sets.
    Parameters:
      `sets` - the initial sets in the composite

- ## Method Details

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

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

  - ### addComposited

    public void addComposited(Set<E> set)
    Adds 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>... sets)
    Adds these Sets to the list of sets in this composite
    Parameters:
      `sets` - the Sets to be appended to the composite

  - ### addComposited

    public void addComposited(Set<E> set1, Set<E> set2)
    Adds 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

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

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

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

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

  - ### getMutator

    protected CompositeSet.SetMutator<E> getMutator()
    Gets the set mutator to be used for this CompositeSet.
    Returns:
      the set mutator

  - ### getSets

    public List<Set<E>> getSets()
    Gets the sets being decorated.
    Returns:
      Unmodifiable list of all sets in this composite.

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

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

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

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

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

  - ### removeComposited

    public void removeComposited(Set<E> set)
    Removes a set from those being decorated in this composite.
    Parameters:
      `set` - set to be removed

  - ### removeIf

    public boolean removeIf(Predicate<? super E> filter)
    Specified by:
      `removeIf` in interface `Collection<E>`
    Since:
      4.4

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

  - ### setMutator

    public void setMutator(CompositeSet.SetMutator<E> mutator)
    Specify a SetMutator strategy instance to handle changes.
    Parameters:
      `mutator` - the mutator to use

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

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

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