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