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