    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.collections4;
    018
    019import java.util.Collection;
    020
    021import org.apache.commons.collections4.functors.AllPredicate;
    022import org.apache.commons.collections4.functors.AndPredicate;
    023import org.apache.commons.collections4.functors.AnyPredicate;
    024import org.apache.commons.collections4.functors.EqualPredicate;
    025import org.apache.commons.collections4.functors.ExceptionPredicate;
    026import org.apache.commons.collections4.functors.FalsePredicate;
    027import org.apache.commons.collections4.functors.IdentityPredicate;
    028import org.apache.commons.collections4.functors.InstanceofPredicate;
    029import org.apache.commons.collections4.functors.InvokerTransformer;
    030import org.apache.commons.collections4.functors.NonePredicate;
    031import org.apache.commons.collections4.functors.NotNullPredicate;
    032import org.apache.commons.collections4.functors.NotPredicate;
    033import org.apache.commons.collections4.functors.NullIsExceptionPredicate;
    034import org.apache.commons.collections4.functors.NullIsFalsePredicate;
    035import org.apache.commons.collections4.functors.NullIsTruePredicate;
    036import org.apache.commons.collections4.functors.NullPredicate;
    037import org.apache.commons.collections4.functors.OnePredicate;
    038import org.apache.commons.collections4.functors.OrPredicate;
    039import org.apache.commons.collections4.functors.TransformedPredicate;
    040import org.apache.commons.collections4.functors.TransformerPredicate;
    041import org.apache.commons.collections4.functors.TruePredicate;
    042import org.apache.commons.collections4.functors.UniquePredicate;
    043
    044/**
    045 * {@code PredicateUtils} provides reference implementations and utilities
    046 * for the Predicate functor interface. The supplied predicates are:
    047 * <ul>
    048 * <li>Invoker - returns the result of a method call on the input object
    049 * <li>InstanceOf - true if the object is an instanceof a class
    050 * <li>Equal - true if the object equals() a specified object
    051 * <li>Identity - true if the object == a specified object
    052 * <li>Null - true if the object is null
    053 * <li>NotNull - true if the object is not null
    054 * <li>Unique - true if the object has not already been evaluated
    055 * <li>And/All - true if all of the predicates are true
    056 * <li>Or/Any - true if any of the predicates is true
    057 * <li>Either/One - true if only one of the predicate is true
    058 * <li>Neither/None - true if none of the predicates are true
    059 * <li>Not - true if the predicate is false, and vice versa
    060 * <li>Transformer - wraps a Transformer as a Predicate
    061 * <li>True - always return true
    062 * <li>False - always return false
    063 * <li>Exception - always throws an exception
    064 * <li>NullIsException/NullIsFalse/NullIsTrue - check for null input
    065 * <li>Transformed - transforms the input before calling the predicate
    066 * </ul>
    067 * All the supplied predicates are Serializable.
    068 *
    069 * @since 3.0
    070 */
    071public class PredicateUtils {
    072
    073    /**
    074     * Create a new Predicate that returns true only if all of the specified
    075     * predicates are true. The predicates are checked in iterator order.
    076     * If the collection of predicates is empty, then this predicate returns true.
    077     *
    078     * @param <T>  the type that the predicate queries
    079     * @param predicates  a collection of predicates to check, may not be null
    080     * @return the {@code all} predicate
    081     * @throws NullPointerException if the predicates collection is null
    082     * @throws NullPointerException if any predicate in the collection is null
    083     * @see AllPredicate
    084     */
    085    public static <T> Predicate<T> allPredicate(final Collection<? extends Predicate<? super T>> predicates) {
    086        return AllPredicate.allPredicate(predicates);
    087    }
    088
    089    /**
    090     * Create a new Predicate that returns true only if all of the specified
    091     * predicates are true.
    092     * If the array of predicates is empty, then this predicate returns true.
    093     *
    094     * @param <T>  the type that the predicate queries
    095     * @param predicates  an array of predicates to check, may not be null
    096     * @return the {@code all} predicate
    097     * @throws NullPointerException if the predicates array is null
    098     * @throws NullPointerException if any predicate in the array is null
    099     * @see AllPredicate
    100     */
    101    public static <T> Predicate<T> allPredicate(final Predicate<? super T>... predicates) {
    102        return AllPredicate.allPredicate(predicates);
    103    }
    104
    105    /**
    106     * Create a new Predicate that returns true only if both of the specified
    107     * predicates are true.
    108     *
    109     * @param <T>  the type that the predicate queries
    110     * @param predicate1  the first predicate, may not be null
    111     * @param predicate2  the second predicate, may not be null
    112     * @return the {@code and} predicate
    113     * @throws NullPointerException if either predicate is null
    114     * @see AndPredicate
    115     */
    116    public static <T> Predicate<T> andPredicate(final Predicate<? super T> predicate1,
    117                                                final Predicate<? super T> predicate2) {
    118        return AndPredicate.andPredicate(predicate1, predicate2);
    119    }
    120
    121    /**
    122     * Create a new Predicate that returns true if any of the specified
    123     * predicates are true. The predicates are checked in iterator order.
    124     * If the collection of predicates is empty, then this predicate returns false.
    125     *
    126     * @param <T>  the type that the predicate queries
    127     * @param predicates  a collection of predicates to check, may not be null
    128     * @return the {@code any} predicate
    129     * @throws NullPointerException if the predicates collection is null
    130     * @throws NullPointerException if any predicate in the collection is null
    131     * @see AnyPredicate
    132     */
    133    public static <T> Predicate<T> anyPredicate(final Collection<? extends Predicate<? super T>> predicates) {
    134        return AnyPredicate.anyPredicate(predicates);
    135    }
    136
    137    /**
    138     * Create a new Predicate that returns true if any of the specified
    139     * predicates are true.
    140     * If the array of predicates is empty, then this predicate returns false.
    141     *
    142     * @param <T>  the type that the predicate queries
    143     * @param predicates  an array of predicates to check, may not be null
    144     * @return the {@code any} predicate
    145     * @throws NullPointerException if the predicates array is null
    146     * @throws NullPointerException if any predicate in the array is null
    147     * @see AnyPredicate
    148     */
    149    public static <T> Predicate<T> anyPredicate(final Predicate<? super T>... predicates) {
    150        return AnyPredicate.anyPredicate(predicates);
    151    }
    152
    153    /**
    154     * Create a new Predicate that wraps a Transformer. The Transformer must
    155     * return either {@link Boolean#TRUE} or {@link Boolean#FALSE} otherwise a
    156     * PredicateException will be thrown.
    157     *
    158     * @param <T>  the type that the predicate queries
    159     * @param transformer  the transformer to wrap, may not be null
    160     * @return the transformer wrapping predicate
    161     * @throws NullPointerException if the transformer is null
    162     * @see TransformerPredicate
    163     */
    164    public static <T> Predicate<T> asPredicate(final Transformer<? super T, Boolean> transformer) {
    165        return TransformerPredicate.transformerPredicate(transformer);
    166    }
    167
    168    /**
    169     * Create a new Predicate that returns true if one, but not both, of the
    170     * specified predicates are true. XOR
    171     *
    172     * @param <T>  the type that the predicate queries
    173     * @param predicate1  the first predicate, may not be null
    174     * @param predicate2  the second predicate, may not be null
    175     * @return the {@code either} predicate
    176     * @throws NullPointerException if either predicate is null
    177     * @see OnePredicate
    178     */
    179    public static <T> Predicate<T> eitherPredicate(final Predicate<? super T> predicate1,
    180                                                   final Predicate<? super T> predicate2) {
    181        @SuppressWarnings("unchecked")
    182        final Predicate<T> onePredicate = onePredicate(predicate1, predicate2);
    183        return onePredicate;
    184    }
    185
    186    /**
    187     * Creates a Predicate that checks if the input object is equal to the
    188     * specified object using equals().
    189     *
    190     * @param <T>  the type that the predicate queries
    191     * @param value  the value to compare against
    192     * @return the predicate
    193     * @see EqualPredicate
    194     */
    195    public static <T> Predicate<T> equalPredicate(final T value) {
    196        return EqualPredicate.equalPredicate(value);
    197    }
    198
    199    /**
    200     * Gets a Predicate that always throws an exception.
    201     * This could be useful during testing as a placeholder.
    202     *
    203     * @param <T>  the type that the predicate queries
    204     * @return the predicate
    205     * @see ExceptionPredicate
    206     */
    207    public static <T> Predicate<T> exceptionPredicate() {
    208        return ExceptionPredicate.exceptionPredicate();
    209    }
    210
    211    /**
    212     * Gets a Predicate that always returns false.
    213     *
    214     * @param <T>  the type that the predicate queries
    215     * @return the predicate
    216     * @see FalsePredicate
    217     */
    218    public static <T> Predicate<T> falsePredicate() {
    219        return FalsePredicate.falsePredicate();
    220    }
    221
    222    /**
    223     * Creates a Predicate that checks if the input object is equal to the
    224     * specified object by identity.
    225     *
    226     * @param <T>  the type that the predicate queries
    227     * @param value  the value to compare against
    228     * @return the predicate
    229     * @see IdentityPredicate
    230     */
    231    public static <T> Predicate<T> identityPredicate(final T value) {
    232        return IdentityPredicate.identityPredicate(value);
    233    }
    234
    235    /**
    236     * Creates a Predicate that checks if the object passed in is of
    237     * a particular type, using instanceof. A {@code null} input
    238     * object will return {@code false}.
    239     *
    240     * @param type  the type to check for, may not be null
    241     * @return the predicate
    242     * @throws NullPointerException if the class is null
    243     * @see InstanceofPredicate
    244     */
    245    public static Predicate<Object> instanceofPredicate(final Class<?> type) {
    246        return InstanceofPredicate.instanceOfPredicate(type);
    247    }
    248
    249    /**
    250     * Creates a Predicate that invokes a method on the input object.
    251     * The method must return either a boolean or a non-null Boolean,
    252     * and have no parameters. If the input object is null, a
    253     * PredicateException is thrown.
    254     * <p>
    255     * For ePredicateUtils.invokerPredicate("isEmpty");}
    256     * will call the {@code isEmpty} method on the input object to
    257     * determine the predicate result.
    258     *
    259     * @param <T>  the type that the predicate queries
    260     * @param methodName  the method name to call on the input object, may not be null
    261     * @return the predicate
    262     * @throws NullPointerException if the methodName is null.
    263     * @see InvokerTransformer
    264     * @see TransformerPredicate
    265     */
    266    public static <T> Predicate<T> invokerPredicate(final String methodName) {
    267        // reuse transformer as it has caching - this is lazy really, should have inner class here
    268        return asPredicate(InvokerTransformer.<Object, Boolean>invokerTransformer(methodName));
    269    }
    270
    271    /**
    272     * Creates a Predicate that invokes a method on the input object.
    273     * The method must return either a boolean or a non-null Boolean,
    274     * and have no parameters. If the input object is null, a
    275     * PredicateException is thrown.
    276     * <p>
    277     * For example, {@code PredicateUtils.invokerPredicate("isEmpty");}
    278     * will call the {@code isEmpty} method on the input object to
    279     * determine the predicate result.
    280     *
    281     * @param <T>  the type that the predicate queries
    282     * @param methodName  the method name to call on the input object, may not be null
    283     * @param paramTypes  the parameter types
    284     * @param args  the arguments
    285     * @return the predicate
    286     * @throws NullPointerException if the method name is null
    287     * @throws IllegalArgumentException if the paramTypes and args don't match
    288     * @see InvokerTransformer
    289     * @see TransformerPredicate
    290     */
    291    public static <T> Predicate<T> invokerPredicate(final String methodName, final Class<?>[] paramTypes,
    292                                                    final Object[] args) {
    293        // reuse transformer as it has caching - this is lazy really, should have inner class here
    294        return asPredicate(InvokerTransformer.<Object, Boolean>invokerTransformer(methodName, paramTypes, args));
    295    }
    296
    297    /**
    298     * Create a new Predicate that returns true if neither of the specified
    299     * predicates are true.
    300     *
    301     * @param <T>  the type that the predicate queries
    302     * @param predicate1  the first predicate, may not be null
    303     * @param predicate2  the second predicate, may not be null
    304     * @return the {@code neither} predicate
    305     * @throws NullPointerException if either predicate is null
    306     * @see NonePredicate
    307     */
    308    public static <T> Predicate<T> neitherPredicate(final Predicate<? super T> predicate1,
    309                                                    final Predicate<? super T> predicate2) {
    310        @SuppressWarnings("unchecked")
    311        final Predicate<T> nonePredicate = nonePredicate(predicate1, predicate2);
    312        return nonePredicate;
    313    }
    314
    315    /**
    316     * Create a new Predicate that returns true if none of the specified
    317     * predicates are true. The predicates are checked in iterator order.
    318     * If the collection of predicates is empty, then this predicate returns true.
    319     *
    320     * @param <T>  the type that the predicate queries
    321     * @param predicates  a collection of predicates to check, may not be null
    322     * @return the {@code none} predicate
    323     * @throws NullPointerException if the predicates collection is null
    324     * @throws NullPointerException if any predicate in the collection is null
    325     * @see NonePredicate
    326     */
    327    public static <T> Predicate<T> nonePredicate(final Collection<? extends Predicate<? super T>> predicates) {
    328        return NonePredicate.nonePredicate(predicates);
    329    }
    330
    331    /**
    332     * Create a new Predicate that returns true if none of the specified
    333     * predicates are true.
    334     * If the array of predicates is empty, then this predicate returns true.
    335     *
    336     * @param <T>  the type that the predicate queries
    337     * @param predicates  an array of predicates to check, may not be null
    338     * @return the {@code none} predicate
    339     * @throws NullPointerException if the predicates array is null
    340     * @throws NullPointerException if any predicate in the array is null
    341     * @see NonePredicate
    342     */
    343    public static <T> Predicate<T> nonePredicate(final Predicate<? super T>... predicates) {
    344        return NonePredicate.nonePredicate(predicates);
    345    }
    346
    347    /**
    348     * Gets a Predicate that checks if the input object passed in is not null.
    349     *
    350     * @param <T>  the type that the predicate queries
    351     * @return the predicate
    352     * @see NotNullPredicate
    353     */
    354    public static <T> Predicate<T> notNullPredicate() {
    355        return NotNullPredicate.notNullPredicate();
    356    }
    357
    358    /**
    359     * Create a new Predicate that returns true if the specified predicate
    360     * returns false and vice versa.
    361     *
    362     * @param <T>  the type that the predicate queries
    363     * @param predicate  the predicate to not
    364     * @return the {@code not} predicate
    365     * @throws NullPointerException if the predicate is null
    366     * @see NotPredicate
    367     */
    368    public static <T> Predicate<T> notPredicate(final Predicate<? super T> predicate) {
    369        return NotPredicate.notPredicate(predicate);
    370    }
    371
    372    /**
    373     * Gets a Predicate that throws an exception if the input object is null,
    374     * otherwise it calls the specified Predicate. This allows null handling
    375     * behavior to be added to Predicates that don't support nulls.
    376     *
    377     * @param <T>  the type that the predicate queries
    378     * @param predicate  the predicate to wrap, may not be null
    379     * @return the predicate
    380     * @throws NullPointerException if the predicate is null.
    381     * @see NullIsExceptionPredicate
    382     */
    383    public static <T> Predicate<T> nullIsExceptionPredicate(final Predicate<? super T> predicate) {
    384        return NullIsExceptionPredicate.nullIsExceptionPredicate(predicate);
    385    }
    386
    387    /**
    388     * Gets a Predicate that returns false if the input object is null, otherwise
    389     * it calls the specified Predicate. This allows null handling behavior to
    390     * be added to Predicates that don't support nulls.
    391     *
    392     * @param <T>  the type that the predicate queries
    393     * @param predicate  the predicate to wrap, may not be null
    394     * @return the predicate
    395     * @throws NullPointerException if the predicate is null.
    396     * @see NullIsFalsePredicate
    397     */
    398    public static <T> Predicate<T> nullIsFalsePredicate(final Predicate<? super T> predicate) {
    399        return NullIsFalsePredicate.nullIsFalsePredicate(predicate);
    400    }
    401
    402    /**
    403     * Gets a Predicate that returns true if the input object is null, otherwise
    404     * it calls the specified Predicate. This allows null handling behavior to
    405     * be added to Predicates that don't support nulls.
    406     *
    407     * @param <T>  the type that the predicate queries
    408     * @param predicate  the predicate to wrap, may not be null
    409     * @return the predicate
    410     * @throws NullPointerException if the predicate is null.
    411     * @see NullIsTruePredicate
    412     */
    413    public static <T> Predicate<T> nullIsTruePredicate(final Predicate<? super T> predicate) {
    414        return NullIsTruePredicate.nullIsTruePredicate(predicate);
    415    }
    416
    417    /**
    418     * Gets a Predicate that checks if the input object passed in is null.
    419     *
    420     * @param <T>  the type that the predicate queries
    421     * @return the predicate
    422     * @see NullPredicate
    423     */
    424    public static <T> Predicate<T> nullPredicate() {
    425        return NullPredicate.nullPredicate();
    426    }
    427
    428    /**
    429     * Create a new Predicate that returns true if only one of the specified
    430     * predicates are true. The predicates are checked in iterator order.
    431     * If the collection of predicates is empty, then this predicate returns false.
    432     *
    433     * @param <T>  the type that the predicate queries
    434     * @param predicates  a collection of predicates to check, may not be null
    435     * @return the {@code one} predicate
    436     * @throws NullPointerException if the predicates collection is null
    437     * @throws NullPointerException if any predicate in the collection is null
    438     * @see OnePredicate
    439     */
    440    public static <T> Predicate<T> onePredicate(final Collection<? extends Predicate<? super T>> predicates) {
    441        return OnePredicate.onePredicate(predicates);
    442    }
    443
    444    /**
    445     * Create a new Predicate that returns true if only one of the specified
    446     * predicates are true.
    447     * If the array of predicates is empty, then this predicate returns false.
    448     *
    449     * @param <T>  the type that the predicate queries
    450     * @param predicates  an array of predicates to check, may not be null
    451     * @return the {@code one} predicate
    452     * @throws NullPointerException if the predicates array is null
    453     * @throws NullPointerException if any predicate in the array is null
    454     * @see OnePredicate
    455     */
    456    public static <T> Predicate<T> onePredicate(final Predicate<? super T>... predicates) {
    457        return OnePredicate.onePredicate(predicates);
    458    }
    459
    460    /**
    461     * Create a new Predicate that returns true if either of the specified
    462     * predicates are true.
    463     *
    464     * @param <T>  the type that the predicate queries
    465     * @param predicate1  the first predicate, may not be null
    466     * @param predicate2  the second predicate, may not be null
    467     * @return the {@code or} predicate
    468     * @throws NullPointerException if either predicate is null
    469     * @see OrPredicate
    470     */
    471    public static <T> Predicate<T> orPredicate(final Predicate<? super T> predicate1,
    472                                               final Predicate<? super T> predicate2) {
    473        return OrPredicate.orPredicate(predicate1, predicate2);
    474    }
    475
    476    // Transformed
    477    /**
    478     * Creates a predicate that transforms the input object before passing it
    479     * to the predicate.
    480     *
    481     * @param <T>  the type that the predicate queries
    482     * @param transformer  the transformer to call first
    483     * @param predicate  the predicate to call with the result of the transform
    484     * @return the predicate
    485     * @throws NullPointerException if the transformer or the predicate is null
    486     * @see TransformedPredicate
    487     * @since 3.1
    488     */
    489    public static <T> Predicate<T> transformedPredicate(final Transformer<? super T, ? extends T> transformer, final Predicate<? super T> predicate) {
    490        return TransformedPredicate.transformedPredicate(transformer, predicate);
    491    }
    492
    493    /**
    494     * Gets a Predicate that always returns true.
    495     *
    496     * @param <T>  the type that the predicate queries
    497     * @return the predicate
    498     * @see TruePredicate
    499     */
    500    public static <T> Predicate<T> truePredicate() {
    501        return TruePredicate.truePredicate();
    502    }
    503
    504    /**
    505     * Creates a Predicate that returns true the first time an object is
    506     * encountered, and false if the same object is received
    507     * again. The comparison is by equals(). A {@code null} input object
    508     * is accepted and will return true the first time, and false subsequently
    509     * as well.
    510     *
    511     * @param <T>  the type that the predicate queries
    512     * @return the predicate
    513     * @see UniquePredicate
    514     */
    515    public static <T> Predicate<T> uniquePredicate() {
    516        // must return new instance each time
    517        return UniquePredicate.uniquePredicate();
    518    }
    519
    520    /**
    521     * Don't allow instances.
    522     */
    523    private PredicateUtils() {
    524        // empty
    525    }
    526
    527}