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:

  • 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
      Throws:
      ClassCastException - if the class of the specified element prevents it from being added to this 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
      Throws:
      ClassCastException - if the class of the specified element prevents it from being added to this collection

    • 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