org.apache.commons.collections4.bag

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

    • 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)

      • 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