All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.commons.collections4.PredicateUtils Maven / Gradle / Ivy

Go to download

The Apache Commons Collections package contains types that extend and augment the Java Collections Framework.

The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections4;

import java.util.Collection;

import org.apache.commons.collections4.functors.AllPredicate;
import org.apache.commons.collections4.functors.AndPredicate;
import org.apache.commons.collections4.functors.AnyPredicate;
import org.apache.commons.collections4.functors.EqualPredicate;
import org.apache.commons.collections4.functors.ExceptionPredicate;
import org.apache.commons.collections4.functors.FalsePredicate;
import org.apache.commons.collections4.functors.IdentityPredicate;
import org.apache.commons.collections4.functors.InstanceofPredicate;
import org.apache.commons.collections4.functors.InvokerTransformer;
import org.apache.commons.collections4.functors.NonePredicate;
import org.apache.commons.collections4.functors.NotNullPredicate;
import org.apache.commons.collections4.functors.NotPredicate;
import org.apache.commons.collections4.functors.NullIsExceptionPredicate;
import org.apache.commons.collections4.functors.NullIsFalsePredicate;
import org.apache.commons.collections4.functors.NullIsTruePredicate;
import org.apache.commons.collections4.functors.NullPredicate;
import org.apache.commons.collections4.functors.OnePredicate;
import org.apache.commons.collections4.functors.OrPredicate;
import org.apache.commons.collections4.functors.TransformedPredicate;
import org.apache.commons.collections4.functors.TransformerPredicate;
import org.apache.commons.collections4.functors.TruePredicate;
import org.apache.commons.collections4.functors.UniquePredicate;

/**
 * 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
 */
public class PredicateUtils {

    /**
     * This class is not normally instantiated.
     */
    private PredicateUtils() {}

    // Simple predicates
    //-----------------------------------------------------------------------------

    /**
     * Gets a Predicate that always throws an exception.
     * This could be useful during testing as a placeholder.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see ExceptionPredicate
     */
    public static  Predicate exceptionPredicate() {
        return ExceptionPredicate.exceptionPredicate();
    }

    /**
     * Gets a Predicate that always returns true.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see TruePredicate
     */
    public static  Predicate truePredicate() {
        return TruePredicate.truePredicate();
    }

    /**
     * Gets a Predicate that always returns false.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see FalsePredicate
     */
    public static  Predicate falsePredicate() {
        return FalsePredicate.falsePredicate();
    }

    /**
     * Gets a Predicate that checks if the input object passed in is null.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see NullPredicate
     */
    public static  Predicate nullPredicate() {
        return NullPredicate.nullPredicate();
    }

    /**
     * Gets a Predicate that checks if the input object passed in is not null.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see NotNullPredicate
     */
    public static  Predicate notNullPredicate() {
        return NotNullPredicate.notNullPredicate();
    }

    /**
     * Creates a Predicate that checks if the input object is equal to the
     * specified object using equals().
     *
     * @param   the type that the predicate queries
     * @param value  the value to compare against
     * @return the predicate
     * @see EqualPredicate
     */
    public static  Predicate equalPredicate(final T value) {
        return EqualPredicate.equalPredicate(value);
    }

    /**
     * Creates a Predicate that checks if the input object is equal to the
     * specified object by identity.
     *
     * @param   the type that the predicate queries
     * @param value  the value to compare against
     * @return the predicate
     * @see IdentityPredicate
     */
    public static  Predicate identityPredicate(final T value) {
        return IdentityPredicate.identityPredicate(value);
    }

    /**
     * Creates a Predicate that checks if the object passed in is of
     * a particular type, using instanceof. A null input
     * object will return false.
     *
     * @param type  the type to check for, may not be null
     * @return the predicate
     * @throws NullPointerException if the class is null
     * @see InstanceofPredicate
     */
    public static Predicate instanceofPredicate(final Class type) {
        return InstanceofPredicate.instanceOfPredicate(type);
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @return the predicate
     * @see UniquePredicate
     */
    public static  Predicate uniquePredicate() {
        // must return new instance each time
        return UniquePredicate.uniquePredicate();
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param methodName  the method name to call on the input object, may not be null
     * @return the predicate
     * @throws NullPointerException if the methodName is null.
     * @see InvokerTransformer
     * @see TransformerPredicate
     */
    public static  Predicate invokerPredicate(final String methodName) {
        // reuse transformer as it has caching - this is lazy really, should have inner class here
        return asPredicate(InvokerTransformer.invokerTransformer(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.
     *
     * @param   the type that the predicate queries
     * @param methodName  the method name to call on the input object, may not be null
     * @param paramTypes  the parameter types
     * @param args  the arguments
     * @return the predicate
     * @throws NullPointerException if the method name is null
     * @throws IllegalArgumentException if the paramTypes and args don't match
     * @see InvokerTransformer
     * @see TransformerPredicate
     */
    public static  Predicate invokerPredicate(final String methodName, final Class[] paramTypes,
                                                    final Object[] args) {
        // reuse transformer as it has caching - this is lazy really, should have inner class here
        return asPredicate(InvokerTransformer.invokerTransformer(methodName, paramTypes, args));
    }

    // Boolean combinations
    //-----------------------------------------------------------------------------

    /**
     * Create a new Predicate that returns true only if both of the specified
     * predicates are true.
     *
     * @param   the type that the predicate queries
     * @param predicate1  the first predicate, may not be null
     * @param predicate2  the second predicate, may not be null
     * @return the and predicate
     * @throws NullPointerException if either predicate is null
     * @see AndPredicate
     */
    public static  Predicate andPredicate(final Predicate predicate1,
                                                final Predicate predicate2) {
        return AndPredicate.andPredicate(predicate1, predicate2);
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param predicates  an array of predicates to check, may not be null
     * @return the all predicate
     * @throws NullPointerException if the predicates array is null
     * @throws NullPointerException if any predicate in the array is null
     * @see AllPredicate
     */
    public static  Predicate allPredicate(final Predicate... predicates) {
        return AllPredicate.allPredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicates  a collection of predicates to check, may not be null
     * @return the all predicate
     * @throws NullPointerException if the predicates collection is null
     * @throws NullPointerException if any predicate in the collection is null
     * @see AllPredicate
     */
    public static  Predicate allPredicate(final Collection> predicates) {
        return AllPredicate.allPredicate(predicates);
    }

    /**
     * Create a new Predicate that returns true if either of the specified
     * predicates are true.
     *
     * @param   the type that the predicate queries
     * @param predicate1  the first predicate, may not be null
     * @param predicate2  the second predicate, may not be null
     * @return the or predicate
     * @throws NullPointerException if either predicate is null
     * @see OrPredicate
     */
    public static  Predicate orPredicate(final Predicate predicate1,
                                               final Predicate predicate2) {
        return OrPredicate.orPredicate(predicate1, predicate2);
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param predicates  an array of predicates to check, may not be null
     * @return the any predicate
     * @throws NullPointerException if the predicates array is null
     * @throws NullPointerException if any predicate in the array is null
     * @see AnyPredicate
     */
    public static  Predicate anyPredicate(final Predicate... predicates) {
        return AnyPredicate.anyPredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicates  a collection of predicates to check, may not be null
     * @return the any predicate
     * @throws NullPointerException if the predicates collection is null
     * @throws NullPointerException if any predicate in the collection is null
     * @see AnyPredicate
     */
    public static  Predicate anyPredicate(final Collection> predicates) {
        return AnyPredicate.anyPredicate(predicates);
    }

    /**
     * Create a new Predicate that returns true if one, but not both, of the
     * specified predicates are true. XOR
     *
     * @param   the type that the predicate queries
     * @param predicate1  the first predicate, may not be null
     * @param predicate2  the second predicate, may not be null
     * @return the either predicate
     * @throws NullPointerException if either predicate is null
     * @see OnePredicate
     */
    public static  Predicate eitherPredicate(final Predicate predicate1,
                                                   final Predicate predicate2) {
        @SuppressWarnings("unchecked")
        final Predicate onePredicate = PredicateUtils.onePredicate(predicate1, predicate2);
        return onePredicate;
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param predicates  an array of predicates to check, may not be null
     * @return the one predicate
     * @throws NullPointerException if the predicates array is null
     * @throws NullPointerException if any predicate in the array is null
     * @see OnePredicate
     */
    public static  Predicate onePredicate(final Predicate... predicates) {
        return OnePredicate.onePredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicates  a collection of predicates to check, may not be null
     * @return the one predicate
     * @throws NullPointerException if the predicates collection is null
     * @throws NullPointerException if any predicate in the collection is null
     * @see OnePredicate
     */
    public static  Predicate onePredicate(final Collection> predicates) {
        return OnePredicate.onePredicate(predicates);
    }

    /**
     * Create a new Predicate that returns true if neither of the specified
     * predicates are true.
     *
     * @param   the type that the predicate queries
     * @param predicate1  the first predicate, may not be null
     * @param predicate2  the second predicate, may not be null
     * @return the neither predicate
     * @throws NullPointerException if either predicate is null
     * @see NonePredicate
     */
    public static  Predicate neitherPredicate(final Predicate predicate1,
                                                    final Predicate predicate2) {
        @SuppressWarnings("unchecked")
        final Predicate nonePredicate = PredicateUtils.nonePredicate(predicate1, predicate2);
        return nonePredicate;
    }

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param predicates  an array of predicates to check, may not be null
     * @return the none predicate
     * @throws NullPointerException if the predicates array is null
     * @throws NullPointerException if any predicate in the array is null
     * @see NonePredicate
     */
    public static  Predicate nonePredicate(final Predicate... predicates) {
        return NonePredicate.nonePredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicates  a collection of predicates to check, may not be null
     * @return the none predicate
     * @throws NullPointerException if the predicates collection is null
     * @throws NullPointerException if any predicate in the collection is null
     * @see NonePredicate
     */
    public static  Predicate nonePredicate(final Collection> predicates) {
        return NonePredicate.nonePredicate(predicates);
    }

    /**
     * Create a new Predicate that returns true if the specified predicate
     * returns false and vice versa.
     *
     * @param   the type that the predicate queries
     * @param predicate  the predicate to not
     * @return the not predicate
     * @throws NullPointerException if the predicate is null
     * @see NotPredicate
     */
    public static  Predicate notPredicate(final Predicate predicate) {
        return NotPredicate.notPredicate(predicate);
    }

    // Adaptors
    //-----------------------------------------------------------------------------

    /**
     * Create a new Predicate that wraps a Transformer. The Transformer must
     * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException
     * will be thrown.
     *
     * @param   the type that the predicate queries
     * @param transformer  the transformer to wrap, may not be null
     * @return the transformer wrapping predicate
     * @throws NullPointerException if the transformer is null
     * @see TransformerPredicate
     */
    public static  Predicate asPredicate(final Transformer transformer) {
        return TransformerPredicate.transformerPredicate(transformer);
    }

    // Null handlers
    //-----------------------------------------------------------------------------

    /**
     * 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.
     *
     * @param   the type that the predicate queries
     * @param predicate  the predicate to wrap, may not be null
     * @return the predicate
     * @throws NullPointerException if the predicate is null.
     * @see NullIsExceptionPredicate
     */
    public static  Predicate nullIsExceptionPredicate(final Predicate predicate){
        return NullIsExceptionPredicate.nullIsExceptionPredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicate  the predicate to wrap, may not be null
     * @return the predicate
     * @throws NullPointerException if the predicate is null.
     * @see NullIsFalsePredicate
     */
    public static  Predicate nullIsFalsePredicate(final Predicate predicate){
        return NullIsFalsePredicate.nullIsFalsePredicate(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.
     *
     * @param   the type that the predicate queries
     * @param predicate  the predicate to wrap, may not be null
     * @return the predicate
     * @throws NullPointerException if the predicate is null.
     * @see NullIsTruePredicate
     */
    public static  Predicate nullIsTruePredicate(final Predicate predicate){
        return NullIsTruePredicate.nullIsTruePredicate(predicate);
    }

    // Transformed
    //-----------------------------------------------------------------------
    /**
     * Creates a predicate that transforms the input object before passing it
     * to the predicate.
     *
     * @param   the type that the predicate queries
     * @param transformer  the transformer to call first
     * @param predicate  the predicate to call with the result of the transform
     * @return the predicate
     * @throws NullPointerException if the transformer or the predicate is null
     * @see TransformedPredicate
     * @since 3.1
     */
    public static  Predicate transformedPredicate(
            final Transformer transformer, final Predicate predicate) {
        return TransformedPredicate.transformedPredicate(transformer, predicate);
    }

}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy