{a, a, b, c}.
* Calling {@link #getCount(Object)} on a would return 2, while
* calling {@link #uniqueSet()} would return {a, b, c}.
+ *
*
* NOTE: This interface violates the {@link Collection} contract.
* The behavior specified in many of these methods is not the same
* as the behavior specified by Collection.
* The noncompliant methods are clearly marked with "(Violation)".
* Exercise caution when using a bag as a Collection.
+ *
* This violation resulted from the original specification of this interface.
* In an ideal world, the interface would be changed to fix the problems, however
@@ -60,11 +62,13 @@ public interface Bag
* 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.
+ *
true if the object was not already in the uniqueSet
@@ -78,6 +82,7 @@ public interface BagnCopies.
+ *
*
* @param object the object to add
* @param nCopies the number of copies to add
@@ -90,10 +95,12 @@ public interface 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. + *
* * @param object the object to remove * @returntrue if this call changed the collection
@@ -106,6 +113,7 @@ public interface 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 @@ -117,6 +125,7 @@ public interface Bag* Uniqueness constraints are the same as those in {@link java.util.Set}. + *
* * @return the Set of unique Bag elements */ @@ -137,11 +146,13 @@ public interface Bagcoll contains n copies
* of a given object, calling {@link #getCount(Object)} on that object must
* 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. + *
* * @param coll the collection to check against * @returntrue if the Bag contains all the collection
@@ -157,10 +168,12 @@ public interface Bagn fewer copies, assuming the bag
* had at least n copies to begin with.
*
- * The {@link Collection#removeAll(Collection)} method specifies + *
+ * 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 * given collection. + *
* * @param coll the collection to remove * @returntrue if this call changed the collection
@@ -179,10 +192,12 @@ public interface Bag!coll.contains(e), then remove e and any
* of its copies.
*
- * The {@link Collection#retainAll(Collection)} method specifies + *
+ * 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 * given collection. + *
* * @param coll the collection to retain * @returntrue if this call changed the collection
diff --git a/src/main/java/org/apache/commons/collections4/BagUtils.java b/src/main/java/org/apache/commons/collections4/BagUtils.java
index c9bfed78f..931a218c1 100644
--- a/src/main/java/org/apache/commons/collections4/BagUtils.java
+++ b/src/main/java/org/apache/commons/collections4/BagUtils.java
@@ -61,6 +61,7 @@ public class BagUtils {
* * It is imperative that the user manually synchronize on the returned bag * when iterating over it: + *
* *
* Bag bag = BagUtils.synchronizedBag(new HashBag());
@@ -105,6 +106,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
+ *
*
* @param the element type
* @param bag the bag to predicate, must not be null
@@ -122,9 +124,11 @@ public class BagUtils {
* 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 {@link TransformedBag#transformedBag(Bag, Transformer)}.
+ *
*
* @param the element type
* @param bag the bag to predicate, must not be null
@@ -157,6 +161,7 @@ public class BagUtils {
*
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
+ *
*
*
* SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
@@ -203,6 +208,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
+ *
*
* @param the element type
* @param bag the sorted bag to predicate, must not be null
@@ -221,10 +227,12 @@ public class BagUtils {
* 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
* {@link TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)}.
+ *
*
* @param the element type
* @param bag the bag to predicate, must not be null
diff --git a/src/main/java/org/apache/commons/collections4/BidiMap.java b/src/main/java/org/apache/commons/collections4/BidiMap.java
index 064094369..b5a2e9837 100644
--- a/src/main/java/org/apache/commons/collections4/BidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/BidiMap.java
@@ -26,14 +26,17 @@ import java.util.Set;
* This interface extends Map and so may be used anywhere a map
* is required. The interface provides an inverse map view, enabling
* full access to both directions of the BidiMap.
+ *
*
* Implementations should allow a value to be looked up from a key and
* a key to be looked up from a value with equal performance.
+ *
*
* This map enforces the restriction that there is a 1:1 relation between
* keys and values, meaning that multiple keys cannot map to the same value.
* This is required so that "inverting" the map results in a map without
* duplicate keys. See the {@link #put} method description for more information.
+ *
*
* @param the type of the keys in the map
* @param the type of the values in the map
@@ -48,6 +51,7 @@ public interface BidiMap extends IterableMap {
* When adding a key-value pair, the value may already exist in the map
* against a different key. That mapping is removed, to ensure that the
* value only occurs once in the inverse map.
+ *
*
* BidiMap map1 = new DualHashBidiMap();
* map.put("A","B"); // contains A mapped to B, as per Map
@@ -76,10 +80,12 @@ public interface BidiMap extends IterableMap {
/**
* Gets the key that is currently mapped to the specified value.
*
+ *
* If the value is not contained in the map, null is returned.
*
* Implementations should seek to make this method perform equally as well
* as get(Object).
+ *
*
* @param value the value to find the key for
* @return the mapped key, or null if not found
@@ -96,9 +102,11 @@ public interface BidiMap extends IterableMap {
* value (optional operation).
*
* If the value is not contained in the map, null is returned.
+ *
*
* Implementations should seek to make this method perform equally as well
* as remove(Object).
+ *
*
* @param value the value to find the key-value pair for
* @return the key that was removed, null if nothing removed
@@ -117,10 +125,12 @@ public interface BidiMap extends IterableMap {
*
* Changes to one map will be visible in the other and vice versa.
* This enables both directions of the map to be accessed as a Map.
+ *
*
* Implementations should seek to avoid creating a new object every time this
* method is called. See AbstractMap.values() etc. Calling this
* method on the inverse map should return the original.
+ *
*
* @return an inverted bidirectional map
*/
diff --git a/src/main/java/org/apache/commons/collections4/ComparatorUtils.java b/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
index f0302157d..5c0f5f4a3 100644
--- a/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
+++ b/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
@@ -34,6 +34,7 @@ import org.apache.commons.collections4.comparators.TransformingComparator;
* comparators package. This class merely provides a
* convenient central place if you have use for more than one class
* in the comparators subpackage.
+ *
*
* @since 2.1
*/
@@ -119,8 +120,10 @@ public class ComparatorUtils {
* Gets a Comparator that can sort Boolean objects.
*
* The parameter specifies whether true or false is sorted first.
+ *
*
* The comparator throws NullPointerException if a null value is compared.
+ *
*
* @param trueFirst when true, sort
* true {@link Boolean}s before
@@ -137,6 +140,7 @@ public class ComparatorUtils {
* The returned comparator will consider a null value to be less than
* any nonnull value, and equal to any other null value. Two nonnull
* values will be evaluated with the given comparator.
+ *
*
* @param the object type to compare
* @param comparator the comparator that wants to allow nulls
@@ -157,6 +161,7 @@ public class ComparatorUtils {
* The returned comparator will consider a null value to be greater than
* any nonnull value, and equal to any other null value. Two nonnull
* values will be evaluated with the given comparator.
+ *
*
* @param the object type to compare
* @param comparator the comparator that wants to allow nulls
@@ -177,6 +182,7 @@ public class ComparatorUtils {
* Objects passed to the returned comparator will first be transformed
* by the given transformer before they are compared by the given
* comparator.
+ *
*
* @param the input object type of the transformed comparator
* @param the object type of the decorated comparator