## org.apache.commons.collections
Class PredicateUtils

    java.lang.Object
      org.apache.commons.collections.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
- 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: 647116 $ $Date: 2008-04-11 12:23:08 +0100 (Fri, 11 Apr 2008) $
Author:
  Stephen Colebourne, Ola Berg

Constructor Summary
`PredicateUtils()` This class is not normally instantiated.

Method Summary
`static Predicate` `allPredicate(java.util.Collection predicates)` Create a new Predicate that returns true only if all of the specified predicates are true.
`static Predicate` `allPredicate(Predicate[] predicates)` Create a new Predicate that returns true only if all of the specified predicates are true.
`static Predicate` `andPredicate(Predicate predicate1, Predicate predicate2)` Create a new Predicate that returns true only if both of the specified predicates are true.
`static Predicate` `anyPredicate(java.util.Collection predicates)` Create a new Predicate that returns true if any of the specified predicates are true.
`static Predicate` `anyPredicate(Predicate[] predicates)` Create a new Predicate that returns true if any of the specified predicates are true.
`static Predicate` `asPredicate(Transformer transformer)` Create a new Predicate that wraps a Transformer.
`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.
`static Predicate` `equalPredicate(java.lang.Object 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 Predicate` `identityPredicate(java.lang.Object value)` Creates a Predicate that checks if the input object is equal to the specified object by identity.
`static Predicate` `instanceofPredicate(java.lang.Class type)` Creates a Predicate that checks if the object passed in is of a particular type, using instanceof.
`static Predicate` `invokerPredicate(java.lang.String methodName)` Creates a Predicate that invokes a method on the input object.
`static Predicate` `invokerPredicate(java.lang.String methodName, java.lang.Class[] paramTypes, java.lang.Object[] args)` Creates a Predicate that invokes a method on the input object.
`static Predicate` `neitherPredicate(Predicate predicate1, Predicate predicate2)` Create a new Predicate that returns true if neither of the specified predicates are true.
`static Predicate` `nonePredicate(java.util.Collection predicates)` Create a new Predicate that returns true if none of the specified predicates are true.
`static Predicate` `nonePredicate(Predicate[] 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 Predicate` `notPredicate(Predicate predicate)` Create a new Predicate that returns true if the specified predicate returns false and vice versa.
`static Predicate` `nullIsExceptionPredicate(Predicate predicate)` Gets a Predicate that throws an exception if the input object is null, otherwise it calls the specified Predicate.
`static Predicate` `nullIsFalsePredicate(Predicate predicate)` Gets a Predicate that returns false if the input object is null, otherwise it calls the specified Predicate.
`static Predicate` `nullIsTruePredicate(Predicate 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 Predicate` `onePredicate(java.util.Collection predicates)` Create a new Predicate that returns true if only one of the specified predicates are true.
`static Predicate` `onePredicate(Predicate[] predicates)` Create a new Predicate that returns true if only one of the specified predicates are true.
`static Predicate` `orPredicate(Predicate predicate1, Predicate predicate2)` Create a new Predicate that returns true if either of the specified predicates are true.
`static Predicate` `transformedPredicate(Transformer transformer, Predicate 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 Predicate equalPredicate(java.lang.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:
    `EqualPredicate`

### identityPredicate

    public static Predicate identityPredicate(java.lang.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:
    `IdentityPredicate`

### instanceofPredicate

    public static Predicate instanceofPredicate(java.lang.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:
    `java.lang.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(java.lang.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:
    `java.lang.IllegalArgumentException` - if the methodName is null.
  See Also:
    `InvokerTransformer`, `TransformerPredicate`

### invokerPredicate

    public static Predicate invokerPredicate(java.lang.String methodName,
                                             java.lang.Class[] paramTypes,
                                             java.lang.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:
    `java.lang.IllegalArgumentException` - if the method name is null
    `java.lang.IllegalArgumentException` - if the paramTypes and args don't match
  See Also:
    `InvokerTransformer`, `TransformerPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if either predicate is null
  See Also:
    `AndPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicates array is null
    `java.lang.IllegalArgumentException` - if any predicate in the array is null
  See Also:
    `AllPredicate`

### allPredicate

    public static Predicate allPredicate(java.util.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:
    `java.lang.IllegalArgumentException` - if the predicates collection is null
    `java.lang.IllegalArgumentException` - if any predicate in the collection is null
  See Also:
    `AllPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if either predicate is null
  See Also:
    `OrPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicates array is null
    `java.lang.IllegalArgumentException` - if any predicate in the array is null
  See Also:
    `AnyPredicate`

### anyPredicate

    public static Predicate anyPredicate(java.util.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:
    `java.lang.IllegalArgumentException` - if the predicates collection is null
    `java.lang.IllegalArgumentException` - if any predicate in the collection is null
  See Also:
    `AnyPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if either predicate is null
  See Also:
    `OnePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicates array is null
    `java.lang.IllegalArgumentException` - if any predicate in the array is null
  See Also:
    `OnePredicate`

### onePredicate

    public static Predicate onePredicate(java.util.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:
    `java.lang.IllegalArgumentException` - if the predicates collection is null
    `java.lang.IllegalArgumentException` - if any predicate in the collection is null
  See Also:
    `OnePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if either predicate is null
  See Also:
    `NonePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicates array is null
    `java.lang.IllegalArgumentException` - if any predicate in the array is null
  See Also:
    `NonePredicate`

### nonePredicate

    public static Predicate nonePredicate(java.util.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:
    `java.lang.IllegalArgumentException` - if the predicates collection is null
    `java.lang.IllegalArgumentException` - if any predicate in the collection is null
  See Also:
    `NonePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicate is null
  See Also:
    `NotPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the transformer is null
  See Also:
    `TransformerPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicate is null.
  See Also:
    `NullIsExceptionPredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicate is null.
  See Also:
    `NullIsFalsePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the predicate is null.
  See Also:
    `NullIsTruePredicate`

### 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:
    `java.lang.IllegalArgumentException` - if the transformer or the predicate is null
  Since:
    Commons Collections 3.1
  See Also:
    `TransformedPredicate`

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