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}