org.apache.commons.collections4.bag

## Class CollectionSortedBag<E>

- java.lang.Object
- - org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>
  - - org.apache.commons.collections4.bag.AbstractBagDecorator<E>
    - - org.apache.commons.collections4.bag.AbstractSortedBagDecorator<E>
      - - org.apache.commons.collections4.bag.CollectionSortedBag<E>

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

      public final class CollectionSortedBag<E>
      extends AbstractSortedBagDecorator<E>

  Decorates another `SortedBag` to comply with the Collection contract.
  Since:
    4.0
  Version:
    $Id: CollectionSortedBag.java 1543168 2013-11-18 21:22:43Z ggregory $
  See Also:
    Serialized Form

- - ### Constructor Summary

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

  - ### Method Summary

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

    - ### Methods inherited from class org.apache.commons.collections4.bag.AbstractSortedBagDecorator

      `comparator, decorated, first, last`

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

      `getCount, remove, uniqueSet`

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

      `clear, contains, equals, hashCode, 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

      `getCount, iterator, remove, size, uniqueSet`

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

      `clear, contains, equals, hashCode, isEmpty, toArray, toArray`

- - ### Constructor Detail

    - #### CollectionSortedBag

          public CollectionSortedBag(SortedBag<E> bag)

      Constructor that wraps (not copies).
      Parameters:
        `bag` - the sorted bag to decorate, must not be null
      Throws:
        `IllegalArgumentException` - if bag is null

  - ### Method Detail

    - #### collectionSortedBag

          public static <E> SortedBag<E> collectionSortedBag(SortedBag<E> bag)

      Factory method to create a sorted bag that complies to the Collection contract.
      Type Parameters:
        `E` - the type of the elements in the bag
      Parameters:
        `bag` - the sorted bag to decorate, must not be null
      Returns:
        a SortedBag that complies to the Collection contract
      Throws:
        `IllegalArgumentException` - if bag is null

    - #### containsAll

          public boolean containsAll(Collection<?> coll)

      Description copied from interface: `Bag`
      (Violation) Returns `true` if the bag contains all elements in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object, calling `Bag.getCount(Object)` on that object must be `>= n` for all `n` in `coll`.

      The `Collection.containsAll(Collection)` method specifies that cardinality should not be respected; this method should return true if the bag contains at least one of every object contained in the given collection.

      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 all the collection

    - #### add

          public boolean add(E object)

      Description copied from interface: `Bag`
      (Violation) Adds one copy of the specified object to the Bag.

      If the object is already in the `Bag.uniqueSet()` then increment its count as reported by `Bag.getCount(Object)`. Otherwise add it to the `Bag.uniqueSet()` and report its count as 1.

      Since this method always increases the size of the bag, according to the `Collection.add(Object)` contract, it should always return `true`. Since it sometimes returns `false`, this method violates the contract.

      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` if the object was not already in the `uniqueSet`

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

      Description copied from interface: `Bag`
      (Violation) Removes all occurrences of the given object from the bag.

      This will also remove the object from the `Bag.uniqueSet()`.

      According to the `Collection.remove(Object)` method, this method should only remove the first occurrence of the given object, not all occurrences.

      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)

      Description copied from interface: `Bag`
      (Violation) Remove all elements represented in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object, the bag will have `n` fewer copies, assuming the bag had at least `n` copies to begin with.

      The `Collection.removeAll(Collection)` method specifies that cardinality should not be respected; this method should 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)

      Description copied from interface: `Bag`
      (Violation) Remove any members of the bag that are not in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object and the bag has `m > n` copies, then delete `m - n` copies from the bag. In addition, if `e` is an object in the bag but `!coll.contains(e)`, then remove `e` and any of its copies.

      The `Collection.retainAll(Collection)` method specifies that cardinality should not be respected; this method should keep all occurrences of every object contained in the given collection.

      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)

      Description copied from interface: `Bag`
      Adds `nCopies` copies of the specified object to the Bag.

      If the object is already in the `Bag.uniqueSet()` then increment its count as reported by `Bag.getCount(Object)`. Otherwise add it to the `Bag.uniqueSet()` and report its count as `nCopies`.

      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` if the object was not already in the `uniqueSet`

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