Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc: Close tags.

This commit is contained in:
Gary Gregory 2019-05-08 20:41:28 -04:00
parent 8688bf734e
commit 0d489086a3
4 changed files with 41 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/main/java/org/apache/commons/collections4/Bag.java
View File

@ -27,12 +27,14 @@ import java.util.Set;
* Suppose you have a Bag that contains <code>{a, a, b, c}</code>.
* Calling {@link #getCount(Object)} on <code>a</code> would return 2, while
* calling {@link #uniqueSet()} would return <code>{a, b, c}</code>.
* </p>
* <p>
* <i>NOTE: This interface violates the {@link Collection} contract.</i>
* The behavior specified in many of these methods is <i>not</i> the same
* as the behavior specified by <code>Collection</code>.
* The noncompliant methods are clearly marked with "(Violation)".
* Exercise caution when using a bag as a <code>Collection</code>.
* </p>
* <p>
* 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<E> extends Collection<E> {
* 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.
* </p>
* <p>
* Since this method always increases the size of the bag,
* according to the {@link Collection#add(Object)} contract, it
* should always return <code>true</code>. Since it sometimes returns
* <code>false</code>, this method violates the contract.
* </p>
*
* @param object the object to add
* @return <code>true</code> if the object was not already in the <code>uniqueSet</code>
@ -78,6 +82,7 @@ public interface Bag<E> extends Collection<E> {
* 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 <code>nCopies</code>.
* </p>
*
* @param object the object to add
* @param nCopies the number of copies to add
@ -90,10 +95,12 @@ public interface Bag<E> extends Collection<E> {
* Removes all occurrences of the given object from the bag.
* <p>
* This will also remove the object from the {@link #uniqueSet()}.
* </p>
* <p>
* According to the {@link Collection#remove(Object)} method,
* this method should only remove the <i>first</i> occurrence of the
* given object, not <i>all</i> occurrences.
* </p>
*
* @param object the object to remove
* @return <code>true</code> if this call changed the collection
@ -106,6 +113,7 @@ public interface Bag<E> extends Collection<E> {
* <p>
* If the number of copies to remove is greater than the actual number of
* copies in the Bag, no error is thrown.
* </p>
*
* @param object the object to remove
* @param nCopies the number of copies to remove
@ -117,6 +125,7 @@ public interface Bag<E> extends Collection<E> {
* Returns a {@link Set} of unique elements in the Bag.
* <p>
* Uniqueness constraints are the same as those in {@link java.util.Set}.
* </p>
*
* @return the Set of unique Bag elements
*/
@ -137,11 +146,13 @@ public interface Bag<E> extends Collection<E> {
* given collection <code>coll</code> contains <code>n</code> copies
* of a given object, calling {@link #getCount(Object)} on that object must
* be <code>&gt;= n</code> for all <code>n</code> in <code>coll</code>.
*
* <p>
* The {@link Collection#containsAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* return true if the bag contains at least one of every object contained
* in the given collection.
* </p>
*
* @param coll the collection to check against
* @return <code>true</code> if the Bag contains all the collection
@ -157,10 +168,12 @@ public interface Bag<E> extends Collection<E> {
* the bag will have <code>n</code> fewer copies, assuming the bag
* had at least <code>n</code> copies to begin with.
*
* <p>The {@link Collection#removeAll(Collection)} method specifies
* <p>
* The {@link Collection#removeAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* remove <i>all</i> occurrences of every object contained in the
* given collection.
* </p>
*
* @param coll the collection to remove
* @return <code>true</code> if this call changed the collection
@ -179,10 +192,12 @@ public interface Bag<E> extends Collection<E> {
* <code>!coll.contains(e)</code>, then remove <code>e</code> and any
* of its copies.
*
* <p>The {@link Collection#retainAll(Collection)} method specifies
* <p>
* The {@link Collection#retainAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* keep <i>all</i> occurrences of every object contained in the
* given collection.
* </p>
*
* @param coll the collection to retain
* @return <code>true</code> if this call changed the collection

8
src/main/java/org/apache/commons/collections4/BagUtils.java
View File

@ -61,6 +61,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
* </p>
*
* <pre>
* 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.
* </p>
*
* @param <E> 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.
* </p>
* <p>
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see {@link TransformedBag#transformedBag(Bag, Transformer)}.
* </p>
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
@ -157,6 +161,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
* </p>
*
* <pre>
* 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.
* </p>
*
* @param <E> 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.
* </p>
* <p>
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see
* {@link TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)}.
* </p>
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null

10
src/main/java/org/apache/commons/collections4/BidiMap.java
View File

@ -26,14 +26,17 @@ import java.util.Set;
* This interface extends <code>Map</code> 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 <code>BidiMap</code>.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
*
* @param <K> the type of the keys in the map
* @param <V> the type of the values in the map
@ -48,6 +51,7 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* 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.
* </p>
* <pre>
* BidiMap map1 = new DualHashBidiMap();
* map.put("A","B"); // contains A mapped to B, as per Map
@ -76,10 +80,12 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
/**
* Gets the key that is currently mapped to the specified value.
* <p>
* </p>
* If the value is not contained in the map, <code>null</code> is returned.
* <p>
* Implementations should seek to make this method perform equally as well
* as <code>get(Object)</code>.
* </p>
*
* @param value the value to find the key for
* @return the mapped key, or <code>null</code> if not found
@ -96,9 +102,11 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* value (optional operation).
* <p>
* If the value is not contained in the map, <code>null</code> is returned.
* </p>
* <p>
* Implementations should seek to make this method perform equally as well
* as <code>remove(Object)</code>.
* </p>
*
* @param value the value to find the key-value pair for
* @return the key that was removed, <code>null</code> if nothing removed
@ -117,10 +125,12 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* <p>
* 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 <code>Map</code>.
* </p>
* <p>
* Implementations should seek to avoid creating a new object every time this
* method is called. See <code>AbstractMap.values()</code> etc. Calling this
* method on the inverse map should return the original.
* </p>
*
* @return an inverted bidirectional map
*/

6
src/main/java/org/apache/commons/collections4/ComparatorUtils.java
View File

@ -34,6 +34,7 @@ import org.apache.commons.collections4.comparators.TransformingComparator;
* <code>comparators</code> package. This class merely provides a
* convenient central place if you have use for more than one class
* in the <code>comparators</code> subpackage.
* </p>
*
* @since 2.1
*/
@ -119,8 +120,10 @@ public class ComparatorUtils {
* Gets a Comparator that can sort Boolean objects.
* <p>
* The parameter specifies whether true or false is sorted first.
* </p>
* <p>
* The comparator throws NullPointerException if a null value is compared.
* </p>
*
* @param trueFirst when <code>true</code>, sort
* <code>true</code> {@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.
* </p>
*
* @param <E> 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.
* </p>
*
* @param <E> 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.
* </p>
*
* @param <I> the input object type of the transformed comparator
* @param <O> the object type of the decorated comparator