{a, a, b,
- * c}. Calling {@link #getCount(Object)} on a would return
- * 2, while calling {@link #uniqueSet()} would return {a, b, c}.
- *
- * Note that this interface violates the {@link Collection} contract. + * the collection. + *
+ * Suppose you have a Bag that contains {a, a, b, c}.
+ * Calling {@link #getCount(Object)} on a would return 2, while
+ * calling {@link #uniqueSet()} would return {a, b, c}.
+ *
+ * Note that this interface violates the {@link Collection} contract. * The behavior specified in many of these methods is not the same * as the behavior specified by {@link Collection}. The noncompliant methods - * are clearly marked with "(Violation)" in their summary line. A future + * are clearly marked with "(Violation)". A future * version of this class will specify the same behavior as {@link Collection}, * which unfortunately will break backwards compatibility with this version. * - * @since 2.0 + * @since Commons Collections 2.0 + * @version $Revision: 1.8 $ $Date: 2003/05/11 12:13:58 $ + * * @author Chuck Burdick - **/ + * @author Stephen Colebourne + */ public interface Bag extends Collection { + /** - * Return the number of occurrences (cardinality) of the given + * Returns the number of occurrences (cardinality) of the given * object currently in the bag. If the object does not exist in the * bag, return 0. - **/ - public int getCount(Object o); + * + * @param object the object to search for + * @return the number of occurrences of the object, zero if not found + */ + public int getCount(Object object); /** - * (Violation) - * Add the given object to the bag and keep a count. If the object - * is already in the {@link #uniqueSet()} then increment its count as - * reported by {@link #getCount(Object)}. Otherwise add it to the {@link - * #uniqueSet()} and report its count as 1.
- * + * (Violation) + * Adds one copy the specified object to the Bag. + *
+ * If the object is already in the {@link #uniqueSet()} then increment its + * count as reported by {@link #getCount(Object)}. Otherwise add it to the + * {@link #uniqueSet()} and report its count as 1. + *
* Since this method always increases the size of the bag,
* according to the {@link Collection#add(Object)} contract, it
- * should always return true. Since it sometimes returns
- * false, this method violates the contract. A future
- * version of this method will comply by always returning true.
+ * should always return true. Since it sometimes returns
+ * false, this method violates the contract. A future
+ * version of this method will comply by always returning true.
*
- * @return true if the object was not already in the
- * uniqueSet
- * @see #getCount(Object)
- **/
- public boolean add(Object o);
+ * @param object the object to add
+ * @return true if the object was not already in the uniqueSet
+ */
+ public boolean add(Object object);
/**
- * Add i copies of the given object to the bag and
- * keep a count.
- * @return true if the object was not already in the
- * uniqueSet
- * @see #add(Object)
- * @see #getCount(Object)
- **/
- public boolean add(Object o, int i);
+ * Adds nCopies copies of the specified object to the Bag.
+ *
+ * If the object is already in the {@link #uniqueSet()} then increment its
+ * count as reported by {@link #getCount(Object)}. Otherwise add it to the
+ * {@link #uniqueSet()} and report its count as nCopies.
+ *
+ * @param object the object to search for
+ * @param nCopies the number of copies to add
+ * @return true if the object was not already in the uniqueSet
+ */
+ public boolean add(Object object, int nCopies);
/**
- * (Violation)
- * Remove all occurrences of the given object from the bag, and do
- * not represent the object in the {@link #uniqueSet()}.
- *
- *
According to the {@link Collection#remove(Object)} method, - * this method should only remove the first occurrence of the - * given object, not all occurrences. A future version of this + * (Violation) + * Removes all occurrences of the given object from the bag. + *
+ * This will also remove the object from the {@link #uniqueSet()}. + *
+ * According to the {@link Collection#remove(Object)} method,
+ * this method should only remove the first occurrence of the
+ * given object, not all occurrences. A future version of this
* method will comply with the contract by only removing one occurrence
* of the given object.
*
- * @see #remove(Object, int)
* @return true if this call changed the collection
- **/
- public boolean remove(Object o);
+ */
+ public boolean remove(Object object);
/**
- * Remove the given number of occurrences from the bag. If the bag
- * contains i occurrences or less, the item will be
- * removed from the {@link #uniqueSet()}.
- * @see #getCount(Object)
- * @see #remove(Object)
+ * Removes nCopies copies of the specified object from the Bag.
+ *
+ * If the number of copies to remove is greater than the actual number of
+ * copies in the Bag, no error is thrown.
+ *
+ * @param object the object to remove
+ * @param nCopies the number of copies to remove
* @return true if this call changed the collection
- **/
- public boolean remove(Object o, int i);
+ */
+ public boolean remove(Object object, int nCopies);
/**
- * The {@link Set} of unique members that represent all members in
- * the bag. Uniqueness constraints are the same as those in {@link
- * Set}.
- **/
+ * Returns a {@link Set} of unique elements in the Bag.
+ *
+ * Uniqueness constraints are the same as those in {@link java.util.Set}.
+ *
+ * @return the Set of unique Bag elements
+ */
public Set uniqueSet();
/**
* Returns the total number of items in the bag across all types.
- **/
+ *
+ * @return the total size of the Bag
+ */
public int size();
/**
- * (Violation)
+ * (Violation)
* Returns true if the bag contains all elements in
* the given collection, respecting cardinality. That is, if the
- * given collection C contains n copies
+ * given collection coll contains n copies
* of a given object, calling {@link #getCount(Object)} on that object must
- * be >= n for all n in C.
- *
- *
The {@link Collection#containsAll(Collection)} method specifies
- * that cardinality should not be respected; this method should
+ * be >= n for all n in coll.
+ *
+ * The {@link 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. A future version of this method will comply
* with that contract.
- **/
- public boolean containsAll(Collection c);
+ *
+ * @param coll the collection to check against
+ * @return true if the Bag contains all the collection
+ */
+ public boolean containsAll(Collection coll);
/**
- * (Violation)
+ * (Violation)
* Remove all elements represented in the given collection,
* respecting cardinality. That is, if the given collection
- * C contains n copies of a given object,
+ * 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 {@link Collection#removeAll(Collection)} method specifies
- * that cardinality should not be respected; this method should
- * remove all occurrences of every object contained in the
+ * that cardinality should not be respected; this method should
+ * remove all occurrences of every object contained in the
* given collection. A future version of this method will comply
* with that contract.
*
+ * @param coll the collection to remove
* @return true if this call changed the collection
- **/
- public boolean removeAll(Collection c);
+ */
+ public boolean removeAll(Collection coll);
/**
- * (Violation)
+ * (Violation)
* Remove any members of the bag that are not in the given
* collection, respecting cardinality. That is, if the given
- * collection C contains n copies of a
+ * 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
- * !C.contains(e), then remove e and any
+ * !coll.contains(e), then remove e and any
* of its copies.
*
*
The {@link Collection#retainAll(Collection)} method specifies
- * that cardinality should not be respected; this method should
- * keep all occurrences of every object contained in the
+ * that cardinality should not be respected; this method should
+ * keep all occurrences of every object contained in the
* given collection. A future version of this method will comply
* with that contract.
*
+ * @param coll the collection to retain
* @return true if this call changed the collection
- **/
- public boolean retainAll(Collection c);
+ */
+ public boolean retainAll(Collection coll);
/**
* Returns an {@link Iterator} over the entire set of members,
* including copies due to cardinality. This iterator is fail-fast
* and will not tolerate concurrent modifications.
- **/
+ *
+ * @return iterator over all elements in the Bag
+ */
public Iterator iterator();
+
}
-
-
-
-
-