Top Description Fields Constructors Methods
org.apache.commons.collections4.bag

public final Class CollectionBag<E>

extends AbstractBagDecorator<E>
Class Inheritance
Type Parameters
<E>
the type of elements in this bag
Imports
java.io.IOException, .ObjectInputStream, .ObjectOutputStream, java.util.Collection, .Iterator, org.apache.commons.collections4.Bag
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

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Hides org.apache.commons.collections4.bag.AbstractBagDecorator.serialVersionUID.

Serialization version

Constructor Summary

AccessConstructor and Description
public
CollectionBag(final Bag<E>
the bag to decorate, must not be null
bag)

Constructor that wraps (not copies).

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true, always
add(final E
the object to add
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements org.apache.commons.collections4.Bag.add, java.util.Collection.add.

(Change) Adds one copy of the specified object to the Bag.
public boolean

Returns:

true, always
add(final E
the object to add
object, final int
the number of copies to add
count)

Overrides org.apache.commons.collections4.bag.AbstractBagDecorator.add.

Implements org.apache.commons.collections4.Bag.add.

(Change) Adds count copies of the specified object to the Bag.
public boolean
addAll(final Collection<? extends E>
collection containing elements to be added to this collection
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Collection.addAll.

Adds all of the elements in the specified collection to this collection (optional operation).
public static <
the type of the elements in the bag
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)

Factory method to create a bag that complies to the Collection contract.

public boolean

Returns:

true if the Bag contains at least one of every object in the collection
containsAll(final Collection<?>
the collection to check against
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.containsAll.

Implements org.apache.commons.collections4.Bag.containsAll, java.util.Collection.containsAll.

(Change) Returns true if the bag contains all elements in the given collection, not respecting cardinality.
private void
readObject(final ObjectInputStream
the input stream
in)

Read the collection in using a custom routine.

public boolean

Returns:

true if this call changed the collection
remove(final Object
the object to remove
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements org.apache.commons.collections4.Bag.remove, java.util.Collection.remove.

(Change) Removes the first occurrence of the given object from the bag.
public boolean

Returns:

true if this call changed the collection
removeAll(final Collection<?>
the collection to remove
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements org.apache.commons.collections4.Bag.removeAll, java.util.Collection.removeAll.

(Change) Remove all elements represented in the given collection, not respecting cardinality.
public boolean

Returns:

true if this call changed the collection
retainAll(final Collection<?>
the collection to retain
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements org.apache.commons.collections4.Bag.retainAll, java.util.Collection.retainAll.

(Change) Remove any members of the bag that are not in the given collection, not respecting cardinality.
private void
writeObject(final ObjectOutputStream
the output stream
out)

Write the collection out using a custom routine.

Inherited from org.apache.commons.collections4.bag.AbstractBagDecorator:
decoratedequalsgetCounthashCoderemoveuniqueSet

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.collections4.bag.AbstractBagDecorator.serialVersionUID.

Serialization version

Constructor Detail

CollectionBagback to summary
public CollectionBag(final Bag<E> bag)

Constructor that wraps (not copies).

Parameters
bag:Bag<E>

the bag to decorate, must not be null

Exceptions
NullPointerException:
if bag is null

Method Detail

addback to summary
public boolean add(final E object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements org.apache.commons.collections4.Bag.add, java.util.Collection.add.

(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.

Parameters
object:E

the object to add

Returns:boolean

true, always

Annotations
@Override
addback to summary
public boolean add(final E object, final int count)

Overrides org.apache.commons.collections4.bag.AbstractBagDecorator.add.

Implements org.apache.commons.collections4.Bag.add.

(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.

Parameters
object:E

the object to add

count:int

the number of copies to add

Returns:boolean

true, always

Annotations
@Override
addAllback to summary
public boolean addAll(final Collection<? extends E> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Collection.addAll.

Doc from java.util.Collection.addAll.

Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.) If the specified collection has a defined encounter order, processing of its elements generally occurs in that order.

Parameters
coll:Collection<? extends E>

collection containing elements to be added to this collection

Returns:boolean

true if this collection changed as a result of the call

Annotations
@Override
collectionBagback to summary
public static <E> Bag<E> collectionBag(final Bag<E> bag)

Factory method to create a bag that complies to the Collection contract.

Parameters
<E>
the type of the elements in the bag
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
containsAllback to summary
public boolean containsAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.containsAll.

Implements org.apache.commons.collections4.Bag.containsAll, java.util.Collection.containsAll.

(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.

Parameters
coll:Collection<?>

the collection to check against

Returns:boolean

true if the Bag contains at least one of every object in the collection

Annotations
@Override
readObjectback to summary
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException

Read the collection in using a custom routine.

Parameters
in:ObjectInputStream

the input stream

Annotations
@SuppressWarnings:unchecked
Exceptions
IOException:
if an error occurs while reading from the stream
ClassNotFoundException:
if an object read from the stream can not be loaded
ClassCastException:
if deserialised object has wrong type
removeback to summary
public boolean remove(final Object object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements org.apache.commons.collections4.Bag.remove, java.util.Collection.remove.

(Change) Removes the first occurrence of the given object from the bag.

This will also remove the object from the uniqueSet() if the bag contains no occurrence anymore of the object after this operation.

Parameters
object:Object

the object to remove

Returns:boolean

true if this call changed the collection

Annotations
@Override
removeAllback to summary
public boolean removeAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements org.apache.commons.collections4.Bag.removeAll, java.util.Collection.removeAll.

(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.

Parameters
coll:Collection<?>

the collection to remove

Returns:boolean

true if this call changed the collection

Annotations
@Override
retainAllback to summary
public boolean retainAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements org.apache.commons.collections4.Bag.retainAll, java.util.Collection.retainAll.

(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).

Parameters
coll:Collection<?>

the collection to retain

Returns:boolean

true if this call changed the collection

Annotations
@Override
writeObjectback to summary
private void writeObject(final ObjectOutputStream out) throws IOException

Write the collection out using a custom routine.

Parameters
out:ObjectOutputStream

the output stream

Exceptions
IOException:
if an error occurs while writing to the stream