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 }