From 9f14cf8d87353d99b88cede6592fba3f7c81a11c Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sun, 11 May 2003 12:13:58 +0000 Subject: [PATCH] Update licence and javadoc git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131066 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/commons/collections/Bag.java | 201 ++++++++++-------- 1 file changed, 109 insertions(+), 92 deletions(-) diff --git a/src/java/org/apache/commons/collections/Bag.java b/src/java/org/apache/commons/collections/Bag.java index de1e7ff88..48caa314b 100644 --- a/src/java/org/apache/commons/collections/Bag.java +++ b/src/java/org/apache/commons/collections/Bag.java @@ -1,13 +1,10 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Bag.java,v 1.7 2002/07/19 01:15:01 mas Exp $ - * $Revision: 1.7 $ - * $Date: 2002/07/19 01:15:01 $ - * + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Bag.java,v 1.8 2003/05/11 12:13:58 scolebourne Exp $ * ==================================================================== * * The Apache Software License, Version 1.1 * - * Copyright (c) 1999-2002 The Apache Software Foundation. All rights + * Copyright (c) 2001-2003 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -23,11 +20,11 @@ * distribution. * * 3. The end-user documentation included with the redistribution, if - * any, must include the following acknowlegement: + * any, must include the following acknowledgment: * "This product includes software developed by the * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowlegement may appear in the software itself, - * if and wherever such third-party acknowlegements normally appear. + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. * * 4. The names "The Jakarta Project", "Commons", and "Apache Software * Foundation" must not be used to endorse or promote products derived @@ -36,7 +33,7 @@ * * 5. Products derived from this software may not be called "Apache" * nor may "Apache" appear in their names without prior written - * permission of the Apache Group. + * permission of the Apache Software Foundation. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES @@ -58,7 +55,6 @@ * . * */ - package org.apache.commons.collections; import java.util.Collection; @@ -67,159 +63,180 @@ import java.util.Set; /** * A {@link Collection} that counts the number of times an object appears in - * 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 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(); + } - - - - -