org.apache.commons.collections4

Class PredicateUtils


  • public class PredicateUtils
extends Object
    PredicateUtils provides reference implementations and utilities for the Predicate functor interface. The supplied predicates are:
    • Invoker - returns the result of a method call on the input object
    • InstanceOf - true if the object is an instanceof a class
    • Equal - true if the object equals() a specified object
    • Identity - true if the object == a specified object
    • Null - true if the object is null
    • NotNull - true if the object is not null
    • Unique - true if the object has not already been evaluated
    • And/All - true if all of the predicates are true
    • Or/Any - true if any of the predicates is true
    • Either/One - true if only one of the predicate is true
    • Neither/None - true if none of the predicates are true
    • Not - true if the predicate is false, and vice versa
    • Transformer - wraps a Transformer as a Predicate
    • True - always return true
    • False - always return false
    • Exception - always throws an exception
    • NullIsException/NullIsFalse/NullIsTrue - check for null input
    • Transformed - transforms the input before calling the predicate
    All the supplied predicates are Serializable.
    Since:
    3.0

    • Method Detail

      • exceptionPredicate

        public static <T> Predicate<T> exceptionPredicate()
        Gets a Predicate that always throws an exception. This could be useful during testing as a placeholder.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        ExceptionPredicate

      • truePredicate

        public static <T> Predicate<T> truePredicate()
        Gets a Predicate that always returns true.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        TruePredicate

      • falsePredicate

        public static <T> Predicate<T> falsePredicate()
        Gets a Predicate that always returns false.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        FalsePredicate

      • nullPredicate

        public static <T> Predicate<T> nullPredicate()
        Gets a Predicate that checks if the input object passed in is null.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        NullPredicate

      • notNullPredicate

        public static <T> Predicate<T> notNullPredicate()
        Gets a Predicate that checks if the input object passed in is not null.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        NotNullPredicate

      • equalPredicate

        public static <T> Predicate<T> equalPredicate(T value)
        Creates a Predicate that checks if the input object is equal to the specified object using equals().
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        value - the value to compare against
        Returns:
        the predicate
        See Also:
        EqualPredicate

      • identityPredicate

        public static <T> Predicate<T> identityPredicate(T value)
        Creates a Predicate that checks if the input object is equal to the specified object by identity.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        value - the value to compare against
        Returns:
        the predicate
        See Also:
        IdentityPredicate

      • instanceofPredicate

        public static Predicate<Object> instanceofPredicate(Class<?> type)
        Creates a Predicate that checks if the object passed in is of a particular type, using instanceof. A null input object will return false.
        Parameters:
        type - the type to check for, may not be null
        Returns:
        the predicate
        Throws:
        NullPointerException - if the class is null
        See Also:
        InstanceofPredicate

      • uniquePredicate

        public static <T> Predicate<T> uniquePredicate()
        Creates a Predicate that returns true the first time an object is encountered, and false if the same object is received again. The comparison is by equals(). A null input object is accepted and will return true the first time, and false subsequently as well.
        Type Parameters:
        T - the type that the predicate queries
        Returns:
        the predicate
        See Also:
        UniquePredicate

      • invokerPredicate

        public static <T> Predicate<T> invokerPredicate(String methodName)
        Creates a Predicate that invokes a method on the input object. The method must return either a boolean or a non-null Boolean, and have no parameters. If the input object is null, a PredicateException is thrown.

        For example, PredicateUtils.invokerPredicate("isEmpty"); will call the isEmpty method on the input object to determine the predicate result.

        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        methodName - the method name to call on the input object, may not be null
        Returns:
        the predicate
        Throws:
        NullPointerException - if the methodName is null.
        See Also:
        InvokerTransformer, TransformerPredicate

      • invokerPredicate

        public static <T> Predicate<T> invokerPredicate(String methodName,
                                                Class<?>[] paramTypes,
                                                Object[] args)
        Creates a Predicate that invokes a method on the input object. The method must return either a boolean or a non-null Boolean, and have no parameters. If the input object is null, a PredicateException is thrown.

        For example, PredicateUtils.invokerPredicate("isEmpty"); will call the isEmpty method on the input object to determine the predicate result.

        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        methodName - the method name to call on the input object, may not be null
        paramTypes - the parameter types
        args - the arguments
        Returns:
        the predicate
        Throws:
        NullPointerException - if the method name is null
        IllegalArgumentException - if the paramTypes and args don't match
        See Also:
        InvokerTransformer, TransformerPredicate

      • andPredicate

        public static <T> Predicate<T> andPredicate(Predicate<? super T> predicate1,
                                            Predicate<? super T> predicate2)
        Create a new Predicate that returns true only if both of the specified predicates are true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate1 - the first predicate, may not be null
        predicate2 - the second predicate, may not be null
        Returns:
        the and predicate
        Throws:
        NullPointerException - if either predicate is null
        See Also:
        AndPredicate

      • allPredicate

        public static <T> Predicate<T> allPredicate(Predicate<? super T>... predicates)
        Create a new Predicate that returns true only if all of the specified predicates are true. If the array of predicates is empty, then this predicate returns true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - an array of predicates to check, may not be null
        Returns:
        the all predicate
        Throws:
        NullPointerException - if the predicates array is null
        NullPointerException - if any predicate in the array is null
        See Also:
        AllPredicate

      • allPredicate

        public static <T> Predicate<T> allPredicate(Collection<? extends Predicate<? super T>> predicates)
        Create a new Predicate that returns true only if all of the specified predicates are true. The predicates are checked in iterator order. If the collection of predicates is empty, then this predicate returns true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - a collection of predicates to check, may not be null
        Returns:
        the all predicate
        Throws:
        NullPointerException - if the predicates collection is null
        NullPointerException - if any predicate in the collection is null
        See Also:
        AllPredicate

      • orPredicate

        public static <T> Predicate<T> orPredicate(Predicate<? super T> predicate1,
                                           Predicate<? super T> predicate2)
        Create a new Predicate that returns true if either of the specified predicates are true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate1 - the first predicate, may not be null
        predicate2 - the second predicate, may not be null
        Returns:
        the or predicate
        Throws:
        NullPointerException - if either predicate is null
        See Also:
        OrPredicate

      • anyPredicate

        public static <T> Predicate<T> anyPredicate(Predicate<? super T>... predicates)
        Create a new Predicate that returns true if any of the specified predicates are true. If the array of predicates is empty, then this predicate returns false.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - an array of predicates to check, may not be null
        Returns:
        the any predicate
        Throws:
        NullPointerException - if the predicates array is null
        NullPointerException - if any predicate in the array is null
        See Also:
        AnyPredicate

      • anyPredicate

        public static <T> Predicate<T> anyPredicate(Collection<? extends Predicate<? super T>> predicates)
        Create a new Predicate that returns true if any of the specified predicates are true. The predicates are checked in iterator order. If the collection of predicates is empty, then this predicate returns false.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - a collection of predicates to check, may not be null
        Returns:
        the any predicate
        Throws:
        NullPointerException - if the predicates collection is null
        NullPointerException - if any predicate in the collection is null
        See Also:
        AnyPredicate

      • eitherPredicate

        public static <T> Predicate<T> eitherPredicate(Predicate<? super T> predicate1,
                                               Predicate<? super T> predicate2)
        Create a new Predicate that returns true if one, but not both, of the specified predicates are true. XOR
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate1 - the first predicate, may not be null
        predicate2 - the second predicate, may not be null
        Returns:
        the either predicate
        Throws:
        NullPointerException - if either predicate is null
        See Also:
        OnePredicate

      • onePredicate

        public static <T> Predicate<T> onePredicate(Predicate<? super T>... predicates)
        Create a new Predicate that returns true if only one of the specified predicates are true. If the array of predicates is empty, then this predicate returns false.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - an array of predicates to check, may not be null
        Returns:
        the one predicate
        Throws:
        NullPointerException - if the predicates array is null
        NullPointerException - if any predicate in the array is null
        See Also:
        OnePredicate

      • onePredicate

        public static <T> Predicate<T> onePredicate(Collection<? extends Predicate<? super T>> predicates)
        Create a new Predicate that returns true if only one of the specified predicates are true. The predicates are checked in iterator order. If the collection of predicates is empty, then this predicate returns false.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - a collection of predicates to check, may not be null
        Returns:
        the one predicate
        Throws:
        NullPointerException - if the predicates collection is null
        NullPointerException - if any predicate in the collection is null
        See Also:
        OnePredicate

      • neitherPredicate

        public static <T> Predicate<T> neitherPredicate(Predicate<? super T> predicate1,
                                                Predicate<? super T> predicate2)
        Create a new Predicate that returns true if neither of the specified predicates are true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate1 - the first predicate, may not be null
        predicate2 - the second predicate, may not be null
        Returns:
        the neither predicate
        Throws:
        NullPointerException - if either predicate is null
        See Also:
        NonePredicate

      • nonePredicate

        public static <T> Predicate<T> nonePredicate(Predicate<? super T>... predicates)
        Create a new Predicate that returns true if none of the specified predicates are true. If the array of predicates is empty, then this predicate returns true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - an array of predicates to check, may not be null
        Returns:
        the none predicate
        Throws:
        NullPointerException - if the predicates array is null
        NullPointerException - if any predicate in the array is null
        See Also:
        NonePredicate

      • nonePredicate

        public static <T> Predicate<T> nonePredicate(Collection<? extends Predicate<? super T>> predicates)
        Create a new Predicate that returns true if none of the specified predicates are true. The predicates are checked in iterator order. If the collection of predicates is empty, then this predicate returns true.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicates - a collection of predicates to check, may not be null
        Returns:
        the none predicate
        Throws:
        NullPointerException - if the predicates collection is null
        NullPointerException - if any predicate in the collection is null
        See Also:
        NonePredicate

      • notPredicate

        public static <T> Predicate<T> notPredicate(Predicate<? super T> predicate)
        Create a new Predicate that returns true if the specified predicate returns false and vice versa.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate - the predicate to not
        Returns:
        the not predicate
        Throws:
        NullPointerException - if the predicate is null
        See Also:
        NotPredicate

      • asPredicate

        public static <T> Predicate<T> asPredicate(Transformer<? super T,Boolean> transformer)
        Create a new Predicate that wraps a Transformer. The Transformer must return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException will be thrown.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        transformer - the transformer to wrap, may not be null
        Returns:
        the transformer wrapping predicate
        Throws:
        NullPointerException - if the transformer is null
        See Also:
        TransformerPredicate

      • nullIsExceptionPredicate

        public static <T> Predicate<T> nullIsExceptionPredicate(Predicate<? super T> predicate)
        Gets a Predicate that throws an exception if the input object is null, otherwise it calls the specified Predicate. This allows null handling behaviour to be added to Predicates that don't support nulls.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate - the predicate to wrap, may not be null
        Returns:
        the predicate
        Throws:
        NullPointerException - if the predicate is null.
        See Also:
        NullIsExceptionPredicate

      • nullIsFalsePredicate

        public static <T> Predicate<T> nullIsFalsePredicate(Predicate<? super T> predicate)
        Gets a Predicate that returns false if the input object is null, otherwise it calls the specified Predicate. This allows null handling behaviour to be added to Predicates that don't support nulls.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate - the predicate to wrap, may not be null
        Returns:
        the predicate
        Throws:
        NullPointerException - if the predicate is null.
        See Also:
        NullIsFalsePredicate

      • nullIsTruePredicate

        public static <T> Predicate<T> nullIsTruePredicate(Predicate<? super T> predicate)
        Gets a Predicate that returns true if the input object is null, otherwise it calls the specified Predicate. This allows null handling behaviour to be added to Predicates that don't support nulls.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        predicate - the predicate to wrap, may not be null
        Returns:
        the predicate
        Throws:
        NullPointerException - if the predicate is null.
        See Also:
        NullIsTruePredicate

      • transformedPredicate

        public static <T> Predicate<T> transformedPredicate(Transformer<? super T,? extends T> transformer,
                                                    Predicate<? super T> predicate)
        Creates a predicate that transforms the input object before passing it to the predicate.
        Type Parameters:
        T - the type that the predicate queries
        Parameters:
        transformer - the transformer to call first
        predicate - the predicate to call with the result of the transform
        Returns:
        the predicate
        Throws:
        NullPointerException - if the transformer or the predicate is null
        Since:
        3.1
        See Also:
        TransformedPredicate