Apache Commons Collections 4.4 · org.apache.commons.collections4.BagUtils

Modifier and Type	Field and Description
public static final Bag<E>	EMPTY_BAG An empty unmodifiable bag.
public static final Bag<E>	EMPTY_SORTED_BAG An empty unmodifiable sorted bag.

Access	Constructor and Description
private	BagUtils() Instantiation of BagUtils is not intended or required.

Method Summary

Modifier and Type	Method and Description
public static < the element type E> Bag<E>	Returns: a Bag that complies to the Collection contract collectionBag(final Bag<E> the bag to decorate, must not be null bag) Returns a bag that complies to the Collection contract, backed by the given bag.
public static < the element type E> Bag<E>	Returns: an empty Bag emptyBag() Get an empty `Bag`.
public static < the element type E> SortedBag<E>	Returns: an empty sorted Bag emptySortedBag() Get an empty `SortedBag`.
public static < the element type E> Bag<E>	Returns: a predicated bag backed by the given bag predicatedBag(final Bag<E> the bag to predicate, must not be null bag, final Predicate<? super E> the predicate for the bag, must not be null predicate) Returns a predicated (validating) bag backed by the given bag.
public static < the element type E> SortedBag<E>	Returns: a predicated bag backed by the given bag predicatedSortedBag(final SortedBag<E> the sorted bag to predicate, must not be null bag, final Predicate<? super E> the predicate for the bag, must not be null predicate) Returns a predicated (validating) sorted bag backed by the given sorted bag.
public static < the element type E> Bag<E>	Returns: a synchronized bag backed by that bag synchronizedBag(final Bag<E> the bag to synchronize, must not be null bag) Returns a synchronized (thread-safe) bag backed by the given bag.
public static < the element type E> SortedBag<E>	Returns: a synchronized bag backed by that bag synchronizedSortedBag(final SortedBag<E> the bag to synchronize, must not be null bag) Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag.
public static < the element type E> Bag<E>	Returns: a transformed bag backed by the given bag transformingBag(final Bag<E> the bag to predicate, must not be null bag, final Transformer<? super E, ? extends E> the transformer for the bag, must not be null transformer) Returns a transformed bag backed by the given bag.
public static < the element type E> SortedBag<E>	Returns: a transformed bag backed by the given bag transformingSortedBag(final SortedBag<E> the bag to predicate, must not be null bag, final Transformer<? super E, ? extends E> the transformer for the bag, must not be null transformer) Returns a transformed sorted bag backed by the given bag.
public static < the element type E> Bag<E>	Returns: an unmodifiable view of that bag unmodifiableBag(final Bag<? extends E> the bag whose unmodifiable view is to be returned, must not be null bag) Returns an unmodifiable view of the given bag.
public static < the element type E> SortedBag<E>	Returns: an unmodifiable view of that bag unmodifiableSortedBag(final SortedBag<E> the bag whose unmodifiable view is to be returned, must not be null bag) Returns an unmodifiable view of the given sorted bag.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

EMPTY_BAG	back to summary
public static final Bag<E> EMPTY_BAG An empty unmodifiable bag. Annotations @SuppressWarnings:rawtypes

EMPTY_SORTED_BAG	back to summary
public static final Bag<E> EMPTY_SORTED_BAG An empty unmodifiable sorted bag. Annotations @SuppressWarnings:rawtypes

BagUtils	back to summary
private BagUtils() Instantiation of BagUtils is not intended or required.

Method Detail

collectionBag	back to summary
public static <E> Bag<E> collectionBag(final Bag<E> bag) Returns a bag that complies to the Collection contract, backed by the given bag. Parameters <E> the element type bag:Bag<E> the bag to decorate, must not be null Returns:Bag<E> a Bag that complies to the Collection contract Exceptions NullPointerException: if bag is null Since 4.0

collectionBag

back to summary

public static <E> Bag<E> collectionBag(final Bag<E> bag)

Returns a bag that complies to the Collection contract, backed by the given bag.

Parameters

<E>: the element type
bag:Bag<E>: the bag to decorate, must not be null

Returns:Bag<E>

a Bag that complies to the Collection contract

Exceptions

NullPointerException:: if bag is null

Since

4.0

emptyBag back to summary

emptyBag	back to summary
public static <E> Bag<E> emptyBag() Get an empty `Bag`. Parameters <E> the element type Returns:Bag<E> an empty Bag Annotations @SuppressWarnings:unchecked

public static <E> Bag<E> emptyBag()

Get an empty Bag.

Parameters

<E>: the element type

Returns:Bag<E>

an empty Bag

Annotations

@SuppressWarnings:unchecked

emptySortedBag back to summary

emptySortedBag	back to summary
public static <E> SortedBag<E> emptySortedBag() Get an empty `SortedBag`. Parameters <E> the element type Returns:SortedBag<E> an empty sorted Bag Annotations @SuppressWarnings:unchecked

public static <E> SortedBag<E> emptySortedBag()

Get an empty SortedBag.

Parameters

<E>: the element type

Returns:SortedBag<E>

an empty sorted Bag

Annotations

@SuppressWarnings:unchecked

predicatedBag	back to summary
public static <E> Bag<E> predicatedBag(final Bag<E> bag, final Predicate<? super E> predicate) Returns a predicated (validating) bag backed by the given bag. Only objects that pass the test in the given predicate can be added to the bag. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original bag after invoking this method, as it is a backdoor for adding invalid objects. Parameters <E> the element type bag:Bag<E> the bag to predicate, must not be null predicate:Predicate<? super E> the predicate for the bag, must not be null Returns:Bag<E> a predicated bag backed by the given bag Exceptions NullPointerException: if the Bag or Predicate is null

predicatedBag

back to summary

public static <E> Bag<E> predicatedBag(final Bag<E> bag, final Predicate<? super E> predicate)

Returns a predicated (validating) bag backed by the given bag.

Only objects that pass the test in the given predicate can be added to the bag. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original bag after invoking this method, as it is a backdoor for adding invalid objects.

Parameters

<E>: the element type
bag:Bag<E>: the bag to predicate, must not be null
predicate:Predicate<? super E>: the predicate for the bag, must not be null

Returns:Bag<E>

a predicated bag backed by the given bag

Exceptions

NullPointerException:: if the Bag or Predicate is null

predicatedSortedBag	back to summary
public static <E> SortedBag<E> predicatedSortedBag(final SortedBag<E> bag, final Predicate<? super E> predicate) Returns a predicated (validating) sorted bag backed by the given sorted bag. Only objects that pass the test in the given predicate can be added to the bag. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original bag after invoking this method, as it is a backdoor for adding invalid objects. Parameters <E> the element type bag:SortedBag<E> the sorted bag to predicate, must not be null predicate:Predicate<? super E> the predicate for the bag, must not be null Returns:SortedBag<E> a predicated bag backed by the given bag Exceptions NullPointerException: if the SortedBag or Predicate is null

predicatedSortedBag

back to summary

public static <E> SortedBag<E> predicatedSortedBag(final SortedBag<E> bag, final Predicate<? super E> predicate)

Returns a predicated (validating) sorted bag backed by the given sorted bag.

Parameters

<E>: the element type
bag:SortedBag<E>: the sorted bag to predicate, must not be null
predicate:Predicate<? super E>: the predicate for the bag, must not be null

Returns:SortedBag<E>

a predicated bag backed by the given bag

Exceptions

NullPointerException:: if the SortedBag or Predicate is null

synchronizedBag	back to summary
public static <E> Bag<E> synchronizedBag(final Bag<E> bag) Returns a synchronized (thread-safe) bag backed by the given bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag. It is imperative that the user manually synchronize on the returned bag when iterating over it: Bag bag = BagUtils.synchronizedBag(new HashBag()); ... synchronized(bag) { Iterator i = bag.iterator(); // Must be in synchronized block while (i.hasNext()) foo(i.next()); } } Failure to follow this advice may result in non-deterministic behavior. Parameters <E> the element type bag:Bag<E> the bag to synchronize, must not be null Returns:Bag<E> a synchronized bag backed by that bag Exceptions NullPointerException: if the Bag is null

synchronizedBag

back to summary

public static <E> Bag<E> synchronizedBag(final Bag<E> bag)

Returns a synchronized (thread-safe) bag backed by the given bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag.

It is imperative that the user manually synchronize on the returned bag when iterating over it:

Bag bag = BagUtils.synchronizedBag(new HashBag());
...
synchronized(bag) {
    Iterator i = bag.iterator(); // Must be in synchronized block
    while (i.hasNext())
        foo(i.next());
    }
}

Failure to follow this advice may result in non-deterministic behavior.

Parameters

<E>: the element type
bag:Bag<E>: the bag to synchronize, must not be null

Returns:Bag<E>

a synchronized bag backed by that bag

Exceptions

NullPointerException:: if the Bag is null

synchronizedSortedBag	back to summary
public static <E> SortedBag<E> synchronizedSortedBag(final SortedBag<E> bag) Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag. It is imperative that the user manually synchronize on the returned bag when iterating over it: SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag()); ... synchronized(bag) { Iterator i = bag.iterator(); // Must be in synchronized block while (i.hasNext()) foo(i.next()); } } Failure to follow this advice may result in non-deterministic behavior. Parameters <E> the element type bag:SortedBag<E> the bag to synchronize, must not be null Returns:SortedBag<E> a synchronized bag backed by that bag Exceptions NullPointerException: if the SortedBag is null

synchronizedSortedBag

back to summary

public static <E> SortedBag<E> synchronizedSortedBag(final SortedBag<E> bag)

Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag.

It is imperative that the user manually synchronize on the returned bag when iterating over it:

SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
...
synchronized(bag) {
    Iterator i = bag.iterator(); // Must be in synchronized block
    while (i.hasNext())
        foo(i.next());
    }
}

Failure to follow this advice may result in non-deterministic behavior.

Parameters

<E>: the element type
bag:SortedBag<E>: the bag to synchronize, must not be null

Returns:SortedBag<E>

a synchronized bag backed by that bag

Exceptions

NullPointerException:: if the SortedBag is null

transformingBag back to summary

transformingBag	back to summary
public static <E> Bag<E> transformingBag(final Bag<E> bag, final Transformer<? super E, ? extends E> transformer) Returns a transformed bag backed by the given bag. Each object is passed through the transformer as it is added to the Bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding untransformed objects. Existing entries in the specified bag will not be transformed. If you want that behaviour, see `TransformedBag#transformedBag(Bag, Transformer)`. Parameters <E> the element type bag:Bag<E> the bag to predicate, must not be null transformer:Transformer<? super E, ? extends E> the transformer for the bag, must not be null Returns:Bag<E> a transformed bag backed by the given bag Exceptions NullPointerException: if the Bag or Transformer is null

public static <E> Bag<E> transformingBag(final Bag<E> bag, final Transformer<? super E, ? extends E> transformer)

Returns a transformed bag backed by the given bag.

Each object is passed through the transformer as it is added to the Bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding untransformed objects.

Existing entries in the specified bag will not be transformed. If you want that behaviour, see TransformedBag#transformedBag(Bag, Transformer).

Parameters

<E>: the element type
bag:Bag<E>: the bag to predicate, must not be null
transformer:Transformer<? super E, ? extends E>: the transformer for the bag, must not be null

Returns:Bag<E>

a transformed bag backed by the given bag

Exceptions

NullPointerException:: if the Bag or Transformer is null

transformingSortedBag back to summary

transformingSortedBag	back to summary
public static <E> SortedBag<E> transformingSortedBag(final SortedBag<E> bag, final Transformer<? super E, ? extends E> transformer) Returns a transformed sorted bag backed by the given bag. Each object is passed through the transformer as it is added to the Bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding untransformed objects. Existing entries in the specified bag will not be transformed. If you want that behaviour, see `TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)`. Parameters <E> the element type bag:SortedBag<E> the bag to predicate, must not be null transformer:Transformer<? super E, ? extends E> the transformer for the bag, must not be null Returns:SortedBag<E> a transformed bag backed by the given bag Exceptions NullPointerException: if the Bag or Transformer is null

public static <E> SortedBag<E> transformingSortedBag(final SortedBag<E> bag, final Transformer<? super E, ? extends E> transformer)

Returns a transformed sorted bag backed by the given bag.

Each object is passed through the transformer as it is added to the Bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding untransformed objects.

Existing entries in the specified bag will not be transformed. If you want that behaviour, see TransformedSortedBag#transformedSortedBag(SortedBag, Transformer).

Parameters

<E>: the element type
bag:SortedBag<E>: the bag to predicate, must not be null
transformer:Transformer<? super E, ? extends E>: the transformer for the bag, must not be null

Returns:SortedBag<E>

a transformed bag backed by the given bag

Exceptions

NullPointerException:: if the Bag or Transformer is null

unmodifiableBag back to summary

unmodifiableBag	back to summary
public static <E> Bag<E> unmodifiableBag(final Bag<? extends E> bag) Returns an unmodifiable view of the given bag. Any modification attempts to the returned bag will raise an `UnsupportedOperationException`. Parameters <E> the element type bag:Bag<? extends E> the bag whose unmodifiable view is to be returned, must not be null Returns:Bag<E> an unmodifiable view of that bag Exceptions NullPointerException: if the Bag is null

public static <E> Bag<E> unmodifiableBag(final Bag<? extends E> bag)

Returns an unmodifiable view of the given bag. Any modification attempts to the returned bag will raise an UnsupportedOperationException.

Parameters

<E>: the element type
bag:Bag<? extends E>: the bag whose unmodifiable view is to be returned, must not be null

Returns:Bag<E>

an unmodifiable view of that bag

Exceptions

NullPointerException:: if the Bag is null

unmodifiableSortedBag back to summary

unmodifiableSortedBag	back to summary
public static <E> SortedBag<E> unmodifiableSortedBag(final SortedBag<E> bag) Returns an unmodifiable view of the given sorted bag. Any modification attempts to the returned bag will raise an `UnsupportedOperationException`. Parameters <E> the element type bag:SortedBag<E> the bag whose unmodifiable view is to be returned, must not be null Returns:SortedBag<E> an unmodifiable view of that bag Exceptions NullPointerException: if the SortedBag is null

public static <E> SortedBag<E> unmodifiableSortedBag(final SortedBag<E> bag)

Returns an unmodifiable view of the given sorted bag. Any modification attempts to the returned bag will raise an UnsupportedOperationException.

Parameters

<E>: the element type
bag:SortedBag<E>: the bag whose unmodifiable view is to be returned, must not be null

Returns:SortedBag<E>

an unmodifiable view of that bag

Exceptions

NullPointerException:: if the SortedBag is null

public Class BagUtils

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail