diff --git a/src/changes/changes.xml b/src/changes/changes.xml index f848e382a..64fd90ff2 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -22,6 +22,9 @@ + + Clarified javadoc of "CollectionBag" wrt changes from the original Bag interface. + Removed wrong type bounds for "ComparatorUtils#chainedComparator(...)". diff --git a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java index 668acdbfe..bf53c61eb 100644 --- a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java +++ b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java @@ -26,7 +26,15 @@ import org.apache.commons.collections4.Bag; /** * Decorates another {@link Bag} to comply with the Collection contract. + *

+ * By decorating an existing {@link Bag} instance with a {@link 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. * + * @see Bag + * @param the type held in the bag * @since 4.0 * @version $Id$ */ @@ -88,6 +96,16 @@ public final class CollectionBag extends AbstractBagDecorator { // Collection interface //----------------------------------------------------------------------- + /** + * (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. + * + * @param coll the collection to check against + * @return true if the Bag contains at least on of every object in the collection + */ @Override public boolean containsAll(final Collection coll) { final Iterator e = coll.iterator(); @@ -99,6 +117,16 @@ public final class CollectionBag extends AbstractBagDecorator { return true; } + /** + * (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. + * + * @param object the object to add + * @return true, always + */ @Override public boolean add(final E object) { return add(object, 1); @@ -115,11 +143,30 @@ public final class CollectionBag extends AbstractBagDecorator { return changed; } + /** + * (Change) + * Removes the first occurrence of the given object from the bag. + *

+ * This will also remove the object from the {@link #uniqueSet()} if the + * bag contains no occurrence anymore of the object after this operation. + * + * @param object the object to remove + * @return true if this call changed the collection + */ @Override public boolean remove(final Object object) { return remove(object, 1); } + /** + * (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. + * + * @param coll the collection to remove + * @return true if this call changed the collection + */ @Override public boolean removeAll(final Collection coll) { if (coll != null) { @@ -137,6 +184,17 @@ public final class CollectionBag extends AbstractBagDecorator { } } + /** + * (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. + * + * @param coll the collection to retain + * @return true if this call changed the collection + */ @Override public boolean retainAll(final Collection coll) { if (coll != null) { @@ -159,6 +217,17 @@ public final class CollectionBag extends AbstractBagDecorator { // Bag interface //----------------------------------------------------------------------- + /** + * (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. + * + * @param object the object to add + * @param count the number of copies to add + * @return true, always + */ @Override public boolean add(final E object, final int count) { decorated().add(object, count);