org.apache.commons.collections
Class PredicateUtils

java.lang.Object
  org.apache.commons.collections.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:

Commons Collections 3.0

Version:

$Revision: 1.2 $ $Date: 2005/05/23 14:42:13 $

Author:

Stephen Colebourne, Matt Hall, John Watkinson, Ola Berg

Constructor Summary

PredicateUtils()
This class is not normally instantiated.

Method Summary

static <T> Predicate<T>	allPredicate(Collection<Predicate<? super T>> predicates) Create a new Predicate that returns true only if all of the specified predicates are true.
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.
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.
static <T> Predicate<T>	anyPredicate(Collection<Predicate<? super T>> predicates) Create a new Predicate that returns true if any of the specified predicates are true.
static <T> Predicate<T>	anyPredicate(Predicate<? super T>[] predicates) Create a new Predicate that returns true if any of the specified predicates are true.
static <T> Predicate<T>	asPredicate(Transformer<T,Boolean> transformer) Create a new Predicate that wraps a Transformer.
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.
static <T> Predicate<T>	equalPredicate(T value) Creates a Predicate that checks if the input object is equal to the specified object using equals().
static Predicate	exceptionPredicate() Gets a Predicate that always throws an exception.
static Predicate	falsePredicate() Gets a Predicate that always returns false.
static <T> Predicate<T>	identityPredicate(T value) Creates a Predicate that checks if the input object is equal to the specified object by identity.
static <T> Predicate<T>	instanceofPredicate(Class<T> type) Creates a Predicate that checks if the object passed in is of a particular type, using instanceof.
static Predicate	invokerPredicate(String methodName) Creates a Predicate that invokes a method on the input object.
static Predicate	invokerPredicate(String methodName, Class[] paramTypes, Object[] args) Creates a Predicate that invokes a method on the input object.
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.
static <T> Predicate<T>	nonePredicate(Collection<Predicate<? super T>> predicates) Create a new Predicate that returns true if none of the specified predicates are true.
static <T> Predicate<T>	nonePredicate(Predicate<? super T>[] predicates) Create a new Predicate that returns true if none of the specified predicates are true.
static Predicate	notNullPredicate() Gets a Predicate that checks if the input object passed in is not null.
static <T> Predicate<T>	notPredicate(Predicate<T> predicate) Create a new Predicate that returns true if the specified predicate returns false and vice versa.
static <T> Predicate<T>	nullIsExceptionPredicate(Predicate<T> predicate) Gets a Predicate that throws an exception if the input object is null, otherwise it calls the specified Predicate.
static <T> Predicate<T>	nullIsFalsePredicate(Predicate<T> predicate) Gets a Predicate that returns false if the input object is null, otherwise it calls the specified Predicate.
static <T> Predicate<T>	nullIsTruePredicate(Predicate<T> predicate) Gets a Predicate that returns true if the input object is null, otherwise it calls the specified Predicate.
static Predicate	nullPredicate() Gets a Predicate that checks if the input object passed in is null.
static <T> Predicate<T>	onePredicate(Collection<Predicate<? super T>> predicates) Create a new Predicate that returns true if only one of the specified predicates are true.
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.
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.
static <I,O> Predicate<I>	transformedPredicate(Transformer<I,? extends O> transformer, Predicate<? super O> predicate) Creates a predicate that transforms the input object before passing it to the predicate.
static Predicate	truePredicate() Gets a Predicate that always returns true.
static Predicate	uniquePredicate() Creates a Predicate that returns true the first time an object is encountered, and false if the same object is received again.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PredicateUtils

public PredicateUtils()

This class is not normally instantiated.

Method Detail

exceptionPredicate

public static Predicate exceptionPredicate()

Gets a Predicate that always throws an exception. This could be useful during testing as a placeholder.

Returns:

the predicate

See Also:

ExceptionPredicate

truePredicate

public static Predicate truePredicate()

Gets a Predicate that always returns true.

Returns:

the predicate

See Also:

TruePredicate

falsePredicate

public static Predicate falsePredicate()

Gets a Predicate that always returns false.

Returns:

the predicate

See Also:

FalsePredicate

nullPredicate

public static Predicate nullPredicate()

Gets a Predicate that checks if the input object passed in is null.

Returns:

the predicate

See Also:

NullPredicate

notNullPredicate

public static Predicate notNullPredicate()

Gets a Predicate that checks if the input object passed in is not null.

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().

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.

Parameters:

value - the value to compare against

Returns:

the predicate

See Also:

IdentityPredicate

instanceofPredicate

public static <T> Predicate<T> instanceofPredicate(Class<T> 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:

IllegalArgumentException - if the class is null

See Also:

InstanceofPredicate

uniquePredicate

public static Predicate 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.

Returns:

the predicate

See Also:

UniquePredicate

invokerPredicate

public static Predicate 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.

Parameters:

methodName - the method name to call on the input object, may not be null

Returns:

the predicate

Throws:

IllegalArgumentException - if the methodName is null.

See Also:

InvokerTransformer, TransformerPredicate

invokerPredicate

public static Predicate 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.

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:

IllegalArgumentException - 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.

Parameters:

predicate1 - the first predicate, may not be null

predicate2 - the second predicate, may not be null

Returns:

the and predicate

Throws:

IllegalArgumentException - 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.

Parameters:

predicates - an array of predicates to check, may not be null

Returns:

the all predicate

Throws:

IllegalArgumentException - if the predicates array is null

IllegalArgumentException - if the predicates array has less than 2 elements

IllegalArgumentException - if any predicate in the array is null

See Also:

AllPredicate

allPredicate

public static <T> Predicate<T> allPredicate(Collection<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.

Parameters:

predicates - a collection of predicates to check, may not be null

Returns:

the all predicate

Throws:

IllegalArgumentException - if the predicates collection is null

IllegalArgumentException - if the predicates collection has less than 2 elements

IllegalArgumentException - 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.

Parameters:

predicate1 - the first predicate, may not be null

predicate2 - the second predicate, may not be null

Returns:

the or predicate

Throws:

IllegalArgumentException - 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.

Parameters:

predicates - an array of predicates to check, may not be null

Returns:

the any predicate

Throws:

IllegalArgumentException - if the predicates array is null

IllegalArgumentException - if the predicates array has less than 2 elements

IllegalArgumentException - if any predicate in the array is null

See Also:

AnyPredicate

anyPredicate

public static <T> Predicate<T> anyPredicate(Collection<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.

Parameters:

predicates - a collection of predicates to check, may not be null

Returns:

the any predicate

Throws:

IllegalArgumentException - if the predicates collection is null

IllegalArgumentException - if the predicates collection has less than 2 elements

IllegalArgumentException - 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.

Parameters:

predicate1 - the first predicate, may not be null

predicate2 - the second predicate, may not be null

Returns:

the either predicate

Throws:

IllegalArgumentException - 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.

Parameters:

predicates - an array of predicates to check, may not be null

Returns:

the one predicate

Throws:

IllegalArgumentException - if the predicates array is null

IllegalArgumentException - if the predicates array has less than 2 elements

IllegalArgumentException - if any predicate in the array is null

See Also:

OnePredicate

onePredicate

public static <T> Predicate<T> onePredicate(Collection<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.

Parameters:

predicates - a collection of predicates to check, may not be null

Returns:

the one predicate

Throws:

IllegalArgumentException - if the predicates collection is null

IllegalArgumentException - if the predicates collection has less than 2 elements

IllegalArgumentException - 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.

Parameters:

predicate1 - the first predicate, may not be null

predicate2 - the second predicate, may not be null

Returns:

the neither predicate

Throws:

IllegalArgumentException - 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.

Parameters:

predicates - an array of predicates to check, may not be null

Returns:

the none predicate

Throws:

IllegalArgumentException - if the predicates array is null

IllegalArgumentException - if the predicates array has less than 2 elements

IllegalArgumentException - if any predicate in the array is null

See Also:

NonePredicate

nonePredicate

public static <T> Predicate<T> nonePredicate(Collection<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.

Parameters:

predicates - a collection of predicates to check, may not be null

Returns:

the none predicate

Throws:

IllegalArgumentException - if the predicates collection is null

IllegalArgumentException - if the predicates collection has less than 2 elements

IllegalArgumentException - if any predicate in the collection is null

See Also:

NonePredicate

notPredicate

public static <T> Predicate<T> notPredicate(Predicate<T> predicate)

Create a new Predicate that returns true if the specified predicate returns false and vice versa.

Parameters:

predicate - the predicate to not

Returns:

the not predicate

Throws:

IllegalArgumentException - if the predicate is null

See Also:

NotPredicate

asPredicate

public static <T> Predicate<T> asPredicate(Transformer<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.

Parameters:

transformer - the transformer to wrap, may not be null

Returns:

the transformer wrapping predicate

Throws:

IllegalArgumentException - if the transformer is null

See Also:

TransformerPredicate

nullIsExceptionPredicate

public static <T> Predicate<T> nullIsExceptionPredicate(Predicate<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.

Parameters:

predicate - the predicate to wrap, may not be null

Returns:

the predicate

Throws:

IllegalArgumentException - if the predicate is null.

See Also:

NullIsExceptionPredicate

nullIsFalsePredicate

public static <T> Predicate<T> nullIsFalsePredicate(Predicate<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.

Parameters:

predicate - the predicate to wrap, may not be null

Returns:

the predicate

Throws:

IllegalArgumentException - if the predicate is null.

See Also:

NullIsFalsePredicate

nullIsTruePredicate

public static <T> Predicate<T> nullIsTruePredicate(Predicate<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.

Parameters:

predicate - the predicate to wrap, may not be null

Returns:

the predicate

Throws:

IllegalArgumentException - if the predicate is null.

See Also:

NullIsTruePredicate

transformedPredicate

public static <I,O> Predicate<I> transformedPredicate(Transformer<I,? extends O> transformer,
                                                      Predicate<? super O> predicate)

Creates a predicate that transforms the input object before passing it to the predicate.

Parameters:

transformer - the transformer to call first

predicate - the predicate to call with the result of the transform

Returns:

the predicate

Throws:

IllegalArgumentException - if the transformer or the predicate is null

Since:

Commons Collections 3.1

See Also:

TransformedPredicate