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