org.apache.commons.collections

Class PredicateUtils

public class PredicateUtils extends Object

PredicateUtils provides reference implementations and utilities for the Predicate functor interface. The supplied predicates are: All the supplied predicates are Serializable.

Since: Commons Collections 3.0

Version: $Revision: 377508 $ $Date: 2006-02-13 22:12:33 +0000 (Mon, 13 Feb 2006) $

Author: Stephen Colebourne Ola Berg

Constructor Summary
PredicateUtils()
This class is not normally instantiated.
Method Summary
static PredicateallPredicate(Predicate[] predicates)
Create a new Predicate that returns true only if all of the specified predicates are true.
static PredicateallPredicate(Collection predicates)
Create a new Predicate that returns true only if all of the specified predicates are true.
static PredicateandPredicate(Predicate predicate1, Predicate predicate2)
Create a new Predicate that returns true only if both of the specified predicates are true.
static PredicateanyPredicate(Predicate[] predicates)
Create a new Predicate that returns true if any of the specified predicates are true.
static PredicateanyPredicate(Collection predicates)
Create a new Predicate that returns true if any of the specified predicates are true.
static PredicateasPredicate(Transformer transformer)
Create a new Predicate that wraps a Transformer.
static PredicateeitherPredicate(Predicate predicate1, Predicate predicate2)
Create a new Predicate that returns true if one, but not both, of the specified predicates are true.
static PredicateequalPredicate(Object value)
Creates a Predicate that checks if the input object is equal to the specified object using equals().
static PredicateexceptionPredicate()
Gets a Predicate that always throws an exception.
static PredicatefalsePredicate()
Gets a Predicate that always returns false.
static PredicateidentityPredicate(Object value)
Creates a Predicate that checks if the input object is equal to the specified object by identity.
static PredicateinstanceofPredicate(Class type)
Creates a Predicate that checks if the object passed in is of a particular type, using instanceof.
static PredicateinvokerPredicate(String methodName)
Creates a Predicate that invokes a method on the input object.
static PredicateinvokerPredicate(String methodName, Class[] paramTypes, Object[] args)
Creates a Predicate that invokes a method on the input object.
static PredicateneitherPredicate(Predicate predicate1, Predicate predicate2)
Create a new Predicate that returns true if neither of the specified predicates are true.
static PredicatenonePredicate(Predicate[] predicates)
Create a new Predicate that returns true if none of the specified predicates are true.
static PredicatenonePredicate(Collection predicates)
Create a new Predicate that returns true if none of the specified predicates are true.
static PredicatenotNullPredicate()
Gets a Predicate that checks if the input object passed in is not null.
static PredicatenotPredicate(Predicate predicate)
Create a new Predicate that returns true if the specified predicate returns false and vice versa.
static PredicatenullIsExceptionPredicate(Predicate predicate)
Gets a Predicate that throws an exception if the input object is null, otherwise it calls the specified Predicate.
static PredicatenullIsFalsePredicate(Predicate predicate)
Gets a Predicate that returns false if the input object is null, otherwise it calls the specified Predicate.
static PredicatenullIsTruePredicate(Predicate predicate)
Gets a Predicate that returns true if the input object is null, otherwise it calls the specified Predicate.
static PredicatenullPredicate()
Gets a Predicate that checks if the input object passed in is null.
static PredicateonePredicate(Predicate[] predicates)
Create a new Predicate that returns true if only one of the specified predicates are true.
static PredicateonePredicate(Collection predicates)
Create a new Predicate that returns true if only one of the specified predicates are true.
static PredicateorPredicate(Predicate predicate1, Predicate predicate2)
Create a new Predicate that returns true if either of the specified predicates are true.
static PredicatetransformedPredicate(Transformer transformer, Predicate predicate)
Creates a predicate that transforms the input object before passing it to the predicate.
static PredicatetruePredicate()
Gets a Predicate that always returns true.
static PredicateuniquePredicate()
Creates a Predicate that returns true the first time an object is encountered, and false if the same object is received again.

Constructor Detail

PredicateUtils

public PredicateUtils()
This class is not normally instantiated.

Method Detail

allPredicate

public static Predicate allPredicate(Predicate[] 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.

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 any predicate in the array is null

See Also:

allPredicate

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

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 any predicate in the collection is null

See Also:

andPredicate

public static Predicate andPredicate(Predicate predicate1, Predicate 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:

anyPredicate

public static Predicate anyPredicate(Predicate[] 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.

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 any predicate in the array is null

See Also:

anyPredicate

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

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 any predicate in the collection is null

See Also:

asPredicate

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

eitherPredicate

public static Predicate eitherPredicate(Predicate predicate1, Predicate 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:

equalPredicate

public static Predicate equalPredicate(Object 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:

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:

falsePredicate

public static Predicate falsePredicate()
Gets a Predicate that always returns false.

Returns: the predicate

See Also:

identityPredicate

public static Predicate identityPredicate(Object 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:

instanceofPredicate

public static Predicate 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: IllegalArgumentException if the class is null

See Also:

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

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

neitherPredicate

public static Predicate neitherPredicate(Predicate predicate1, Predicate 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

public static Predicate nonePredicate(Predicate[] 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.

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 any predicate in the array is null

See Also:

nonePredicate

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

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 any predicate in the collection is null

See Also:

notNullPredicate

public static Predicate notNullPredicate()
Gets a Predicate that checks if the input object passed in is not null.

Returns: the predicate

See Also:

notPredicate

public static Predicate notPredicate(Predicate 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:

nullIsExceptionPredicate

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

nullIsFalsePredicate

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

nullIsTruePredicate

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

nullPredicate

public static Predicate nullPredicate()
Gets a Predicate that checks if the input object passed in is null.

Returns: the predicate

See Also:

onePredicate

public static Predicate onePredicate(Predicate[] 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.

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 any predicate in the array is null

See Also:

onePredicate

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

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 any predicate in the collection is null

See Also:

orPredicate

public static Predicate orPredicate(Predicate predicate1, Predicate 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:

transformedPredicate

public static Predicate transformedPredicate(Transformer transformer, Predicate 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:

truePredicate

public static Predicate truePredicate()
Gets a Predicate that always returns true.

Returns: the predicate

See Also:

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:

Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.