001: /*
002: * Copyright 2002-2004,2006 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections;
017:
018: import java.util.Collection;
019:
020: import org.apache.commons.collections.functors.AllPredicate;
021: import org.apache.commons.collections.functors.AndPredicate;
022: import org.apache.commons.collections.functors.AnyPredicate;
023: import org.apache.commons.collections.functors.EqualPredicate;
024: import org.apache.commons.collections.functors.ExceptionPredicate;
025: import org.apache.commons.collections.functors.FalsePredicate;
026: import org.apache.commons.collections.functors.IdentityPredicate;
027: import org.apache.commons.collections.functors.InstanceofPredicate;
028: import org.apache.commons.collections.functors.InvokerTransformer;
029: import org.apache.commons.collections.functors.NonePredicate;
030: import org.apache.commons.collections.functors.NotNullPredicate;
031: import org.apache.commons.collections.functors.NotPredicate;
032: import org.apache.commons.collections.functors.NullIsExceptionPredicate;
033: import org.apache.commons.collections.functors.NullIsFalsePredicate;
034: import org.apache.commons.collections.functors.NullIsTruePredicate;
035: import org.apache.commons.collections.functors.NullPredicate;
036: import org.apache.commons.collections.functors.OnePredicate;
037: import org.apache.commons.collections.functors.OrPredicate;
038: import org.apache.commons.collections.functors.TransformedPredicate;
039: import org.apache.commons.collections.functors.TransformerPredicate;
040: import org.apache.commons.collections.functors.TruePredicate;
041: import org.apache.commons.collections.functors.UniquePredicate;
042:
043: /**
044: * <code>PredicateUtils</code> provides reference implementations and utilities
045: * for the Predicate functor interface. The supplied predicates are:
046: * <ul>
047: * <li>Invoker - returns the result of a method call on the input object
048: * <li>InstanceOf - true if the object is an instanceof a class
049: * <li>Equal - true if the object equals() a specified object
050: * <li>Identity - true if the object == a specified object
051: * <li>Null - true if the object is null
052: * <li>NotNull - true if the object is not null
053: * <li>Unique - true if the object has not already been evaluated
054: * <li>And/All - true if all of the predicates are true
055: * <li>Or/Any - true if any of the predicates is true
056: * <li>Either/One - true if only one of the predicate is true
057: * <li>Neither/None - true if none of the predicates are true
058: * <li>Not - true if the predicate is false, and vice versa
059: * <li>Transformer - wraps a Transformer as a Predicate
060: * <li>True - always return true
061: * <li>False - always return false
062: * <li>Exception - always throws an exception
063: * <li>NullIsException/NullIsFalse/NullIsTrue - check for null input
064: * <li>Transformed - transforms the input before calling the predicate
065: * </ul>
066: * All the supplied predicates are Serializable.
067: *
068: * @since Commons Collections 3.0
069: * @version $Revision: 377508 $ $Date: 2006-02-13 22:12:33 +0000 (Mon, 13 Feb 2006) $
070: *
071: * @author Stephen Colebourne
072: * @author Ola Berg
073: */
074: public class PredicateUtils {
075:
076: /**
077: * This class is not normally instantiated.
078: */
079: public PredicateUtils() {
080: super ();
081: }
082:
083: // Simple predicates
084: //-----------------------------------------------------------------------------
085:
086: /**
087: * Gets a Predicate that always throws an exception.
088: * This could be useful during testing as a placeholder.
089: *
090: * @see org.apache.commons.collections.functors.ExceptionPredicate
091: *
092: * @return the predicate
093: */
094: public static Predicate exceptionPredicate() {
095: return ExceptionPredicate.INSTANCE;
096: }
097:
098: /**
099: * 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 instanceof Predicate(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,
242: 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,
245: paramTypes, args));
246: }
247:
248: // Boolean combinations
249: //-----------------------------------------------------------------------------
250:
251: /**
252: * Create a new Predicate that returns true only if both of the specified
253: * predicates are true.
254: *
255: * @see org.apache.commons.collections.functors.AndPredicate
256: *
257: * @param predicate1 the first predicate, may not be null
258: * @param predicate2 the second predicate, may not be null
259: * @return the <code>and</code> predicate
260: * @throws IllegalArgumentException if either predicate is null
261: */
262: public static Predicate andPredicate(Predicate predicate1,
263: Predicate predicate2) {
264: return AndPredicate.getInstance(predicate1, predicate2);
265: }
266:
267: /**
268: * Create a new Predicate that returns true only if all of the specified
269: * predicates are true.
270: * If the array of predicates is empty, then this predicate returns true.
271: *
272: * @see org.apache.commons.collections.functors.AllPredicate
273: *
274: * @param predicates an array of predicates to check, may not be null
275: * @return the <code>all</code> predicate
276: * @throws IllegalArgumentException if the predicates array is null
277: * @throws IllegalArgumentException if any predicate in the array is null
278: */
279: public static Predicate allPredicate(Predicate[] predicates) {
280: return AllPredicate.getInstance(predicates);
281: }
282:
283: /**
284: * Create a new Predicate that returns true only if all of the specified
285: * predicates are true. The predicates are checked in iterator order.
286: * If the collection of predicates is empty, then this predicate returns true.
287: *
288: * @see org.apache.commons.collections.functors.AllPredicate
289: *
290: * @param predicates a collection of predicates to check, may not be null
291: * @return the <code>all</code> predicate
292: * @throws IllegalArgumentException if the predicates collection is null
293: * @throws IllegalArgumentException if any predicate in the collection is null
294: */
295: public static Predicate allPredicate(Collection predicates) {
296: return AllPredicate.getInstance(predicates);
297: }
298:
299: /**
300: * Create a new Predicate that returns true if either of the specified
301: * predicates are true.
302: *
303: * @see org.apache.commons.collections.functors.OrPredicate
304: *
305: * @param predicate1 the first predicate, may not be null
306: * @param predicate2 the second predicate, may not be null
307: * @return the <code>or</code> predicate
308: * @throws IllegalArgumentException if either predicate is null
309: */
310: public static Predicate orPredicate(Predicate predicate1,
311: Predicate predicate2) {
312: return OrPredicate.getInstance(predicate1, predicate2);
313: }
314:
315: /**
316: * Create a new Predicate that returns true if any of the specified
317: * predicates are true.
318: * If the array of predicates is empty, then this predicate returns false.
319: *
320: * @see org.apache.commons.collections.functors.AnyPredicate
321: *
322: * @param predicates an array of predicates to check, may not be null
323: * @return the <code>any</code> predicate
324: * @throws IllegalArgumentException if the predicates array is null
325: * @throws IllegalArgumentException if any predicate in the array is null
326: */
327: public static Predicate anyPredicate(Predicate[] predicates) {
328: return AnyPredicate.getInstance(predicates);
329: }
330:
331: /**
332: * Create a new Predicate that returns true if any of the specified
333: * predicates are true. The predicates are checked in iterator order.
334: * If the collection of predicates is empty, then this predicate returns false.
335: *
336: * @see org.apache.commons.collections.functors.AnyPredicate
337: *
338: * @param predicates a collection of predicates to check, may not be null
339: * @return the <code>any</code> predicate
340: * @throws IllegalArgumentException if the predicates collection is null
341: * @throws IllegalArgumentException if any predicate in the collection is null
342: */
343: public static Predicate anyPredicate(Collection predicates) {
344: return AnyPredicate.getInstance(predicates);
345: }
346:
347: /**
348: * Create a new Predicate that returns true if one, but not both, of the
349: * specified predicates are true.
350: *
351: * @see org.apache.commons.collections.functors.OnePredicate
352: *
353: * @param predicate1 the first predicate, may not be null
354: * @param predicate2 the second predicate, may not be null
355: * @return the <code>either</code> predicate
356: * @throws IllegalArgumentException if either predicate is null
357: */
358: public static Predicate eitherPredicate(Predicate predicate1,
359: Predicate predicate2) {
360: return onePredicate(new Predicate[] { predicate1, predicate2 });
361: }
362:
363: /**
364: * Create a new Predicate that returns true if only one of the specified
365: * predicates are true.
366: * If the array of predicates is empty, then this predicate returns false.
367: *
368: * @see org.apache.commons.collections.functors.OnePredicate
369: *
370: * @param predicates an array of predicates to check, may not be null
371: * @return the <code>one</code> predicate
372: * @throws IllegalArgumentException if the predicates array is null
373: * @throws IllegalArgumentException if any predicate in the array is null
374: */
375: public static Predicate onePredicate(Predicate[] predicates) {
376: return OnePredicate.getInstance(predicates);
377: }
378:
379: /**
380: * Create a new Predicate that returns true if only one of the specified
381: * predicates are true. The predicates are checked in iterator order.
382: * If the collection of predicates is empty, then this predicate returns false.
383: *
384: * @see org.apache.commons.collections.functors.OnePredicate
385: *
386: * @param predicates a collection of predicates to check, may not be null
387: * @return the <code>one</code> predicate
388: * @throws IllegalArgumentException if the predicates collection is null
389: * @throws IllegalArgumentException if any predicate in the collection is null
390: */
391: public static Predicate onePredicate(Collection predicates) {
392: return OnePredicate.getInstance(predicates);
393: }
394:
395: /**
396: * Create a new Predicate that returns true if neither of the specified
397: * predicates are true.
398: *
399: * @see org.apache.commons.collections.functors.NonePredicate
400: *
401: * @param predicate1 the first predicate, may not be null
402: * @param predicate2 the second predicate, may not be null
403: * @return the <code>neither</code> predicate
404: * @throws IllegalArgumentException if either predicate is null
405: */
406: public static Predicate neitherPredicate(Predicate predicate1,
407: Predicate predicate2) {
408: return nonePredicate(new Predicate[] { predicate1, predicate2 });
409: }
410:
411: /**
412: * Create a new Predicate that returns true if none of the specified
413: * predicates are true.
414: * If the array of predicates is empty, then this predicate returns true.
415: *
416: * @see org.apache.commons.collections.functors.NonePredicate
417: *
418: * @param predicates an array of predicates to check, may not be null
419: * @return the <code>none</code> predicate
420: * @throws IllegalArgumentException if the predicates array is null
421: * @throws IllegalArgumentException if any predicate in the array is null
422: */
423: public static Predicate nonePredicate(Predicate[] predicates) {
424: return NonePredicate.getInstance(predicates);
425: }
426:
427: /**
428: * Create a new Predicate that returns true if none of the specified
429: * predicates are true. The predicates are checked in iterator order.
430: * If the collection of predicates is empty, then this predicate returns true.
431: *
432: * @see org.apache.commons.collections.functors.NonePredicate
433: *
434: * @param predicates a collection of predicates to check, may not be null
435: * @return the <code>none</code> predicate
436: * @throws IllegalArgumentException if the predicates collection is null
437: * @throws IllegalArgumentException if any predicate in the collection is null
438: */
439: public static Predicate nonePredicate(Collection predicates) {
440: return NonePredicate.getInstance(predicates);
441: }
442:
443: /**
444: * Create a new Predicate that returns true if the specified predicate
445: * returns false and vice versa.
446: *
447: * @see org.apache.commons.collections.functors.NotPredicate
448: *
449: * @param predicate the predicate to not
450: * @return the <code>not</code> predicate
451: * @throws IllegalArgumentException if the predicate is null
452: */
453: public static Predicate notPredicate(Predicate predicate) {
454: return NotPredicate.getInstance(predicate);
455: }
456:
457: // Adaptors
458: //-----------------------------------------------------------------------------
459:
460: /**
461: * Create a new Predicate that wraps a Transformer. The Transformer must
462: * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException
463: * will be thrown.
464: *
465: * @see org.apache.commons.collections.functors.TransformerPredicate
466: *
467: * @param transformer the transformer to wrap, may not be null
468: * @return the transformer wrapping predicate
469: * @throws IllegalArgumentException if the transformer is null
470: */
471: public static Predicate asPredicate(Transformer transformer) {
472: return TransformerPredicate.getInstance(transformer);
473: }
474:
475: // Null handlers
476: //-----------------------------------------------------------------------------
477:
478: /**
479: * Gets a Predicate that throws an exception if the input object is null,
480: * otherwise it calls the specified Predicate. This allows null handling
481: * behaviour to be added to Predicates that don't support nulls.
482: *
483: * @see org.apache.commons.collections.functors.NullIsExceptionPredicate
484: *
485: * @param predicate the predicate to wrap, may not be null
486: * @return the predicate
487: * @throws IllegalArgumentException if the predicate is null.
488: */
489: public static Predicate nullIsExceptionPredicate(Predicate predicate) {
490: return NullIsExceptionPredicate.getInstance(predicate);
491: }
492:
493: /**
494: * Gets a Predicate that returns false if the input object is null, otherwise
495: * it calls the specified Predicate. This allows null handling behaviour to
496: * be added to Predicates that don't support nulls.
497: *
498: * @see org.apache.commons.collections.functors.NullIsFalsePredicate
499: *
500: * @param predicate the predicate to wrap, may not be null
501: * @return the predicate
502: * @throws IllegalArgumentException if the predicate is null.
503: */
504: public static Predicate nullIsFalsePredicate(Predicate predicate) {
505: return NullIsFalsePredicate.getInstance(predicate);
506: }
507:
508: /**
509: * Gets a Predicate that returns true if the input object is null, otherwise
510: * it calls the specified Predicate. This allows null handling behaviour to
511: * be added to Predicates that don't support nulls.
512: *
513: * @see org.apache.commons.collections.functors.NullIsTruePredicate
514: *
515: * @param predicate the predicate to wrap, may not be null
516: * @return the predicate
517: * @throws IllegalArgumentException if the predicate is null.
518: */
519: public static Predicate nullIsTruePredicate(Predicate predicate) {
520: return NullIsTruePredicate.getInstance(predicate);
521: }
522:
523: // Transformed
524: //-----------------------------------------------------------------------
525: /**
526: * Creates a predicate that transforms the input object before passing it
527: * to the predicate.
528: *
529: * @see org.apache.commons.collections.functors.TransformedPredicate
530: *
531: * @param transformer the transformer to call first
532: * @param predicate the predicate to call with the result of the transform
533: * @return the predicate
534: * @throws IllegalArgumentException if the transformer or the predicate is null
535: * @since Commons Collections 3.1
536: */
537: public static Predicate transformedPredicate(
538: Transformer transformer, Predicate predicate) {
539: return TransformedPredicate.getInstance(transformer, predicate);
540: }
541:
542: }
|