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 held in the 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
  Version:
    $Id: CollectionBag.java 1686855 2015-06-22 13:00:27Z tn $
  See Also:
    `Bag`, Serialized Form

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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, 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, toArray, toArray`

- - ### Constructor Detail

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

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

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

    - #### 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 `Collection<E>`
      Specified by:
        `add` in interface `Bag<E>`
      Overrides:
        `add` in class `AbstractCollectionDecorator<E>`
      Parameters:
        `object` - the object 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>`

    - #### 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 `Collection<E>`
      Specified by:
        `remove` in interface `Bag<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 `Collection<E>`
      Specified by:
        `removeAll` in interface `Bag<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 `Collection<E>`
      Specified by:
        `retainAll` in interface `Bag<E>`
      Overrides:
        `retainAll` in class `AbstractCollectionDecorator<E>`
      Parameters:
        `coll` - the collection to retain
      Returns:
        `true` if this call changed the collection

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

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