Add missing javadoc for generic type, rearrange order of javadoc tags, remove deprecation -> see COLLECTIONS-251.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1436345 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/collections/PredicateUtils.java

@@ -85,9 +85,9 @@ public class PredicateUtils {
      * Gets a Predicate that always throws an exception.
      * This could be useful during testing as a placeholder.
      *
-     * @see org.apache.commons.collections.functors.ExceptionPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
+     * @see org.apache.commons.collections.functors.ExceptionPredicate
      */
     public static <T> Predicate<T> exceptionPredicate() {
         return ExceptionPredicate.<T>exceptionPredicate();
@@ -96,12 +96,10 @@ public class PredicateUtils {
     /**
      * Gets a Predicate that always returns true.
      *
-     * @see org.apache.commons.collections.functors.TruePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
-     * @deprecated use {@link TruePredicate#truePredicate()} instead.
+     * @see org.apache.commons.collections.functors.TruePredicate
      */
-    @Deprecated
     public static <T> Predicate<T> truePredicate() {
         return TruePredicate.truePredicate();
     }
@@ -109,12 +107,10 @@ public class PredicateUtils {
     /**
      * Gets a Predicate that always returns false.
      *
-     * @see org.apache.commons.collections.functors.FalsePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
-     * @deprecated use {@link FalsePredicate#falsePredicate()} instead.
+     * @see org.apache.commons.collections.functors.FalsePredicate
      */
-    @Deprecated
     public static <T> Predicate<T> falsePredicate() {
         return FalsePredicate.<T> falsePredicate();
     }
@@ -122,12 +118,10 @@ public class PredicateUtils {
     /**
      * Gets a Predicate that checks if the input object passed in is null.
      *
-     * @see org.apache.commons.collections.functors.NullPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
-     * @deprecated use {@link NullPredicate#nullPredicate()} instead
+     * @see org.apache.commons.collections.functors.NullPredicate
      */
-    @Deprecated
     public static <T> Predicate<T> nullPredicate() {
         return NullPredicate.nullPredicate();
     }
@@ -135,9 +129,9 @@ public class PredicateUtils {
     /**
      * Gets a Predicate that checks if the input object passed in is not null.
      *
-     * @see org.apache.commons.collections.functors.NotNullPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
+     * @see org.apache.commons.collections.functors.NotNullPredicate
      */
     public static <T> Predicate<T> notNullPredicate() {
         return NotNullPredicate.<T>notNullPredicate();
@@ -147,13 +141,11 @@ public class PredicateUtils {
      * Creates a Predicate that checks if the input object is equal to the
      * specified object using equals().
      *
-     * @see org.apache.commons.collections.functors.EqualPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param value  the value to compare against
      * @return the predicate
-     * @deprecated use {@link EqualPredicate#equalPredicate(Object)} instead.
+     * @see org.apache.commons.collections.functors.EqualPredicate
      */
-    @Deprecated
     public static <T> Predicate<T> equalPredicate(final T value) {
         return EqualPredicate.equalPredicate(value);
     }
@@ -162,10 +154,10 @@ public class PredicateUtils {
      * Creates a Predicate that checks if the input object is equal to the
      * specified object by identity.
      *
-     * @see org.apache.commons.collections.functors.IdentityPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param value  the value to compare against
      * @return the predicate
+     * @see org.apache.commons.collections.functors.IdentityPredicate
      */
     public static <T> Predicate<T> identityPredicate(final T value) {
         return IdentityPredicate.<T>identityPredicate(value);
@@ -176,11 +168,10 @@ public class PredicateUtils {
      * a particular type, using instanceof. A <code>null</code> input
      * object will return <code>false</code>.
      *
-     * @see org.apache.commons.collections.functors.InstanceofPredicate
-     *
      * @param type  the type to check for, may not be null
      * @return the predicate
      * @throws IllegalArgumentException if the class is null
+     * @see org.apache.commons.collections.functors.InstanceofPredicate
      */
     public static Predicate<Object> instanceofPredicate(final Class<?> type) {
         return InstanceofPredicate.instanceOfPredicate(type);
@@ -193,9 +184,9 @@ public class PredicateUtils {
      * is accepted and will return true the first time, and false subsequently
      * as well.
      *
-     * @see org.apache.commons.collections.functors.UniquePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @return the predicate
+     * @see org.apache.commons.collections.functors.UniquePredicate
      */
     public static <T> Predicate<T> uniquePredicate() {
         // must return new instance each time
@@ -212,14 +203,14 @@ public class PredicateUtils {
      * will call the <code>isEmpty</code> method on the input object to
      * determine the predicate result.
      *
-     * @see org.apache.commons.collections.functors.InvokerTransformer
+     * @param <T>  the type that the predicate queries
-     * @see org.apache.commons.collections.functors.TransformerPredicate
-     *
      * @param methodName  the method name to call on the input object, may not be null
      * @return the predicate
      * @throws IllegalArgumentException if the methodName is null.
+     * @see org.apache.commons.collections.functors.InvokerTransformer
+     * @see org.apache.commons.collections.functors.TransformerPredicate
      */
-    public static <T> Predicate<T> invokerPredicate(final String methodName){
+    public static <T> Predicate<T> invokerPredicate(final String methodName) {
         // reuse transformer as it has caching - this is lazy really, should have inner class here
         return asPredicate(InvokerTransformer.<Object, Boolean>invokerTransformer(methodName));
     }
@@ -234,15 +225,15 @@ public class PredicateUtils {
      * will call the <code>isEmpty</code> method on the input object to
      * determine the predicate result.
      *
-     * @see org.apache.commons.collections.functors.InvokerTransformer
+     * @param <T>  the type that the predicate queries
-     * @see org.apache.commons.collections.functors.TransformerPredicate
-     *
      * @param methodName  the method name to call on the input object, may not be null
      * @param paramTypes  the parameter types
      * @param args  the arguments
      * @return the predicate
      * @throws IllegalArgumentException if the method name is null
      * @throws IllegalArgumentException if the paramTypes and args don't match
+     * @see org.apache.commons.collections.functors.InvokerTransformer
+     * @see org.apache.commons.collections.functors.TransformerPredicate
      */
     public static <T> Predicate<T> invokerPredicate(final String methodName, final Class<?>[] paramTypes,
                                                     final Object[] args) {
@@ -257,12 +248,12 @@ public class PredicateUtils {
      * Create a new Predicate that returns true only if both of the specified
      * predicates are true.
      *
-     * @see org.apache.commons.collections.functors.AndPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate1  the first predicate, may not be null
      * @param predicate2  the second predicate, may not be null
      * @return the <code>and</code> predicate
      * @throws IllegalArgumentException if either predicate is null
+     * @see org.apache.commons.collections.functors.AndPredicate
      */
     public static <T> Predicate<T> andPredicate(final Predicate<? super T> predicate1,
                                                 final Predicate<? super T> predicate2) {
@@ -274,15 +265,13 @@ public class PredicateUtils {
      * predicates are true.
      * If the array of predicates is empty, then this predicate returns true.
      *
-     * @see org.apache.commons.collections.functors.AllPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  an array of predicates to check, may not be null
      * @return the <code>all</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
      * @throws IllegalArgumentException if any predicate in the array is null
-     * @deprecated use {@link AllPredicate#allPredicate(Predicate...)} instead.
+     * @see org.apache.commons.collections.functors.AllPredicate
      */
-    @Deprecated
     public static <T> Predicate<T> allPredicate(final Predicate<? super T>... predicates) {
         return AllPredicate.allPredicate(predicates);
     }
@@ -292,12 +281,12 @@ public class PredicateUtils {
      * predicates are true. The predicates are checked in iterator order.
      * If the collection of predicates is empty, then this predicate returns true.
      *
-     * @see org.apache.commons.collections.functors.AllPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  a collection of predicates to check, may not be null
      * @return the <code>all</code> predicate
      * @throws IllegalArgumentException if the predicates collection is null
      * @throws IllegalArgumentException if any predicate in the collection is null
+     * @see org.apache.commons.collections.functors.AllPredicate
      */
     public static <T> Predicate<T> allPredicate(final Collection<? extends Predicate<T>> predicates) {
         return AllPredicate.allPredicate(predicates);
@@ -307,12 +296,12 @@ public class PredicateUtils {
      * Create a new Predicate that returns true if either of the specified
      * predicates are true.
      *
-     * @see org.apache.commons.collections.functors.OrPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate1  the first predicate, may not be null
      * @param predicate2  the second predicate, may not be null
      * @return the <code>or</code> predicate
      * @throws IllegalArgumentException if either predicate is null
+     * @see org.apache.commons.collections.functors.OrPredicate
      */
     public static <T> Predicate<T> orPredicate(final Predicate<? super T> predicate1,
                                                final Predicate<? super T> predicate2) {
@@ -324,12 +313,12 @@ public class PredicateUtils {
      * predicates are true.
      * If the array of predicates is empty, then this predicate returns false.
      *
-     * @see org.apache.commons.collections.functors.AnyPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  an array of predicates to check, may not be null
      * @return the <code>any</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
      * @throws IllegalArgumentException if any predicate in the array is null
+     * @see org.apache.commons.collections.functors.AnyPredicate
      */
     public static <T> Predicate<T> anyPredicate(final Predicate<? super T>... predicates) {
         return AnyPredicate.anyPredicate(predicates);
@@ -340,12 +329,12 @@ public class PredicateUtils {
      * predicates are true. The predicates are checked in iterator order.
      * If the collection of predicates is empty, then this predicate returns false.
      *
-     * @see org.apache.commons.collections.functors.AnyPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  a collection of predicates to check, may not be null
      * @return the <code>any</code> predicate
      * @throws IllegalArgumentException if the predicates collection is null
      * @throws IllegalArgumentException if any predicate in the collection is null
+     * @see org.apache.commons.collections.functors.AnyPredicate
      */
     public static <T> Predicate<T> anyPredicate(final Collection<? extends Predicate<T>> predicates) {
         return AnyPredicate.anyPredicate(predicates);
@@ -355,18 +344,17 @@ public class PredicateUtils {
      * Create a new Predicate that returns true if one, but not both, of the
      * specified predicates are true. XOR
      *
-     * @see org.apache.commons.collections.functors.OnePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate1  the first predicate, may not be null
      * @param predicate2  the second predicate, may not be null
      * @return the <code>either</code> predicate
      * @throws IllegalArgumentException if either predicate is null
+     * @see org.apache.commons.collections.functors.OnePredicate
      */
     public static <T> Predicate<T> eitherPredicate(final Predicate<? super T> predicate1,
                                                    final Predicate<? super T> predicate2) {
         @SuppressWarnings("unchecked")
-        final
+        final Predicate<T> onePredicate = PredicateUtils.<T>onePredicate(predicate1, predicate2);
-        Predicate<T> onePredicate = PredicateUtils.<T>onePredicate(predicate1, predicate2);
         return onePredicate;
     }
 
@@ -375,12 +363,12 @@ public class PredicateUtils {
      * predicates are true.
      * If the array of predicates is empty, then this predicate returns false.
      *
-     * @see org.apache.commons.collections.functors.OnePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  an array of predicates to check, may not be null
      * @return the <code>one</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
      * @throws IllegalArgumentException if any predicate in the array is null
+     * @see org.apache.commons.collections.functors.OnePredicate
      */
     public static <T> Predicate<T> onePredicate(final Predicate<? super T>... predicates) {
         return OnePredicate.onePredicate(predicates);
@@ -391,12 +379,12 @@ public class PredicateUtils {
      * predicates are true. The predicates are checked in iterator order.
      * If the collection of predicates is empty, then this predicate returns false.
      *
-     * @see org.apache.commons.collections.functors.OnePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  a collection of predicates to check, may not be null
      * @return the <code>one</code> predicate
      * @throws IllegalArgumentException if the predicates collection is null
      * @throws IllegalArgumentException if any predicate in the collection is null
+     * @see org.apache.commons.collections.functors.OnePredicate
      */
     public static <T> Predicate<T> onePredicate(final Collection<Predicate<T>> predicates) {
         return OnePredicate.onePredicate(predicates);
@@ -406,18 +394,17 @@ public class PredicateUtils {
      * Create a new Predicate that returns true if neither of the specified
      * predicates are true.
      *
-     * @see org.apache.commons.collections.functors.NonePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate1  the first predicate, may not be null
      * @param predicate2  the second predicate, may not be null
      * @return the <code>neither</code> predicate
      * @throws IllegalArgumentException if either predicate is null
+     * @see org.apache.commons.collections.functors.NonePredicate
      */
     public static <T> Predicate<T> neitherPredicate(final Predicate<? super T> predicate1,
                                                     final Predicate<? super T> predicate2) {
         @SuppressWarnings("unchecked")
-        final
+        final Predicate<T> nonePredicate = PredicateUtils.<T>nonePredicate(predicate1, predicate2);
-        Predicate<T> nonePredicate = PredicateUtils.<T>nonePredicate(predicate1, predicate2);
         return nonePredicate;
     }
 
@@ -426,12 +413,12 @@ public class PredicateUtils {
      * predicates are true.
      * If the array of predicates is empty, then this predicate returns true.
      *
-     * @see org.apache.commons.collections.functors.NonePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  an array of predicates to check, may not be null
      * @return the <code>none</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
      * @throws IllegalArgumentException if any predicate in the array is null
+     * @see org.apache.commons.collections.functors.NonePredicate
      */
     public static <T> Predicate<T> nonePredicate(final Predicate<? super T>... predicates) {
         return NonePredicate.nonePredicate(predicates);
@@ -442,12 +429,12 @@ public class PredicateUtils {
      * predicates are true. The predicates are checked in iterator order.
      * If the collection of predicates is empty, then this predicate returns true.
      *
-     * @see org.apache.commons.collections.functors.NonePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicates  a collection of predicates to check, may not be null
      * @return the <code>none</code> predicate
      * @throws IllegalArgumentException if the predicates collection is null
      * @throws IllegalArgumentException if any predicate in the collection is null
+     * @see org.apache.commons.collections.functors.NonePredicate
      */
     public static <T> Predicate<T> nonePredicate(final Collection<? extends Predicate<T>> predicates) {
         return NonePredicate.nonePredicate(predicates);
@@ -457,11 +444,11 @@ public class PredicateUtils {
      * Create a new Predicate that returns true if the specified predicate
      * returns false and vice versa.
      *
-     * @see org.apache.commons.collections.functors.NotPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate  the predicate to not
      * @return the <code>not</code> predicate
      * @throws IllegalArgumentException if the predicate is null
+     * @see org.apache.commons.collections.functors.NotPredicate
      */
     public static <T> Predicate<T> notPredicate(final Predicate<? super T> predicate) {
         return NotPredicate.notPredicate(predicate);
@@ -475,11 +462,11 @@ public class PredicateUtils {
      * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException
      * will be thrown.
      *
-     * @see org.apache.commons.collections.functors.TransformerPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param transformer  the transformer to wrap, may not be null
      * @return the transformer wrapping predicate
      * @throws IllegalArgumentException if the transformer is null
+     * @see org.apache.commons.collections.functors.TransformerPredicate
      */
     public static <T> Predicate<T> asPredicate(final Transformer<? super T, Boolean> transformer) {
         return TransformerPredicate.transformerPredicate(transformer);
@@ -493,11 +480,11 @@ public class PredicateUtils {
      * otherwise it calls the specified Predicate. This allows null handling
      * behaviour to be added to Predicates that don't support nulls.
      *
-     * @see org.apache.commons.collections.functors.NullIsExceptionPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate  the predicate to wrap, may not be null
      * @return the predicate
      * @throws IllegalArgumentException if the predicate is null.
+     * @see org.apache.commons.collections.functors.NullIsExceptionPredicate
      */
     public static <T> Predicate<T> nullIsExceptionPredicate(final Predicate<? super T> predicate){
         return NullIsExceptionPredicate.nullIsExceptionPredicate(predicate);
@@ -508,11 +495,11 @@ public class PredicateUtils {
      * it calls the specified Predicate. This allows null handling behaviour to
      * be added to Predicates that don't support nulls.
      *
-     * @see org.apache.commons.collections.functors.NullIsFalsePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate  the predicate to wrap, may not be null
      * @return the predicate
      * @throws IllegalArgumentException if the predicate is null.
+     * @see org.apache.commons.collections.functors.NullIsFalsePredicate
      */
     public static <T> Predicate<T> nullIsFalsePredicate(final Predicate<? super T> predicate){
         return NullIsFalsePredicate.nullIsFalsePredicate(predicate);
@@ -523,11 +510,11 @@ public class PredicateUtils {
      * it calls the specified Predicate. This allows null handling behaviour to
      * be added to Predicates that don't support nulls.
      *
-     * @see org.apache.commons.collections.functors.NullIsTruePredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param predicate  the predicate to wrap, may not be null
      * @return the predicate
      * @throws IllegalArgumentException if the predicate is null.
+     * @see org.apache.commons.collections.functors.NullIsTruePredicate
      */
     public static <T> Predicate<T> nullIsTruePredicate(final Predicate<? super T> predicate){
         return NullIsTruePredicate.nullIsTruePredicate(predicate);
@@ -539,12 +526,12 @@ public class PredicateUtils {
      * Creates a predicate that transforms the input object before passing it
      * to the predicate.
      *
-     * @see org.apache.commons.collections.functors.TransformedPredicate
+     * @param <T>  the type that the predicate queries
-     *
      * @param transformer  the transformer to call first
      * @param predicate  the predicate to call with the result of the transform
      * @return the predicate
      * @throws IllegalArgumentException if the transformer or the predicate is null
+     * @see org.apache.commons.collections.functors.TransformedPredicate
      * @since 3.1
      */
     public static <T> Predicate<T> transformedPredicate(