1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15.functors.predicate;
17
18
19 import net.sf.collections15.Predicate;
20 import net.sf.collections15.Transformer;
21 import net.sf.collections15.functors.transformer.InvokerTransformer;
22
23 import java.util.Collection;
24
25 /***
26 * <code>PredicateUtils</code> provides reference implementations and utilities
27 * for the <code>Predicate</code> functor interface. The supplied
28 * <code>Predicate</code>s are: <ul> <li>Invoker - Returns the result of a
29 * method call on the input object (the return type of the method must be
30 * <code>boolean</code> or <code>Boolean</code>).</li> <li>InstanceOf - Returns
31 * <code>true</code> only if the input object is an instance of a specified
32 * class.</li> <li>Equal - Returns <code>true</code> only if the input object is
33 * equal to a specified object (according to the <code>Object.equals(Object)
34 * contract).</li> <li>Same - Returns <code>true</code> only if the input object
35 * is the same as a specified object (i.e. the input and specified references
36 * refer to the same object instance).</li> <li>Null - Returns <code>true</code>
37 * only if the input object is <code>null</code>.</li> <li>NotNull - Returns
38 * <code>true</code> only if the input object is not <code>null</code>.</li>
39 * <li>Unique - Returns <code>true</code> only if the input object has not
40 * already been evaluated by the <code>Predicate</code>.</li> <li>And/All -
41 * Returns <code>true</code> only if all of the decorated
42 * <code>Predicate</code>s return <code>true</code>.</li> <li>Or/Any - Returns
43 * <code>true</code> if any of the decorated <code>Predicate</code>s return
44 * <code>true</code>.</li> <li>Either/One - Returns <code>true</code> if only
45 * one of the decorated <code>Predicate</code>s returns <code>true</code>.</li>
46 * <li>Neither/None - Returns <code>true</code> only if none of the decorated
47 * <code>Predicate</code>s return <code>true</code>.</li> <li>Not - Retuns the
48 * opposite of a decorated <code>Predicate</code>.</li> <li>Transformer - Wraps
49 * a <code>Transformer</code> whose output type is <code>Boolean</code>.</li>
50 * <li>True - Always returns <code>true</code>.</li> <li>False - Always return
51 * <code>false</code>.</li> <li>Exception - Always throws an exception.</li>
52 * <li>NullIsException/NullIsFalse/NullIsTrue - Decorates an existing
53 * <code>Predicate</code> with specific handling for a <code>null</code> input
54 * object.</li> <li>Transformed - Transforms the input object before calling a
55 * decorated <code>Predicate</code>.</li> </ul> All of the supplied predicates
56 * are <code>Serializable</code>.
57 *
58 * @author Stephen Colebourne
59 * @author Ola Berg
60 * @author Chris Lambrou (port to Java 5.0)
61 * @since Collections15 1.0
62 */
63 public class PredicateUtils
64 {
65
66 /***
67 * Protected constructor prevents direct instantiation, but allows users to
68 * extend this library to provide their own augmented static library class.
69 */
70 protected PredicateUtils()
71 {
72 }
73
74 /***
75 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
76 * method always throws an exception.
77 *
78 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
79 * method always throws an exception.
80 *
81 * @see ExceptionPredicate
82 * @since Collections 1.0
83 */
84 public static <T> Predicate<T> exceptionPredicate()
85 {
86 return ExceptionPredicate.getInstance();
87 }
88
89 /***
90 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
91 * method always returns <code>true</code>.
92 *
93 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
94 * method always returns <code>true</code>.
95 *
96 * @see TruePredicate
97 * @since Collections 1.0
98 */
99 public static <T> Predicate<T> truePredicate()
100 {
101 return TruePredicate.getInstance();
102 }
103
104 /***
105 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
106 * method always returns <code>false</code>.
107 *
108 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
109 * method always returns <code>false</code>.
110 *
111 * @see FalsePredicate
112 * @since Collections 1.0
113 */
114 public static <T> Predicate<T> falsePredicate()
115 {
116 return FalsePredicate.getInstance();
117 }
118
119 /***
120 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
121 * method returns <code>true</code> only if the input object is
122 * <code>null</code>.
123 *
124 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
125 * method returns <code>true</code> only if the input object is
126 * <code>null</code>.
127 *
128 * @see NullPredicate
129 * @since Collections 1.0
130 */
131 public static <T> Predicate<T> nullPredicate()
132 {
133 return NullPredicate.getInstance();
134 }
135
136 /***
137 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
138 * method returns <code>true</code> only if the input object is not
139 * <code>null</code>.
140 *
141 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
142 * method returns <code>true</code> only if the input object is not
143 * <code>null</code>.
144 *
145 * @see NotNullPredicate
146 * @since Collections 1.0
147 */
148 public static <T> Predicate<T> notNullPredicate()
149 {
150 return NotNullPredicate.getInstance();
151 }
152
153 /***
154 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
155 * method returns <code>true</code> only if the input object is equal to the
156 * specified value, according to the <code>Object.equals(Object)</code>
157 * contract.
158 *
159 * @param value The object to which input objects are compared.
160 *
161 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
162 * method returns <code>true</code> only if the input object is
163 * equal to the specified value, according to the
164 * <code>Object.equals(Object)</code> contract.
165 *
166 * @throws IllegalArgumentException Thrown if the specified value object is
167 * <code>null</code>.
168 * @see EqualPredicate
169 * @see #samePredicate
170 * @since Collections 1.0
171 */
172 public static <T> Predicate<T> equalPredicate(T value)
173 {
174 return EqualPredicate.getInstance(value);
175 }
176
177 /***
178 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
179 * method returns <code>true</code> only if the input object is the same as
180 * the specified value (i.e. only if the input object reference and the
181 * value object reference both refer to the same object instance).
182 *
183 * @param value The object to which input objects are compared.
184 *
185 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
186 * method returns <code>true</code> only if the input object is the
187 * same as the specified value (i.e. only if the input object
188 * reference and the value object reference both refer to the same
189 * object instance).
190 *
191 * @throws IllegalArgumentException Thrown if the specified value object is
192 * <code>null</code>.
193 * @see SamePredicate
194 * @see #equalPredicate
195 * @since Collections 1.0
196 */
197 public static <T> Predicate<T> samePredicate(T value)
198 {
199 return SamePredicate.getInstance(value);
200 }
201
202 /***
203 * Returns a <code>Predicate</code> instance whose <code>evaluate</code>
204 * method returns <code>true</code> only if the input object is an instance
205 * of the specified type.
206 *
207 * @param type The type to compare input objects to.
208 *
209 * @return A <code>Predicate</code> instance whose <code>evaluate</code>
210 * method returns <code>true</code> only if the input object is an
211 * instance of the specified type.
212 *
213 * @throws IllegalArgumentException Thrown if the specified type is
214 * <code>null</code>.
215 * @see InstanceofPredicate
216 * @since Collections 1.0
217 */
218 public static <T> Predicate<T> instanceofPredicate(Class<? extends T> type)
219 {
220 return InstanceofPredicate.getInstance(type);
221 }
222
223 /***
224 * Returns a <code>Predicate</code> which returns <code>true</code> the
225 * first time any given object is evaluated, and returns <code>false</code>
226 * each time the same object is subsequently evaluated</code>.
227 *
228 * @return A <code>Predicate</code> which returns <code>true</code> the
229 * first time any given object is evaluated, and returns
230 * <code>false</code> each time the same object is subsequently
231 * evaluated</code>.
232 *
233 * @see UniquePredicate
234 */
235 public static <T> Predicate<T> uniquePredicate()
236 {
237 return UniquePredicate.getInstance();
238 }
239
240 /***
241 * Returns a <code>Predicate</code> that invokes a method on the input
242 * object, which must return either a <code>boolean</code> or
243 * <code>Boolean</code>, and have no parameters.
244 * <p/>
245 * For example, <code>PredicateUtils.invokerPredicate("isEmpty");</code>
246 * will call the <code>isEmpty</code> method on the input object to
247 * determine the predicate result.
248 * <p/>
249 * If the input object is <code>null</code>, or does not have the named
250 * method with the appropriate signature, an exception is thrown.
251 *
252 * @param methodName The method name to call on the input object.
253 *
254 * @return A <code>Predicate</code> that invokes a method on the input
255 * object, which must return either a <code>boolean</code> or
256 * <code>Boolean</code>, and have no parameters.
257 *
258 * @throws IllegalArgumentException If the method name is <code>null</code>.
259 * @see InvokerTransformer
260 * @see TransformerPredicate
261 */
262 public static <T> Predicate<T> invokerPredicate(String methodName)
263 {
264 Transformer<T, Boolean> transformer = InvokerTransformer.getInstance(methodName);
265 return asPredicate(transformer);
266 }
267
268 /***
269 * Returns a <code>Predicate</code> that invokes a method on the input
270 * object, which must return either a <code>boolean</code> or
271 * <code>Boolean</code>, and have the specified parameters.
272 * <p/>
273 * If the input object is <code>null</code>, or does not have the named
274 * method with the appropriate signature, an exception is thrown.
275 *
276 * @param methodName The method name to call on the input object.
277 * @param paramTypes The types of the arguments of the method to invoke on
278 * the input object.
279 * @param args The arguments to pass to the method invoked on the
280 * input object.
281 *
282 * @return A <code>Predicate</code> that invokes a method on the input
283 * object, which must return either a <code>boolean</code> or
284 * <code>Boolean</code>, and have the specified parameters.
285 *
286 * @throws IllegalArgumentException If the method name is <code>null</code>.
287 * @throws IllegalArgumentException If <code>paramTypes</code> is
288 * <code>null</code>, or contains any
289 * <code>null</code> classes.
290 * @throws IllegalArgumentException If <code>args</code> is <code>null</code>,
291 * contains a different number of elements
292 * to <code>paramTypes</code>, or if any of
293 * its elements doen't match the
294 * corresponding type in <code>paramTypes</code>.
295 * @see InvokerTransformer
296 * @see TransformerPredicate
297 */
298 public static <T> Predicate<T> invokerPredicate(String methodName, Class[] paramTypes, Object[] args)
299 {
300 Transformer<T, Boolean> transformer = InvokerTransformer.getInstance(methodName, paramTypes, args);
301 return asPredicate(transformer);
302 }
303
304 /***
305 * Returns a <code>Predicate</code> that wraps the specified collection of
306 * <code>Predicate</code>s, and which returns <code>true</code> only if all
307 * of the specified <code>Predicate</code>s return <code>true</code>.
308 *
309 * @param predicates The <cod>Predicate</code>s to wrap. The contents of the
310 * collection are defensively copied by the new instance.
311 *
312 * @return A <code>Predicate</code> instance that will evaluate to
313 * <code>true</code> unless any of the wrapped <code>Predicate</code>s
314 * evaluate to <code>false</code>.
315 *
316 * @throws IllegalArgumentException Thrown if the collection, or any of its
317 * elements are <code>null</code>. The
318 * collection may be empty, however, in
319 * which case the resulting <code>Predicate</code>
320 * will always return <code>true</code>.
321 * @see AllPredicate
322 */
323 public static <T> Predicate<T> allPredicate(Collection<Predicate<? super T>> predicates)
324 {
325 return AllPredicate.getInstance(predicates);
326 }
327
328 /***
329 * Returns a <code>Predicate</code> that wraps the specified collection of
330 * <code>Predicate</code>s, and which returns <code>true</code> if any one
331 * of the specified <code>Predicate</code>s return <code>true</code>.
332 *
333 * @param predicates The <cod>Predicate</code>s to wrap. The contents of the
334 * collection are defensively copied by the new instance.
335 *
336 * @return A <code>Predicate</code> instance that will evaluate to
337 * <code>true</code> if any of the wrapped <code>Predicate</code>s
338 * evaluate to <code>true</code>.
339 *
340 * @throws IllegalArgumentException Thrown if the collection, or any of its
341 * elements are <code>null</code>. The
342 * collection may be empty, however, in
343 * which case the resulting <code>AnyPredicate</code>
344 * will always return <code>false</code>.
345 * @see AnyPredicate
346 */
347 public static <T> Predicate<T> anyPredicate(Collection<Predicate<? super T>> predicates)
348 {
349 return AnyPredicate.getInstance(predicates);
350 }
351
352 /***
353 * Returns a <code>Predicate</code> that wraps the specified collection of
354 * <code>Predicate</code>s, and which returns <code>true</code> if only one
355 * of the specified <code>Predicate</code>s return <code>true</code>.
356 *
357 * @param predicates The <cod>Predicate</code>s to wrap. The contents of the
358 * collection are defensively copied by the new instance.
359 *
360 * @return A <code>Predicate</code> instance that will only evaluate to
361 * <code>true</code> if exactly one of the wrapped
362 * <code>Predicate</code>s evaluates to <code>true</code>.
363 *
364 * @throws IllegalArgumentException Thrown if the collection, or any of its
365 * elements are <code>null</code>. The
366 * collection may be empty, however, in
367 * which case the resulting <code>AnyPredicate</code>
368 * will always return <code>false</code>.
369 * @see OnePredicate
370 */
371 public static <T> Predicate<T> onePredicate(Collection<Predicate<? super T>> predicates)
372 {
373 return OnePredicate.getInstance(predicates);
374 }
375
376 /***
377 * Returns a <code>Predicate</code> that wraps the specified collection of
378 * <code>Predicate</code>s, and which returns <code>true</code> unless any
379 * one of the specified <code>Predicate</code>s return <code>true</code>.
380 *
381 * @param predicates The <cod>Predicate</code>s to wrap. The contents of the
382 * collection are defensively copied by the new instance.
383 *
384 * @return A <code>Predicate</code> instance that will evaluate to
385 * <code>true</code> unless any of the wrapped <code>Predicate</code>s
386 * evaluate to <code>true</code>.
387 *
388 * @throws IllegalArgumentException Thrown if the collection, or any of its
389 * elements are <code>null</code>. The
390 * collection may be empty, however, in
391 * which case the resulting <code>AnyPredicate</code>
392 * will always return <code>true</code>.
393 * @see NonePredicate
394 */
395 public static <T> Predicate<T> nonePredicate(Collection<Predicate<? super T>> predicates)
396 {
397 return NonePredicate.getInstance(predicates);
398 }
399
400 /***
401 * Returns a <code>Predicate</code> whose <code>evaluate</code> method
402 * returns the inverse of the decorated <code>Predicate</code>'s
403 * <code>evaluate</code> method.
404 *
405 * @param predicate The decorated <code>Predicate</code>.
406 *
407 * @throws IllegalArgumentException Thrown if the decorated <code>Predicate</code>
408 * is <code>null</code>.
409 */
410 public static <T> Predicate<T> notPredicate(Predicate<T> predicate)
411 {
412 return NotPredicate.getInstance(predicate);
413 }
414
415 /***
416 * Returns a <code>Predicate</code> that evaluates input objects using the
417 * specified <code>Transformer</code>. The <code>Predicate</code> evaluates
418 * <code>true</code> if the <code>Transformer</code> returns
419 * <code>Boolean.TRUE</code>, and evaluates to <code>false</code> if the
420 * <code>Transformer</code> returns <code>Boolean.False</code> or
421 * <code>null</code>.
422 *
423 * @param transformer The <code>Transformer</code> to use.
424 *
425 * @return A <code>Predicate</code> that evaluates input objects using the
426 * specified <code>Transformer</code>.
427 *
428 * @throws IllegalArgumentException Thrown if the <code>transformer</code>
429 * argument is <code>null</code>.
430 */
431 public static <T> Predicate<T> asPredicate(Transformer<T, Boolean> transformer)
432 {
433 return TransformerPredicate.getInstance(transformer);
434 }
435
436 /***
437 * Returns a <code>Predicate</code> that decorates the specified
438 * <code>Predicate</code>, throwing an exception for any <code>null</code>
439 * input object.
440 *
441 * @param predicate The decorated <code>Predicate</code> that is delgated to
442 * if the <code>null</code> check doesn't throw an
443 * exception.
444 *
445 * @return A <code>Predicate</code> that decorates the specified
446 * <code>Predicate</code>, throwing an exception for any
447 * <code>null</code> input object.
448 *
449 * @throws IllegalArgumentException Thrown if the specified <code>Predicate</code>
450 * to decorate is <code>null</code>.
451 * @see NullIsExceptionPredicate
452 */
453 public static <T> Predicate<T> nullIsExceptionPredicate(Predicate<T> predicate)
454 {
455 return NullIsExceptionPredicate.getInstance(predicate);
456 }
457
458 /***
459 * Returns a <code>Predicate</code> that decorates the specified
460 * <code>Predicate</code>, returning <code>false</code> for any
461 * <code>null</code> input object.
462 *
463 * @param predicate The decorated <code>Predicate</code> that is delgated to
464 * if the <code>null</code> check doesn't cause
465 * <code>false</code> to be returned.
466 *
467 * @return A <code>Predicate</code> that decorates the specified
468 * <code>Predicate</code>, returning <code>false</code> for any
469 * <code>null</code> input object.
470 *
471 * @throws IllegalArgumentException Thrown if the specified <code>Predicate</code>
472 * to decorate is <code>null</code>.
473 * @see NullIsFalsePredicate
474 */
475 public static <T> Predicate<T> nullIsFalsePredicate(Predicate<T> predicate)
476 {
477 return NullIsFalsePredicate.getInstance(predicate);
478 }
479
480 /***
481 * Returns a <code>Predicate</code> that decorates the specified
482 * <code>Predicate</code>, returning <code>true</code> for any
483 * <code>null</code> input object.
484 *
485 * @param predicate The decorated <code>Predicate</code> that is delgated to
486 * if the <code>null</code> check doesn't cause
487 * <code>true</code> to be returned.
488 *
489 * @return A <code>Predicate</code> that decorates the specified
490 * <code>Predicate</code>, returning <code>true</code> for any
491 * <code>null</code> input object.
492 *
493 * @throws IllegalArgumentException Thrown if the specified <code>Predicate</code>
494 * to decorate is <code>null</code>.
495 * @see NullIsTruePredicate
496 */
497 public static <T> Predicate<T> nullIsTruePredicate(Predicate<T> predicate)
498 {
499 return NullIsTruePredicate.getInstance(predicate);
500 }
501
502 /***
503 * Returns a <code>Predicate</code> whose <code>evaluate</code> method
504 * transforms an input object and evaluates the result using another
505 * <code>Predicate</code> instance.
506 *
507 * @param transformer The <code>Transformer</code> used to transform an
508 * input object prior to evaluation.
509 * @param predicate The <code>Predicate</code> used to evaluate the
510 * transformed input object.
511 *
512 * @return A <code>Predicate</code> whose <code>evaluate</code> method
513 * transforms an input object and evaluates the result using another
514 * <code>Predicate</code> instance.
515 *
516 * @throws IllegalArgumentException If either argument is <code>null</code>.
517 * @see TransformedPredicate
518 * @since Collections15 1.0
519 */
520 public static <E, D> Predicate<E> transformedPredicate(Transformer<? super E, ? extends D> transformer, Predicate<? super D> predicate)
521 {
522 return TransformedPredicate.getInstance(transformer, predicate);
523 }
524
525 }