From f99ac98da4f1cbe2710348ebcc5645c5364e6d27 Mon Sep 17 00:00:00 2001 From: Thomas Neidhart Date: Mon, 21 Jan 2013 14:14:46 +0000 Subject: [PATCH] Complete javadoc, minor formatting. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1436360 13f79535-47bb-0310-9956-ffa450edef68 --- .../commons/collections/CollectionUtils.java | 178 +++++++++--------- 1 file changed, 85 insertions(+), 93 deletions(-) diff --git a/src/main/java/org/apache/commons/collections/CollectionUtils.java b/src/main/java/org/apache/commons/collections/CollectionUtils.java index de44835af..eb6d42aee 100644 --- a/src/main/java/org/apache/commons/collections/CollectionUtils.java +++ b/src/main/java/org/apache/commons/collections/CollectionUtils.java @@ -453,6 +453,7 @@ public class CollectionUtils { * If the input collection or predicate is null, or no element of the collection * matches the predicate, null is returned. * + * @param the type of object the {@link Collection} contains * @param collection the collection to search, may be null * @param predicate the predicate to use, may be null * @return the first element of the collection which matches the predicate or null if none could be found @@ -473,10 +474,10 @@ public class CollectionUtils { *

* If the input collection or closure is null, there is no change made. * - * @param collection - * the collection to get the input from, may be null - * @param closure - * the closure to perform, may be null + * @param the type of object the {@link Collection} contains + * @param the closure type + * @param collection the collection to get the input from, may be null + * @param closure the closure to perform, may be null * @return closure */ public static > C forAllDo(final Collection collection, final C closure) { @@ -493,10 +494,10 @@ public class CollectionUtils { *

* If the input collection or closure is null, there is no change made. * - * @param iterator - * the iterator to get the input from, may be null - * @param closure - * the closure to perform, may be null + * @param the type of object the {@link Iterator} contains + * @param the closure type + * @param iterator the iterator to get the input from, may be null + * @param closure the closure to perform, may be null * @return closure * @since 4.0 */ @@ -514,11 +515,10 @@ public class CollectionUtils { * predicate returns false, remove the element. *

* If the input collection or predicate is null, there is no change made. - * - * @param collection - * the collection to get the input from, may be null - * @param predicate - * the predicate to use as a filter, may be null + * + * @param the type of object the {@link Iterable} contains + * @param collection the collection to get the input from, may be null + * @param predicate the predicate to use as a filter, may be null * @return true if the collection is modified by this call, false otherwise. */ public static boolean filter(final Iterable collection, final Predicate predicate) { @@ -547,13 +547,13 @@ public class CollectionUtils { * Transformer creates duplicates (or are otherwise invalid), the collection * may reduce in size due to calling this method. * - * @param collection - * the {@link Iterable} to get the input from, may be null - * @param transformer - * the transformer to perform, may be null + * @param the type of object the {@link Collection} contains + * @param collection the {@link Iterable} to get the input from, may be null + * @param transformer the transformer to perform, may be null */ public static void transform(final Collection collection, final Transformer transformer) { + if (collection != null && transformer != null) { if (collection instanceof List) { final List list = (List) collection; @@ -574,10 +574,9 @@ public class CollectionUtils { *

* A null collection or predicate matches no elements. * - * @param input - * the {@link Iterable} to get the input from, may be null - * @param predicate - * the predicate to use, may be null + * @param the type of object the {@link Iterable} contains + * @param input the {@link Iterable} to get the input from, may be null + * @param predicate the predicate to use, may be null * @return the number of matches for the predicate in the collection */ public static int countMatches(final Iterable input, final Predicate predicate) { @@ -598,12 +597,10 @@ public class CollectionUtils { *

* A null collection or predicate returns false. * - * @param input - * the {@link Iterable} to get the input from, may be null - * @param predicate - * the predicate to use, may be null - * @return true if at least one element of the collection matches the - * predicate + * @param the type of object the {@link Iterable} contains + * @param input the {@link Iterable} to get the input from, may be null + * @param predicate the predicate to use, may be null + * @return true if at least one element of the collection matches the predicate */ public static boolean exists(final Iterable input, final Predicate predicate) { if (input != null && predicate != null) { @@ -622,13 +619,11 @@ public class CollectionUtils { *

* A null predicate matches no elements. * - * @param inputCollection - * the collection to get the input from, may not be null - * @param predicate - * the predicate to use, may be null + * @param the type of object the {@link Collection} contains + * @param inputCollection the collection to get the input from, may not be null + * @param predicate the predicate to use, may be null * @return the elements matching the predicate (new list) - * @throws NullPointerException - * if the input collection is null + * @throws NullPointerException if the input collection is null */ public static Collection select(final Collection inputCollection, final Predicate predicate) { @@ -642,17 +637,17 @@ public class CollectionUtils { * If the input collection or predicate is null, there is no change to the * output collection. * - * @param inputCollection - * the collection to get the input from, may be null - * @param predicate - * the predicate to use, may be null - * @param outputCollection - * the collection to output into, may not be null if the inputCollection - * and predicate or not null + * @param the type of object the {@link Collection} contains + * @param the type of the output {@link Collection} + * @param inputCollection the collection to get the input from, may be null + * @param predicate the predicate to use, may be null + * @param outputCollection the collection to output into, may not be null if the inputCollection + * and predicate or not null * @return the outputCollection */ public static > R select(final Collection inputCollection, final Predicate predicate, final R outputCollection) { + if (inputCollection != null && predicate != null) { for (final O item : inputCollection) { if (predicate.evaluate(item)) { @@ -670,13 +665,11 @@ public class CollectionUtils { * If the input predicate is null, the result is an empty * list. * - * @param inputCollection - * the collection to get the input from, may not be null - * @param predicate - * the predicate to use, may be null + * @param the type of object the {@link Collection} contains + * @param inputCollection the collection to get the input from, may not be null + * @param predicate the predicate to use, may be null * @return the elements not matching the predicate (new list) - * @throws NullPointerException - * if the input collection is null + * @throws NullPointerException if the input collection is null */ public static Collection selectRejected(final Collection inputCollection, final Predicate predicate) { @@ -690,13 +683,12 @@ public class CollectionUtils { * If the input predicate is null, no elements are added to * outputCollection. * - * @param inputCollection - * the collection to get the input from, may be null - * @param predicate - * the predicate to use, may be null - * @param outputCollection - * the collection to output into, may not be null if the inputCollection - * and predicate or not null + * @param the type of object the {@link Collection} contains + * @param the type of the output {@link Collection} + * @param inputCollection the collection to get the input from, may be null + * @param predicate the predicate to use, may be null + * @param outputCollection the collection to output into, may not be null if the inputCollection + * and predicate or not null * @return outputCollection */ public static > R selectRejected(final Collection inputCollection, @@ -718,15 +710,12 @@ public class CollectionUtils { *

* If the input transformer is null, the result is an empty list. * - * @param inputCollection - * the collection to get the input from, may not be null - * @param transformer - * the transformer to use, may be null + * @param inputCollection the collection to get the input from, may not be null + * @param transformer the transformer to use, may be null * @param the type of object in the input collection * @param the type of object in the output collection * @return the transformed result (new list) - * @throws NullPointerException - * if the input collection is null + * @throws NullPointerException if the input collection is null */ public static Collection collect(final Iterable inputCollection, final Transformer transformer) { @@ -742,10 +731,8 @@ public class CollectionUtils { * If the input iterator or transformer is null, the result is an empty * list. * - * @param inputIterator - * the iterator to get the input from, may be null - * @param transformer - * the transformer to use, may be null + * @param inputIterator the iterator to get the input from, may be null + * @param transformer the transformer to use, may be null * @param the type of object in the input collection * @param the type of object in the output collection * @return the transformed result (new list) @@ -818,6 +805,7 @@ public class CollectionUtils { /** * Adds an element to the collection unless the element is null. * + * @param the type of object the {@link Collection} contains * @param collection the collection to add to, must not be null * @param object the object to add, if null it will not be added * @return true if the collection changed @@ -836,13 +824,11 @@ public class CollectionUtils { * {@link Iterable} is a {@link Collection} then it is cast and will be * added using {@link Collection#addAll(Collection)} instead of iterating. * - * @param collection - * the collection to add to, must not be null - * @param iterable - * the iterable of elements to add, must not be null + * @param the type of object the {@link Collection} contains + * @param collection the collection to add to, must not be null + * @param iterable the iterable of elements to add, must not be null * @return a boolean indicating whether the collection has changed or not. - * @throws NullPointerException - * if the collection or iterator is null + * @throws NullPointerException if the collection or iterator is null */ public static boolean addAll(final Collection collection, final Iterable iterable) { if (iterable instanceof Collection) { @@ -854,13 +840,11 @@ public class CollectionUtils { /** * Adds all elements in the iteration to the given collection. * - * @param collection - * the collection to add to, must not be null - * @param iterator - * the iterator of elements to add, must not be null + * @param the type of object the {@link Collection} contains + * @param collection the collection to add to, must not be null + * @param iterator the iterator of elements to add, must not be null * @return a boolean indicating whether the collection has changed or not. - * @throws NullPointerException - * if the collection or iterator is null + * @throws NullPointerException if the collection or iterator is null */ public static boolean addAll(final Collection collection, final Iterator iterator) { boolean changed = false; @@ -873,8 +857,10 @@ public class CollectionUtils { /** * Adds all elements in the enumeration to the given collection. * + * @param the type of object the {@link Collection} contains * @param collection the collection to add to, must not be null * @param enumeration the enumeration of elements to add, must not be null + * @return {@code true} if the collections was changed, {@code false} otherwise * @throws NullPointerException if the collection or enumeration is null */ public static boolean addAll(final Collection collection, final Enumeration enumeration) { @@ -888,12 +874,11 @@ public class CollectionUtils { /** * Adds all elements in the array to the given collection. * - * @param collection - * the collection to add to, must not be null - * @param elements - * the array of elements to add, must not be null - * @throws NullPointerException - * if the collection or array is null + * @param the type of object the {@link Collection} contains + * @param collection the collection to add to, must not be null + * @param elements the array of elements to add, must not be null + * @return {@code true} if the collection was changed, {@code false} otherwise + * @throws NullPointerException if the collection or array is null */ public static boolean addAll(final Collection collection, final C[] elements) { boolean changed = false; @@ -906,9 +891,9 @@ public class CollectionUtils { /** * Returns the index-th value in {@link Iterator}, throwing * IndexOutOfBoundsException if there is no such element. - * The Iterator is advanced to - * index (or to the end, if index exceeds the - * number of entries) as a side effect of this method. + *

+ * The Iterator is advanced to index (or to the end, if + * index exceeds the number of entries) as a side effect of this method. * * @param iterator the iterator to get a value from * @param index the index to get @@ -920,14 +905,14 @@ public class CollectionUtils { public static T get(final Iterator iterator, final int index) { int i = index; checkIndexBounds(i); - while (iterator.hasNext()) { - i--; - if (i == -1) { - return iterator.next(); - } - iterator.next(); + while (iterator.hasNext()) { + i--; + if (i == -1) { + return iterator.next(); } - throw new IndexOutOfBoundsException("Entry does not exist: " + i); + iterator.next(); + } + throw new IndexOutOfBoundsException("Entry does not exist: " + i); } /** @@ -1038,9 +1023,11 @@ public class CollectionUtils { } /** - * Returns the index-th Map.Entry in the map's entrySet, throwing - * IndexOutOfBoundsException if there is no such element. + * Returns the index-th Map.Entry in the map's entrySet, + * throwing IndexOutOfBoundsException if there is no such element. * + * @param the key type in the {@link Map} + * @param the key type in the {@link Map} * @param map the object to get a value from * @param index the index to get * @return the object at the specified index @@ -1261,6 +1248,7 @@ public class CollectionUtils { * case the cardinality is zero. This method is useful if you do not wish to modify * the collection c and thus cannot call c.retainAll(retain);. * + * @param the type of object the {@link Collection} contains * @param collection the collection whose contents are the target of the #retailAll operation * @param retain the collection containing the elements to be retained in the returned collection * @return a Collection containing all the elements of collection @@ -1281,6 +1269,7 @@ public class CollectionUtils { * case the cardinality is zero. This method is useful if you do not wish to modify * the collection c and thus cannot call collection.removeAll(remove);. * + * @param the type of object the {@link Collection} contains * @param collection the collection from which items are removed (in the returned collection) * @param remove the items to be removed from the returned collection * @return a Collection containing all the elements of collection except @@ -1311,6 +1300,7 @@ public class CollectionUtils { * * This method uses the implementation in the decorators subpackage. * + * @param the type of object the {@link Collection} contains * @param collection the collection to synchronize, must not be null * @return a synchronized collection backed by the given collection * @throws IllegalArgumentException if the collection is null @@ -1324,6 +1314,7 @@ public class CollectionUtils { *

* This method uses the implementation in the decorators subpackage. * + * @param the type of object the {@link Collection} contains * @param collection the collection to make unmodifiable, must not be null * @return an unmodifiable collection backed by the given collection * @throws IllegalArgumentException if the collection is null @@ -1361,6 +1352,7 @@ public class CollectionUtils { * Existing entries in the specified collection will not be transformed. * If you want that behaviour, see {@link TransformedCollection#transformedCollection}. * + * @param the type of object the {@link Collection} contains * @param collection the collection to predicate, must not be null * @param transformer the transformer for the collection, must not be null * @return a transformed collection backed by the given collection