PredicateUtils


1   /*
2    *  Copyright 2002-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.apache.commons.collections;
17  
18  import java.util.Collection  ;
19  
20  import org.apache.commons.collections.functors.AllPredicate;
21  import org.apache.commons.collections.functors.AndPredicate;
22  import org.apache.commons.collections.functors.AnyPredicate;
23  import org.apache.commons.collections.functors.EqualPredicate;
24  import org.apache.commons.collections.functors.ExceptionPredicate;
25  import org.apache.commons.collections.functors.FalsePredicate;
26  import org.apache.commons.collections.functors.IdentityPredicate;
27  import org.apache.commons.collections.functors.InstanceofPredicate;
28  import org.apache.commons.collections.functors.InvokerTransformer;
29  import org.apache.commons.collections.functors.NonePredicate;
30  import org.apache.commons.collections.functors.NotNullPredicate;
31  import org.apache.commons.collections.functors.NotPredicate;
32  import org.apache.commons.collections.functors.NullIsExceptionPredicate;
33  import org.apache.commons.collections.functors.NullIsFalsePredicate;
34  import org.apache.commons.collections.functors.NullIsTruePredicate;
35  import org.apache.commons.collections.functors.NullPredicate;
36  import org.apache.commons.collections.functors.OnePredicate;
37  import org.apache.commons.collections.functors.OrPredicate;
38  import org.apache.commons.collections.functors.TransformedPredicate;
39  import org.apache.commons.collections.functors.TransformerPredicate;
40  import org.apache.commons.collections.functors.TruePredicate;
41  import org.apache.commons.collections.functors.UniquePredicate;
42  
43  /**
44   * <code>PredicateUtils</code> provides reference implementations and utilities
45   * for the Predicate functor interface. The supplied predicates are:
46   * <ul>
47   * <li>Invoker - returns the result of a method call on the input object
48   * <li>InstanceOf - true if the object is an instanceof a class
49   * <li>Equal - true if the object equals() a specified object
50   * <li>Identity - true if the object == a specified object
51   * <li>Null - true if the object is null
52   * <li>NotNull - true if the object is not null
53   * <li>Unique - true if the object has not already been evaluated
54   * <li>And/All - true if all of the predicates are true
55   * <li>Or/Any - true if any of the predicates is true
56   * <li>Either/One - true if only one of the predicate is true
57   * <li>Neither/None - true if none of the predicates are true
58   * <li>Not - true if the predicate is false, and vice versa
59   * <li>Transformer - wraps a Transformer as a Predicate
60   * <li>True - always return true
61   * <li>False - always return false
62   * <li>Exception - always throws an exception
63   * <li>NullIsException/NullIsFalse/NullIsTrue - check for null input
64   * <li>Transformed - transforms the input before calling the predicate
65   * </ul>
66   * All the supplied predicates are Serializable.
67   *
68   * @since Commons Collections 3.0
69   * @version $Revision: 1.19 $ $Date: 2004/05/26 21:50:52 $
70   * 
71   * @author Stephen Colebourne
72   * @author Ola Berg
73   */
74  public class PredicateUtils {
75  
76      /**
77       * This class is not normally instantiated.
78       */
79      public PredicateUtils() {
80          super();
81      }
82  
83      // Simple predicates
84      //-----------------------------------------------------------------------------
85  
86      /** 
87       * Gets a Predicate that always throws an exception.
88       * This could be useful during testing as a placeholder.
89       *
90       * @see org.apache.commons.collections.functors.ExceptionPredicate
91       * 
92       * @return the predicate
93       */
94      public static Predicate exceptionPredicate() {
95          return ExceptionPredicate.INSTANCE;
96      }
97  
98      /**
99       * Gets a Predicate that always returns true.
100      * 
101      * @see org.apache.commons.collections.functors.TruePredicate
102      * 
103      * @return the predicate
104      */
105     public static Predicate truePredicate() {
106         return TruePredicate.INSTANCE;
107     }
108 
109     /**
110      * Gets a Predicate that always returns false.
111      * 
112      * @see org.apache.commons.collections.functors.FalsePredicate
113      * 
114      * @return the predicate
115      */
116     public static Predicate falsePredicate() {
117         return FalsePredicate.INSTANCE;
118     }
119 
120     /**
121      * Gets a Predicate that checks if the input object passed in is null.
122      * 
123      * @see org.apache.commons.collections.functors.NullPredicate
124      * 
125      * @return the predicate
126      */
127     public static Predicate nullPredicate() {
128         return NullPredicate.INSTANCE;
129     }
130 
131     /**
132      * Gets a Predicate that checks if the input object passed in is not null.
133      * 
134      * @see org.apache.commons.collections.functors.NotNullPredicate
135      * 
136      * @return the predicate
137      */
138     public static Predicate notNullPredicate() {
139         return NotNullPredicate.INSTANCE;
140     }
141 
142     /**
143      * Creates a Predicate that checks if the input object is equal to the
144      * specified object using equals().
145      * 
146      * @see org.apache.commons.collections.functors.EqualPredicate
147      * 
148      * @param value  the value to compare against
149      * @return the predicate
150      */
151     public static Predicate equalPredicate(Object   value) {
152         return EqualPredicate.getInstance(value);
153     }
154 
155     /**
156      * Creates a Predicate that checks if the input object is equal to the
157      * specified object by identity.
158      * 
159      * @see org.apache.commons.collections.functors.IdentityPredicate
160      * 
161      * @param value  the value to compare against
162      * @return the predicate
163      */
164     public static Predicate identityPredicate(Object   value) {
165         return IdentityPredicate.getInstance(value);
166     }
167     
168     /**
169      * Creates a Predicate that checks if the object passed in is of
170      * a particular type, using instanceof. A <code>null</code> input
171      * object will return <code>false</code>.
172      * 
173      * @see org.apache.commons.collections.functors.InstanceofPredicate
174      * 
175      * @param type  the type to check for, may not be null
176      * @return the predicate
177      * @throws IllegalArgumentException if the class is null
178      */
179     public static Predicate instanceofPredicate(Class   type) {
180         return InstanceofPredicate.getInstance(type);
181     }
182 
183     /**
184      * Creates a Predicate that returns true the first time an object is
185      * encountered, and false if the same object is received 
186      * again. The comparison is by equals(). A <code>null</code> input object
187      * is accepted and will return true the first time, and false subsequently
188      * as well.
189      * 
190      * @see org.apache.commons.collections.functors.UniquePredicate
191      * 
192      * @return the predicate
193      */
194     public static Predicate uniquePredicate() {
195         // must return new instance each time
196         return UniquePredicate.getInstance();
197     }
198 
199     /**
200      * Creates a Predicate that invokes a method on the input object.
201      * The method must return either a boolean or a non-null Boolean,
202      * and have no parameters. If the input object is null, a 
203      * PredicateException is thrown.
204      * <p>
205      * For example, <code>PredicateUtils.invokerPredicate("isEmpty");</code>
206      * will call the <code>isEmpty</code> method on the input object to 
207      * determine the predicate result.
208      * 
209      * @see org.apache.commons.collections.functors.InvokerTransformer
210      * @see org.apache.commons.collections.functors.TransformerPredicate
211      * 
212      * @param methodName  the method name to call on the input object, may not be null
213      * @return the predicate
214      * @throws IllegalArgumentException if the methodName is null.
215      */
216     public static Predicate invokerPredicate(String   methodName){
217         // reuse transformer as it has caching - this is lazy really, should have inner class here
218         return asPredicate(InvokerTransformer.getInstance(methodName));
219     }
220 
221     /**
222      * Creates a Predicate that invokes a method on the input object.
223      * The method must return either a boolean or a non-null Boolean,
224      * and have no parameters. If the input object is null, a 
225      * PredicateException is thrown.
226      * <p>
227      * For example, <code>PredicateUtils.invokerPredicate("isEmpty");</code>
228      * will call the <code>isEmpty</code> method on the input object to 
229      * determine the predicate result.
230      * 
231      * @see org.apache.commons.collections.functors.InvokerTransformer
232      * @see org.apache.commons.collections.functors.TransformerPredicate
233      * 
234      * @param methodName  the method name to call on the input object, may not be null
235      * @param paramTypes  the parameter types
236      * @param args  the arguments
237      * @return the predicate
238      * @throws IllegalArgumentException if the method name is null
239      * @throws IllegalArgumentException if the paramTypes and args don't match
240      */
241     public static Predicate invokerPredicate(String   methodName, Class  [] paramTypes, Object  [] args){
242         // reuse transformer as it has caching - this is lazy really, should have inner class here
243         return asPredicate(InvokerTransformer.getInstance(methodName, paramTypes, args));
244     }
245 
246     // Boolean combinations
247     //-----------------------------------------------------------------------------
248 
249     /**
250      * Create a new Predicate that returns true only if both of the specified
251      * predicates are true.
252      * 
253      * @see org.apache.commons.collections.functors.AndPredicate
254      * 
255      * @param predicate1  the first predicate, may not be null
256      * @param predicate2  the second predicate, may not be null
257      * @return the <code>and</code> predicate
258      * @throws IllegalArgumentException if either predicate is null
259      */
260     public static Predicate andPredicate(Predicate predicate1, Predicate predicate2) {
261         return AndPredicate.getInstance(predicate1, predicate2);
262     }
263 
264     /**
265      * Create a new Predicate that returns true only if all of the specified
266      * predicates are true.
267      * 
268      * @see org.apache.commons.collections.functors.AllPredicate
269      * 
270      * @param predicates  an array of predicates to check, may not be null
271      * @return the <code>all</code> predicate
272      * @throws IllegalArgumentException if the predicates array is null
273      * @throws IllegalArgumentException if the predicates array has less than 2 elements
274      * @throws IllegalArgumentException if any predicate in the array is null
275      */
276     public static Predicate allPredicate(Predicate[] predicates) {
277         return AllPredicate.getInstance(predicates);
278     }
279 
280     /**
281      * Create a new Predicate that returns true only if all of the specified
282      * predicates are true. The predicates are checked in iterator order.
283      * 
284      * @see org.apache.commons.collections.functors.AllPredicate
285      * 
286      * @param predicates  a collection of predicates to check, may not be null
287      * @return the <code>all</code> predicate
288      * @throws IllegalArgumentException if the predicates collection is null
289      * @throws IllegalArgumentException if the predicates collection has less than 2 elements
290      * @throws IllegalArgumentException if any predicate in the collection is null
291      */
292     public static Predicate allPredicate(Collection   predicates) {
293         return AllPredicate.getInstance(predicates);
294     }
295 
296     /**
297      * Create a new Predicate that returns true if either of the specified
298      * predicates are true.
299      * 
300      * @see org.apache.commons.collections.functors.OrPredicate
301      * 
302      * @param predicate1  the first predicate, may not be null
303      * @param predicate2  the second predicate, may not be null
304      * @return the <code>or</code> predicate
305      * @throws IllegalArgumentException if either predicate is null
306      */
307     public static Predicate orPredicate(Predicate predicate1, Predicate predicate2) {
308         return OrPredicate.getInstance(predicate1, predicate2);
309     }
310 
311     /**
312      * Create a new Predicate that returns true if any of the specified
313      * predicates are true.
314      * 
315      * @see org.apache.commons.collections.functors.AnyPredicate
316      * 
317      * @param predicates  an array of predicates to check, may not be null
318      * @return the <code>any</code> predicate
319      * @throws IllegalArgumentException if the predicates array is null
320      * @throws IllegalArgumentException if the predicates array has less than 2 elements
321      * @throws IllegalArgumentException if any predicate in the array is null
322      */
323     public static Predicate anyPredicate(Predicate[] predicates) {
324         return AnyPredicate.getInstance(predicates);
325     }
326 
327     /**
328      * Create a new Predicate that returns true if any of the specified
329      * predicates are true. The predicates are checked in iterator order.
330      * 
331      * @see org.apache.commons.collections.functors.AnyPredicate
332      * 
333      * @param predicates  a collection of predicates to check, may not be null
334      * @return the <code>any</code> predicate
335      * @throws IllegalArgumentException if the predicates collection is null
336      * @throws IllegalArgumentException if the predicates collection has less than 2 elements
337      * @throws IllegalArgumentException if any predicate in the collection is null
338      */
339     public static Predicate anyPredicate(Collection   predicates) {
340         return AnyPredicate.getInstance(predicates);
341     }
342 
343     /**
344      * Create a new Predicate that returns true if one, but not both, of the
345      * specified predicates are true.
346      * 
347      * @see org.apache.commons.collections.functors.OnePredicate
348      * 
349      * @param predicate1  the first predicate, may not be null
350      * @param predicate2  the second predicate, may not be null
351      * @return the <code>either</code> predicate
352      * @throws IllegalArgumentException if either predicate is null
353      */
354     public static Predicate eitherPredicate(Predicate predicate1, Predicate predicate2) {
355         return onePredicate(new Predicate[] { predicate1, predicate2 });
356     }
357 
358     /**
359      * Create a new Predicate that returns true if only one of the specified
360      * predicates are true.
361      * 
362      * @see org.apache.commons.collections.functors.OnePredicate
363      * 
364      * @param predicates  an array of predicates to check, may not be null
365      * @return the <code>one</code> predicate
366      * @throws IllegalArgumentException if the predicates array is null
367      * @throws IllegalArgumentException if the predicates array has less than 2 elements
368      * @throws IllegalArgumentException if any predicate in the array is null
369      */
370     public static Predicate onePredicate(Predicate[] predicates) {
371         return OnePredicate.getInstance(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      * 
378      * @see org.apache.commons.collections.functors.OnePredicate
379      * 
380      * @param predicates  a collection of predicates to check, may not be null
381      * @return the <code>one</code> predicate
382      * @throws IllegalArgumentException if the predicates collection is null
383      * @throws IllegalArgumentException if the predicates collection has less than 2 elements
384      * @throws IllegalArgumentException if any predicate in the collection is null
385      */
386     public static Predicate onePredicate(Collection   predicates) {
387         return OnePredicate.getInstance(predicates);
388     }
389 
390     /**
391      * Create a new Predicate that returns true if neither of the specified 
392      * predicates are true.
393      * 
394      * @see org.apache.commons.collections.functors.NonePredicate
395      * 
396      * @param predicate1  the first predicate, may not be null
397      * @param predicate2  the second predicate, may not be null
398      * @return the <code>neither</code> predicate
399      * @throws IllegalArgumentException if either predicate is null
400      */
401     public static Predicate neitherPredicate(Predicate predicate1, Predicate predicate2) {
402         return nonePredicate(new Predicate[] { predicate1, predicate2 });
403     }
404 
405     /**
406      * Create a new Predicate that returns true if none of the specified
407      * predicates are true.
408      * 
409      * @see org.apache.commons.collections.functors.NonePredicate
410      * 
411      * @param predicates  an array of predicates to check, may not be null
412      * @return the <code>none</code> predicate
413      * @throws IllegalArgumentException if the predicates array is null
414      * @throws IllegalArgumentException if the predicates array has less than 2 elements
415      * @throws IllegalArgumentException if any predicate in the array is null
416      */
417     public static Predicate nonePredicate(Predicate[] predicates) {
418         return NonePredicate.getInstance(predicates);
419     }
420 
421     /**
422      * Create a new Predicate that returns true if none of the specified
423      * predicates are true. The predicates are checked in iterator order.
424      * 
425      * @see org.apache.commons.collections.functors.NonePredicate
426      * 
427      * @param predicates  a collection of predicates to check, may not be null
428      * @return the <code>none</code> predicate
429      * @throws IllegalArgumentException if the predicates collection is null
430      * @throws IllegalArgumentException if the predicates collection has less than 2 elements
431      * @throws IllegalArgumentException if any predicate in the collection is null
432      */
433     public static Predicate nonePredicate(Collection   predicates) {
434         return NonePredicate.getInstance(predicates);
435     }
436 
437     /**
438      * Create a new Predicate that returns true if the specified predicate
439      * returns false and vice versa.
440      * 
441      * @see org.apache.commons.collections.functors.NotPredicate
442      * 
443      * @param predicate  the predicate to not
444      * @return the <code>not</code> predicate
445      * @throws IllegalArgumentException if the predicate is null
446      */
447     public static Predicate notPredicate(Predicate predicate) {
448         return NotPredicate.getInstance(predicate);
449     }
450 
451     // Adaptors
452     //-----------------------------------------------------------------------------
453 
454     /**
455      * Create a new Predicate that wraps a Transformer. The Transformer must
456      * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException
457      * will be thrown.
458      * 
459      * @see org.apache.commons.collections.functors.TransformerPredicate
460      * 
461      * @param transformer  the transformer to wrap, may not be null
462      * @return the transformer wrapping predicate
463      * @throws IllegalArgumentException if the transformer is null
464      */
465     public static Predicate asPredicate(Transformer transformer) {
466         return TransformerPredicate.getInstance(transformer);
467     }
468 
469     // Null handlers
470     //-----------------------------------------------------------------------------
471 
472     /**
473      * Gets a Predicate that throws an exception if the input object is null, 
474      * otherwise it calls the specified Predicate. This allows null handling 
475      * behaviour to be added to Predicates that don't support nulls.
476      * 
477      * @see org.apache.commons.collections.functors.NullIsExceptionPredicate
478      * 
479      * @param predicate  the predicate to wrap, may not be null
480      * @return the predicate
481      * @throws IllegalArgumentException if the predicate is null.
482      */
483     public static Predicate nullIsExceptionPredicate(Predicate predicate){
484         return NullIsExceptionPredicate.getInstance(predicate);
485     }
486 
487     /**
488      * Gets a Predicate that returns false if the input object is null, otherwise
489      * it calls the specified Predicate. This allows null handling behaviour to
490      * be added to Predicates that don't support nulls.
491      * 
492      * @see org.apache.commons.collections.functors.NullIsFalsePredicate
493      * 
494      * @param predicate  the predicate to wrap, may not be null
495      * @return the predicate
496      * @throws IllegalArgumentException if the predicate is null.
497      */
498     public static Predicate nullIsFalsePredicate(Predicate predicate){
499         return NullIsFalsePredicate.getInstance(predicate);
500     }
501 
502     /**
503      * Gets a Predicate that returns true if the input object is null, otherwise
504      * it calls the specified Predicate. This allows null handling behaviour to
505      * be added to Predicates that don't support nulls.
506      * 
507      * @see org.apache.commons.collections.functors.NullIsTruePredicate
508      * 
509      * @param predicate  the predicate to wrap, may not be null
510      * @return the predicate
511      * @throws IllegalArgumentException if the predicate is null.
512      */
513     public static Predicate nullIsTruePredicate(Predicate predicate){
514         return NullIsTruePredicate.getInstance(predicate);
515     }
516 
517     // Transformed
518     //-----------------------------------------------------------------------
519     /**
520      * Creates a predicate that transforms the input object before passing it
521      * to the predicate.
522      * 
523      * @see org.apache.commons.collections.functors.TransformedPredicate
524      * 
525      * @param transformer  the transformer to call first
526      * @param predicate  the predicate to call with the result of the transform
527      * @return the predicate
528      * @throws IllegalArgumentException if the transformer or the predicate is null
529      * @since Commons Collections 3.1
530      */
531     public static Predicate transformedPredicate(Transformer transformer, Predicate predicate) {
532         return TransformedPredicate.getInstance(transformer, predicate);
533     }
534 
535 }
536
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags