1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.collections; 18 19 import java.util.Collection; 20 21 import org.apache.commons.collections.functors.AllPredicate; 22 import org.apache.commons.collections.functors.AndPredicate; 23 import org.apache.commons.collections.functors.AnyPredicate; 24 import org.apache.commons.collections.functors.EqualPredicate; 25 import org.apache.commons.collections.functors.ExceptionPredicate; 26 import org.apache.commons.collections.functors.FalsePredicate; 27 import org.apache.commons.collections.functors.IdentityPredicate; 28 import org.apache.commons.collections.functors.InstanceofPredicate; 29 import org.apache.commons.collections.functors.InvokerTransformer; 30 import org.apache.commons.collections.functors.NonePredicate; 31 import org.apache.commons.collections.functors.NotNullPredicate; 32 import org.apache.commons.collections.functors.NotPredicate; 33 import org.apache.commons.collections.functors.NullIsExceptionPredicate; 34 import org.apache.commons.collections.functors.NullIsFalsePredicate; 35 import org.apache.commons.collections.functors.NullIsTruePredicate; 36 import org.apache.commons.collections.functors.NullPredicate; 37 import org.apache.commons.collections.functors.OnePredicate; 38 import org.apache.commons.collections.functors.OrPredicate; 39 import org.apache.commons.collections.functors.TransformedPredicate; 40 import org.apache.commons.collections.functors.TransformerPredicate; 41 import org.apache.commons.collections.functors.TruePredicate; 42 import org.apache.commons.collections.functors.UniquePredicate; 43 44 /** 45 * <code>PredicateUtils</code> provides reference implementations and utilities 46 * for the Predicate functor interface. The supplied predicates are: 47 * <ul> 48 * <li>Invoker - returns the result of a method call on the input object 49 * <li>InstanceOf - true if the object is an instanceof a class 50 * <li>Equal - true if the object equals() a specified object 51 * <li>Identity - true if the object == a specified object 52 * <li>Null - true if the object is null 53 * <li>NotNull - true if the object is not null 54 * <li>Unique - true if the object has not already been evaluated 55 * <li>And/All - true if all of the predicates are true 56 * <li>Or/Any - true if any of the predicates is true 57 * <li>Either/One - true if only one of the predicate is true 58 * <li>Neither/None - true if none of the predicates are true 59 * <li>Not - true if the predicate is false, and vice versa 60 * <li>Transformer - wraps a Transformer as a Predicate 61 * <li>True - always return true 62 * <li>False - always return false 63 * <li>Exception - always throws an exception 64 * <li>NullIsException/NullIsFalse/NullIsTrue - check for null input 65 * <li>Transformed - transforms the input before calling the predicate 66 * </ul> 67 * All the supplied predicates are Serializable. 68 * 69 * @since Commons Collections 3.0 70 * @version $Revision: 647116 $ $Date: 2008-04-11 13:23:08 +0200 (Fri, 11 Apr 2008) $ 71 * 72 * @author Stephen Colebourne 73 * @author Ola Berg 74 */ 75 public class PredicateUtils { 76 77 /** 78 * This class is not normally instantiated. 79 */ PredicateUtils()80 public PredicateUtils() { 81 super(); 82 } 83 84 // Simple predicates 85 //----------------------------------------------------------------------------- 86 87 /** 88 * Gets a Predicate that always throws an exception. 89 * This could be useful during testing as a placeholder. 90 * 91 * @see org.apache.commons.collections.functors.ExceptionPredicate 92 * 93 * @return the predicate 94 */ exceptionPredicate()95 public static Predicate exceptionPredicate() { 96 return ExceptionPredicate.INSTANCE; 97 } 98 99 /** 100 * Gets a Predicate that always returns true. 101 * 102 * @see org.apache.commons.collections.functors.TruePredicate 103 * 104 * @return the predicate 105 */ truePredicate()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 */ falsePredicate()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 */ nullPredicate()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 */ notNullPredicate()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 */ equalPredicate(Object value)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 */ identityPredicate(Object value)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 */ instanceofPredicate(Class type)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 */ uniquePredicate()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 */ invokerPredicate(String methodName)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 */ invokerPredicate(String methodName, Class[] paramTypes, Object[] args)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 */ andPredicate(Predicate predicate1, Predicate predicate2)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 */ allPredicate(Predicate[] predicates)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 */ allPredicate(Collection predicates)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 */ orPredicate(Predicate predicate1, Predicate predicate2)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 */ anyPredicate(Predicate[] predicates)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 */ anyPredicate(Collection predicates)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 */ eitherPredicate(Predicate predicate1, Predicate predicate2)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 */ onePredicate(Predicate[] predicates)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 */ onePredicate(Collection predicates)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 */ neitherPredicate(Predicate predicate1, Predicate predicate2)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 */ nonePredicate(Predicate[] predicates)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 */ nonePredicate(Collection predicates)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 */ notPredicate(Predicate predicate)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 */ asPredicate(Transformer transformer)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 */ nullIsExceptionPredicate(Predicate predicate)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 */ nullIsFalsePredicate(Predicate predicate)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 */ nullIsTruePredicate(Predicate predicate)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 */ transformedPredicate(Transformer transformer, Predicate predicate)532 public static Predicate transformedPredicate(Transformer transformer, Predicate predicate) { 533 return TransformedPredicate.getInstance(transformer, predicate); 534 } 535 536 } 537