Package org.apache.commons.collections4.bag

# Class CollectionBag<E>

java.lang.Object
org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>
org.apache.commons.collections4.bag.AbstractBagDecorator<E>
org.apache.commons.collections4.bag.CollectionBag<E>

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

All Implemented Interfaces:
  `Serializable`, `Iterable<E>`, `Collection<E>`, `Bag<E>`

public final class CollectionBag<E> extends AbstractBagDecorator<E>
Decorates another `Bag` to comply with the Collection contract.

By decorating an existing `Bag` instance with a `CollectionBag`, it can be safely passed on to methods that require Collection types that are fully compliant with the Collection contract.

The method Javadoc highlights the differences compared to the original Bag interface.

Since:
  4.0
See Also:
  - `Bag`
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CollectionBag(Bag<E> bag)`
  Constructor that wraps (not copies).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  (Change) Adds one copy of the specified object to the Bag.
  `boolean`
  `add(E object, int count)`
  (Change) Adds `count` copies of the specified object to the Bag.
  `boolean`
  `addAll(Collection<? extends E> coll)`
  `static <E> Bag<E>`
  `collectionBag(Bag<E> bag)`
  Factory method to create a bag that complies to the Collection contract.
  `boolean`
  `containsAll(Collection<?> coll)`
  (Change) Returns `true` if the bag contains all elements in the given collection, not respecting cardinality.
  `boolean`
  `remove(Object object)`
  (Change) Removes the first occurrence of the given object from the bag.
  `boolean`
  `removeAll(Collection<?> coll)`
  (Change) Remove all elements represented in the given collection, not respecting cardinality.
  `boolean`
  `retainAll(Collection<?> coll)`
  (Change) Remove any members of the bag that are not in the given collection, not respecting cardinality.

  ### Methods inherited from class org.apache.commons.collections4.bag.AbstractBagDecorator

  `decorated, equals, getCount, hashCode, remove, uniqueSet`

  ### Methods inherited from class org.apache.commons.collections4.collection.AbstractCollectionDecorator

  `clear, contains, isEmpty, iterator, removeIf, setCollection, size, toArray, toArray, toString`

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

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

  ### Methods inherited from interface org.apache.commons.collections4.Bag

  `iterator, size`

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

  `clear, contains, isEmpty, parallelStream, removeIf, spliterator, stream, toArray, toArray`

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

  `forEach`

- ## Constructor Details

  - ### CollectionBag

    public CollectionBag(Bag<E> bag)
    Constructor that wraps (not copies).
    Parameters:
      `bag` - the bag to decorate, must not be null
    Throws:
      `NullPointerException` - if bag is null

- ## Method Details

  - ### collectionBag

    public static <E> Bag<E> collectionBag(Bag<E> bag)
    Factory method to create a bag that complies to the Collection contract.
    Type Parameters:
      `E` - the type of the elements in the bag
    Parameters:
      `bag` - the bag to decorate, must not be null
    Returns:
      a Bag that complies to the Collection contract
    Throws:
      `NullPointerException` - if bag is null

  - ### add

    public boolean add(E object)
    (Change) Adds one copy of the specified object to the Bag.

    Since this method always increases the size of the bag, it will always return `true`.

    Specified by:
      `add` in interface `Bag<E>`
    Specified by:
      `add` in interface `Collection<E>`
    Overrides:
      `add` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `object` - the object to add
    Returns:
      `true`, always

  - ### add

    public boolean add(E object, int count)
    (Change) Adds `count` copies of the specified object to the Bag.

    Since this method always increases the size of the bag, it will always return `true`.

    Specified by:
      `add` in interface `Bag<E>`
    Overrides:
      `add` in class `AbstractBagDecorator<E>`
    Parameters:
      `object` - the object to add
      `count` - the number of copies to add
    Returns:
      `true`, always

  - ### addAll

    public boolean addAll(Collection<? extends E> coll)
    Specified by:
      `addAll` in interface `Collection<E>`
    Overrides:
      `addAll` in class `AbstractCollectionDecorator<E>`

  - ### containsAll

    public boolean containsAll(Collection<?> coll)
    (Change) Returns `true` if the bag contains all elements in the given collection, not respecting cardinality. That is, if the given collection `coll` contains at least one of every object contained in this object.
    Specified by:
      `containsAll` in interface `Bag<E>`
    Specified by:
      `containsAll` in interface `Collection<E>`
    Overrides:
      `containsAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to check against
    Returns:
      `true` if the Bag contains at least one of every object in the collection

  - ### remove

    public boolean remove(Object object)
    (Change) Removes the first occurrence of the given object from the bag.

    This will also remove the object from the `AbstractBagDecorator.uniqueSet()` if the bag contains no occurrence anymore of the object after this operation.

    Specified by:
      `remove` in interface `Bag<E>`
    Specified by:
      `remove` in interface `Collection<E>`
    Overrides:
      `remove` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `object` - the object to remove
    Returns:
      `true` if this call changed the collection

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    (Change) Remove all elements represented in the given collection, not respecting cardinality. That is, remove all occurrences of every object contained in the given collection.
    Specified by:
      `removeAll` in interface `Bag<E>`
    Specified by:
      `removeAll` in interface `Collection<E>`
    Overrides:
      `removeAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to remove
    Returns:
      `true` if this call changed the collection

  - ### retainAll

    public boolean retainAll(Collection<?> coll)
    (Change) Remove any members of the bag that are not in the given collection, not respecting cardinality. That is, any object in the given collection `coll` will be retained in the bag with the same number of copies prior to this operation. All other objects will be completely removed from this bag.

    This implementation iterates over the elements of this bag, checking each element in turn to see if it's contained in `coll`. If it's not contained, it's removed from this bag. As a consequence, it is advised to use a collection type for `coll` that provides a fast (e.g. O(1)) implementation of `Collection.contains(Object)`.

    Specified by:
      `retainAll` in interface `Bag<E>`
    Specified by:
      `retainAll` in interface `Collection<E>`
    Overrides:
      `retainAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to retain
    Returns:
      `true` if this call changed the collection