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