net.sf.collections15.functors.predicate
Class PredicateUtils

java.lang.Object
  net.sf.collections15.functors.predicate.PredicateUtils

public class PredicateUtils
extends java.lang.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 (the return type of the method must be boolean or Boolean).
• InstanceOf - Returns true only if the input object is an instance of a specified class.
• Equal - Returns true only if the input object is equal to a specified object (according to the Object.equals(Object) contract).
• Same - Returns true only if the input object is the same as a specified object (i.e. the input and specified references refer to the same object instance).
• Null - Returns true only if the input object is null.
• NotNull - Returns true only if the input object is not null.
• Unique - Returns true only if the input object has not already been evaluated by the Predicate.
• And/All - Returns true only if all of the decorated Predicates return true.
• Or/Any - Returns true if any of the decorated Predicates return true.
• Either/One - Returns true if only one of the decorated Predicates returns true.
• Neither/None - Returns true only if none of the decorated Predicates return true.
• Not - Retuns the opposite of a decorated Predicate.
• Transformer - Wraps a Transformer whose output type is Boolean.
• True - Always returns true.
• False - Always return false.
• Exception - Always throws an exception.
• NullIsException/NullIsFalse/NullIsTrue - Decorates an existing Predicate with specific handling for a null input object.
• Transformed - Transforms the input object before calling a decorated Predicate.

All of the supplied predicates are Serializable.

Since:

Collections15 1.0

Author:

Stephen Colebourne, Ola Berg, Chris Lambrou (port to Java 5.0)

Constructor Summary

protected

PredicateUtils() Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Summary

static <T> Predicate<T>	allPredicate(java.util.Collection<Predicate<? super T>> predicates) Returns a Predicate that wraps the specified collection of Predicates, and which returns true only if all of the specified Predicates return true.
static <T> Predicate<T>	anyPredicate(java.util.Collection<Predicate<? super T>> predicates) Returns a Predicate that wraps the specified collection of Predicates, and which returns true if any one of the specified Predicates return true.
static <T> Predicate<T>	asPredicate(Transformer<T,java.lang.Boolean> transformer) Returns a Predicate that evaluates input objects using the specified Transformer.
static <T> Predicate<T>	equalPredicate(T value) Returns a Predicate instance whose evaluate method returns true only if the input object is equal to the specified value, according to the Object.equals(Object) contract.
static <T> Predicate<T>	exceptionPredicate() Returns a Predicate instance whose evaluate method always throws an exception.
static <T> Predicate<T>	falsePredicate() Returns a Predicate instance whose evaluate method always returns false.
static <T> Predicate<T>	instanceofPredicate(java.lang.Class<? extends T> type) Returns a Predicate instance whose evaluate method returns true only if the input object is an instance of the specified type.
static <T> Predicate<T>	invokerPredicate(java.lang.String methodName) Returns a Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have no parameters.
static <T> Predicate<T>	invokerPredicate(java.lang.String methodName, java.lang.Class[] paramTypes, java.lang.Object[] args) Returns a Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have the specified parameters.
static <T> Predicate<T>	nonePredicate(java.util.Collection<Predicate<? super T>> predicates) Returns a Predicate that wraps the specified collection of Predicates, and which returns true unless any one of the specified Predicates return true.
static <T> Predicate<T>	notNullPredicate() Returns a Predicate instance whose evaluate method returns true only if the input object is not null.
static <T> Predicate<T>	notPredicate(Predicate<T> predicate) Returns a Predicate whose evaluate method returns the inverse of the decorated Predicate's evaluate method.
static <T> Predicate<T>	nullIsExceptionPredicate(Predicate<T> predicate) Returns a Predicate that decorates the specified Predicate, throwing an exception for any null input object.
static <T> Predicate<T>	nullIsFalsePredicate(Predicate<T> predicate) Returns a Predicate that decorates the specified Predicate, returning false for any null input object.
static <T> Predicate<T>	nullIsTruePredicate(Predicate<T> predicate) Returns a Predicate that decorates the specified Predicate, returning true for any null input object.
static <T> Predicate<T>	nullPredicate() Returns a Predicate instance whose evaluate method returns true only if the input object is null.
static <T> Predicate<T>	onePredicate(java.util.Collection<Predicate<? super T>> predicates) Returns a Predicate that wraps the specified collection of Predicates, and which returns true if only one of the specified Predicates return true.
static <T> Predicate<T>	samePredicate(T value) Returns a Predicate instance whose evaluate method returns true only if the input object is the same as the specified value (i.e.
static <E,D> Predicate<E>	transformedPredicate(Transformer<? super E,? extends D> transformer, Predicate<? super D> predicate) Returns a Predicate whose evaluate method transforms an input object and evaluates the result using another Predicate instance.
static <T> Predicate<T>	truePredicate() Returns a Predicate instance whose evaluate method always returns true.
static <T> Predicate<T>	uniquePredicate() Returns a Predicate which returns true the first time any given object is evaluated, and returns false each time the same object is subsequently evaluated.

Methods inherited from class java.lang.Object

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

Constructor Detail

PredicateUtils

protected PredicateUtils()

Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Detail

exceptionPredicate

public static <T> Predicate<T> exceptionPredicate()

Returns a Predicate instance whose evaluate method always throws an exception.

Returns:

A Predicate instance whose evaluate method always throws an exception.

Since:

Collections 1.0

See Also:

ExceptionPredicate

truePredicate

public static <T> Predicate<T> truePredicate()

Returns a Predicate instance whose evaluate method always returns true.

Returns:

A Predicate instance whose evaluate method always returns true.

Since:

Collections 1.0

See Also:

TruePredicate

falsePredicate

public static <T> Predicate<T> falsePredicate()

Returns a Predicate instance whose evaluate method always returns false.

Returns:

A Predicate instance whose evaluate method always returns false.

Since:

Collections 1.0

See Also:

FalsePredicate

nullPredicate

public static <T> Predicate<T> nullPredicate()

Returns a Predicate instance whose evaluate method returns true only if the input object is null.

Returns:

A Predicate instance whose evaluate method returns true only if the input object is null.

Since:

Collections 1.0

See Also:

NullPredicate

notNullPredicate

public static <T> Predicate<T> notNullPredicate()

Returns a Predicate instance whose evaluate method returns true only if the input object is not null.

Returns:

A Predicate instance whose evaluate method returns true only if the input object is not null.

Since:

Collections 1.0

See Also:

NotNullPredicate

equalPredicate

public static <T> Predicate<T> equalPredicate(T value)

Returns a Predicate instance whose evaluate method returns true only if the input object is equal to the specified value, according to the Object.equals(Object) contract.

Parameters:

value - The object to which input objects are compared.

Returns:

A Predicate instance whose evaluate method returns true only if the input object is equal to the specified value, according to the Object.equals(Object) contract.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified value object is null.

Since:

Collections 1.0

See Also:

EqualPredicate, samePredicate(T)

samePredicate

public static <T> Predicate<T> samePredicate(T value)

Returns a Predicate instance whose evaluate method returns true only if the input object is the same as the specified value (i.e. only if the input object reference and the value object reference both refer to the same object instance).

Parameters:

value - The object to which input objects are compared.

Returns:

A Predicate instance whose evaluate method returns true only if the input object is the same as the specified value (i.e. only if the input object reference and the value object reference both refer to the same object instance).

Throws:

java.lang.IllegalArgumentException - Thrown if the specified value object is null.

Since:

Collections 1.0

See Also:

SamePredicate, equalPredicate(T)

instanceofPredicate

public static <T> Predicate<T> instanceofPredicate(java.lang.Class<? extends T> type)

Returns a Predicate instance whose evaluate method returns true only if the input object is an instance of the specified type.

Parameters:

type - The type to compare input objects to.

Returns:

A Predicate instance whose evaluate method returns true only if the input object is an instance of the specified type.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified type is null.

Since:

Collections 1.0

See Also:

InstanceofPredicate

uniquePredicate

public static <T> Predicate<T> uniquePredicate()

Returns a Predicate which returns true the first time any given object is evaluated, and returns false each time the same object is subsequently evaluated.

Returns:

A Predicate which returns true the first time any given object is evaluated, and returns false each time the same object is subsequently evaluated.

See Also:

UniquePredicate

invokerPredicate

public static <T> Predicate<T> invokerPredicate(java.lang.String methodName)

Returns a Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have no parameters.

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

If the input object is null, or does not have the named method with the appropriate signature, an exception is thrown.

Parameters:

methodName - The method name to call on the input object.

Returns:

A Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have no parameters.

Throws:

java.lang.IllegalArgumentException - If the method name is null.

See Also:

InvokerTransformer, TransformerPredicate

invokerPredicate

public static <T> Predicate<T> invokerPredicate(java.lang.String methodName,
                                                java.lang.Class[] paramTypes,
                                                java.lang.Object[] args)

Returns a Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have the specified parameters.

If the input object is null, or does not have the named method with the appropriate signature, an exception is thrown.

Parameters:

methodName - The method name to call on the input object.

paramTypes - The types of the arguments of the method to invoke on the input object.

args - The arguments to pass to the method invoked on the input object.

Returns:

A Predicate that invokes a method on the input object, which must return either a boolean or Boolean, and have the specified parameters.

Throws:

java.lang.IllegalArgumentException - If the method name is null.

java.lang.IllegalArgumentException - If paramTypes is null, or contains any null classes.

java.lang.IllegalArgumentException - If args is null, contains a different number of elements to paramTypes, or if any of its elements doen't match the corresponding type in paramTypes.

See Also:

InvokerTransformer, TransformerPredicate

allPredicate

public static <T> Predicate<T> allPredicate(java.util.Collection<Predicate<? super T>> predicates)

Returns a Predicate that wraps the specified collection of Predicates, and which returns true only if all of the specified Predicates return true.

Parameters:

predicates - The Predicates to wrap. The contents of the collection are defensively copied by the new instance.

Returns:

A Predicate instance that will evaluate to true unless any of the wrapped Predicates evaluate to false.

Throws:

java.lang.IllegalArgumentException - Thrown if the collection, or any of its elements are null. The collection may be empty, however, in which case the resulting Predicate will always return true.

See Also:

AllPredicate

anyPredicate

public static <T> Predicate<T> anyPredicate(java.util.Collection<Predicate<? super T>> predicates)

Returns a Predicate that wraps the specified collection of Predicates, and which returns true if any one of the specified Predicates return true.

Parameters:

predicates - The Predicates to wrap. The contents of the collection are defensively copied by the new instance.

Returns:

A Predicate instance that will evaluate to true if any of the wrapped Predicates evaluate to true.

Throws:

java.lang.IllegalArgumentException - Thrown if the collection, or any of its elements are null. The collection may be empty, however, in which case the resulting AnyPredicate will always return false.

See Also:

AnyPredicate

onePredicate

public static <T> Predicate<T> onePredicate(java.util.Collection<Predicate<? super T>> predicates)

Returns a Predicate that wraps the specified collection of Predicates, and which returns true if only one of the specified Predicates return true.

Parameters:

predicates - The Predicates to wrap. The contents of the collection are defensively copied by the new instance.

Returns:

A Predicate instance that will only evaluate to true if exactly one of the wrapped Predicates evaluates to true.

Throws:

java.lang.IllegalArgumentException - Thrown if the collection, or any of its elements are null. The collection may be empty, however, in which case the resulting AnyPredicate will always return false.

See Also:

OnePredicate

nonePredicate

public static <T> Predicate<T> nonePredicate(java.util.Collection<Predicate<? super T>> predicates)

Returns a Predicate that wraps the specified collection of Predicates, and which returns true unless any one of the specified Predicates return true.

Parameters:

predicates - The Predicates to wrap. The contents of the collection are defensively copied by the new instance.

Returns:

A Predicate instance that will evaluate to true unless any of the wrapped Predicates evaluate to true.

Throws:

java.lang.IllegalArgumentException - Thrown if the collection, or any of its elements are null. The collection may be empty, however, in which case the resulting AnyPredicate will always return true.

See Also:

NonePredicate

notPredicate

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

Returns a Predicate whose evaluate method returns the inverse of the decorated Predicate's evaluate method.

Parameters:

predicate - The decorated Predicate.

Throws:

java.lang.IllegalArgumentException - Thrown if the decorated Predicate is null.

asPredicate

public static <T> Predicate<T> asPredicate(Transformer<T,java.lang.Boolean> transformer)

Returns a Predicate that evaluates input objects using the specified Transformer. The Predicate evaluates true if the Transformer returns Boolean.TRUE, and evaluates to false if the Transformer returns Boolean.False or null.

Parameters:

transformer - The Transformer to use.

Returns:

A Predicate that evaluates input objects using the specified Transformer.

Throws:

java.lang.IllegalArgumentException - Thrown if the transformer argument is null.

nullIsExceptionPredicate

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

Returns a Predicate that decorates the specified Predicate, throwing an exception for any null input object.

Parameters:

predicate - The decorated Predicate that is delgated to if the null check doesn't throw an exception.

Returns:

A Predicate that decorates the specified Predicate, throwing an exception for any null input object.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified Predicate to decorate is null.

See Also:

NullIsExceptionPredicate

nullIsFalsePredicate

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

Returns a Predicate that decorates the specified Predicate, returning false for any null input object.

Parameters:

predicate - The decorated Predicate that is delgated to if the null check doesn't cause false to be returned.

Returns:

A Predicate that decorates the specified Predicate, returning false for any null input object.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified Predicate to decorate is null.

See Also:

NullIsFalsePredicate

nullIsTruePredicate

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

Returns a Predicate that decorates the specified Predicate, returning true for any null input object.

Parameters:

predicate - The decorated Predicate that is delgated to if the null check doesn't cause true to be returned.

Returns:

A Predicate that decorates the specified Predicate, returning true for any null input object.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified Predicate to decorate is null.

See Also:

NullIsTruePredicate

transformedPredicate

public static <E,D> Predicate<E> transformedPredicate(Transformer<? super E,? extends D> transformer,
                                                      Predicate<? super D> predicate)

Returns a Predicate whose evaluate method transforms an input object and evaluates the result using another Predicate instance.

Parameters:

transformer - The Transformer used to transform an input object prior to evaluation.

predicate - The Predicate used to evaluate the transformed input object.

Returns:

A Predicate whose evaluate method transforms an input object and evaluates the result using another Predicate instance.

Throws:

java.lang.IllegalArgumentException - If either argument is null.

Since:

Collections15 1.0

See Also:

TransformedPredicate