Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.collections4; import java.util.Collection; import org.apache.commons.collections4.functors.AllPredicate; import org.apache.commons.collections4.functors.AndPredicate; import org.apache.commons.collections4.functors.AnyPredicate; import org.apache.commons.collections4.functors.EqualPredicate; import org.apache.commons.collections4.functors.ExceptionPredicate; import org.apache.commons.collections4.functors.FalsePredicate; import org.apache.commons.collections4.functors.IdentityPredicate; import org.apache.commons.collections4.functors.InstanceofPredicate; import org.apache.commons.collections4.functors.InvokerTransformer; import org.apache.commons.collections4.functors.NonePredicate; import org.apache.commons.collections4.functors.NotNullPredicate; import org.apache.commons.collections4.functors.NotPredicate; import org.apache.commons.collections4.functors.NullIsExceptionPredicate; import org.apache.commons.collections4.functors.NullIsFalsePredicate; import org.apache.commons.collections4.functors.NullIsTruePredicate; import org.apache.commons.collections4.functors.NullPredicate; import org.apache.commons.collections4.functors.OnePredicate; import org.apache.commons.collections4.functors.OrPredicate; import org.apache.commons.collections4.functors.TransformedPredicate; import org.apache.commons.collections4.functors.TransformerPredicate; import org.apache.commons.collections4.functors.TruePredicate; import org.apache.commons.collections4.functors.UniquePredicate; /** * <code>PredicateUtils</code> provides reference implementations and utilities * for the Predicate functor interface. The supplied predicates are: * <ul> * <li>Invoker - returns the result of a method call on the input object * <li>InstanceOf - true if the object is an instanceof a class * <li>Equal - true if the object equals() a specified object * <li>Identity - true if the object == a specified object * <li>Null - true if the object is null * <li>NotNull - true if the object is not null * <li>Unique - true if the object has not already been evaluated * <li>And/All - true if all of the predicates are true * <li>Or/Any - true if any of the predicates is true * <li>Either/One - true if only one of the predicate is true * <li>Neither/None - true if none of the predicates are true * <li>Not - true if the predicate is false, and vice versa * <li>Transformer - wraps a Transformer as a Predicate * <li>True - always return true * <li>False - always return false * <li>Exception - always throws an exception * <li>NullIsException/NullIsFalse/NullIsTrue - check for null input * <li>Transformed - transforms the input before calling the predicate * </ul> * All the supplied predicates are Serializable. * * @since 3.0 * @version $Id: PredicateUtils.java 1469004 2013-04-17 17:37:03Z tn $ */ public class PredicateUtils { /** * This class is not normally instantiated. */ private PredicateUtils() { } // Simple predicates //----------------------------------------------------------------------------- /** * Gets a Predicate that always throws an exception. * This could be useful during testing as a placeholder. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.ExceptionPredicate */ public static <T> Predicate<T> exceptionPredicate() { return ExceptionPredicate.<T>exceptionPredicate(); } /** * Gets a Predicate that always returns true. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.TruePredicate */ public static <T> Predicate<T> truePredicate() { return TruePredicate.truePredicate(); } /** * Gets a Predicate that always returns false. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.FalsePredicate */ public static <T> Predicate<T> falsePredicate() { return FalsePredicate.<T>falsePredicate(); } /** * Gets a Predicate that checks if the input object passed in is null. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.NullPredicate */ public static <T> Predicate<T> nullPredicate() { return NullPredicate.nullPredicate(); } /** * Gets a Predicate that checks if the input object passed in is not null. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.NotNullPredicate */ public static <T> Predicate<T> notNullPredicate() { return NotNullPredicate.<T>notNullPredicate(); } /** * Creates a Predicate that checks if the input object is equal to the * specified object using equals(). * * @param <T> the type that the predicate queries * @param value the value to compare against * @return the predicate * @see org.apache.commons.collections4.functors.EqualPredicate */ public static <T> Predicate<T> equalPredicate(final T value) { return EqualPredicate.equalPredicate(value); } /** * Creates a Predicate that checks if the input object is equal to the * specified object by identity. * * @param <T> the type that the predicate queries * @param value the value to compare against * @return the predicate * @see org.apache.commons.collections4.functors.IdentityPredicate */ public static <T> Predicate<T> identityPredicate(final T value) { return IdentityPredicate.<T>identityPredicate(value); } /** * Creates a Predicate that checks if the object passed in is of * a particular type, using instanceof. A <code>null</code> input * object will return <code>false</code>. * * @param type the type to check for, may not be null * @return the predicate * @throws IllegalArgumentException if the class is null * @see org.apache.commons.collections4.functors.InstanceofPredicate */ public static Predicate<Object> instanceofPredicate(final Class<?> type) { return InstanceofPredicate.instanceOfPredicate(type); } /** * Creates a Predicate that returns true the first time an object is * encountered, and false if the same object is received * again. The comparison is by equals(). A <code>null</code> input object * is accepted and will return true the first time, and false subsequently * as well. * * @param <T> the type that the predicate queries * @return the predicate * @see org.apache.commons.collections4.functors.UniquePredicate */ public static <T> Predicate<T> uniquePredicate() { // must return new instance each time return UniquePredicate.<T>uniquePredicate(); } /** * Creates a Predicate that invokes a method on the input object. * The method must return either a boolean or a non-null Boolean, * and have no parameters. If the input object is null, a * PredicateException is thrown. * <p> * For example, <code>PredicateUtils.invokerPredicate("isEmpty");</code> * will call the <code>isEmpty</code> method on the input object to * determine the predicate result. * * @param <T> the type that the predicate queries * @param methodName the method name to call on the input object, may not be null * @return the predicate * @throws IllegalArgumentException if the methodName is null. * @see org.apache.commons.collections4.functors.InvokerTransformer * @see org.apache.commons.collections4.functors.TransformerPredicate */ public static <T> Predicate<T> invokerPredicate(final String methodName) { // reuse transformer as it has caching - this is lazy really, should have inner class here return asPredicate(InvokerTransformer.<Object, Boolean>invokerTransformer(methodName)); } /** * Creates a Predicate that invokes a method on the input object. * The method must return either a boolean or a non-null Boolean, * and have no parameters. If the input object is null, a * PredicateException is thrown. * <p> * For example, <code>PredicateUtils.invokerPredicate("isEmpty");</code> * will call the <code>isEmpty</code> method on the input object to * determine the predicate result. * * @param <T> the type that the predicate queries * @param methodName the method name to call on the input object, may not be null * @param paramTypes the parameter types * @param args the arguments * @return the predicate * @throws IllegalArgumentException if the method name is null * @throws IllegalArgumentException if the paramTypes and args don't match * @see org.apache.commons.collections4.functors.InvokerTransformer * @see org.apache.commons.collections4.functors.TransformerPredicate */ public static <T> Predicate<T> invokerPredicate(final String methodName, final Class<?>[] paramTypes, final Object[] args) { // reuse transformer as it has caching - this is lazy really, should have inner class here return asPredicate(InvokerTransformer.<Object, Boolean>invokerTransformer(methodName, paramTypes, args)); } // Boolean combinations //----------------------------------------------------------------------------- /** * Create a new Predicate that returns true only if both of the specified * predicates are true. * * @param <T> the type that the predicate queries * @param predicate1 the first predicate, may not be null * @param predicate2 the second predicate, may not be null * @return the <code>and</code> predicate * @throws IllegalArgumentException if either predicate is null * @see org.apache.commons.collections4.functors.AndPredicate */ public static <T> Predicate<T> andPredicate(final Predicate<? super T> predicate1, final Predicate<? super T> predicate2) { return AndPredicate.<T>andPredicate(predicate1, predicate2); } /** * Create a new Predicate that returns true only if all of the specified * predicates are true. * If the array of predicates is empty, then this predicate returns true. * * @param <T> the type that the predicate queries * @param predicates an array of predicates to check, may not be null * @return the <code>all</code> predicate * @throws IllegalArgumentException if the predicates array is null * @throws IllegalArgumentException if any predicate in the array is null * @see org.apache.commons.collections4.functors.AllPredicate */ public static <T> Predicate<T> allPredicate(final Predicate<? super T>... predicates) { return AllPredicate.allPredicate(predicates); } /** * Create a new Predicate that returns true only if all of the specified * predicates are true. The predicates are checked in iterator order. * If the collection of predicates is empty, then this predicate returns true. * * @param <T> the type that the predicate queries * @param predicates a collection of predicates to check, may not be null * @return the <code>all</code> predicate * @throws IllegalArgumentException if the predicates collection is null * @throws IllegalArgumentException if any predicate in the collection is null * @see org.apache.commons.collections4.functors.AllPredicate */ public static <T> Predicate<T> allPredicate(final Collection<? extends Predicate<T>> predicates) { return AllPredicate.allPredicate(predicates); } /** * Create a new Predicate that returns true if either of the specified * predicates are true. * * @param <T> the type that the predicate queries * @param predicate1 the first predicate, may not be null * @param predicate2 the second predicate, may not be null * @return the <code>or</code> predicate * @throws IllegalArgumentException if either predicate is null * @see org.apache.commons.collections4.functors.OrPredicate */ public static <T> Predicate<T> orPredicate(final Predicate<? super T> predicate1, final Predicate<? super T> predicate2) { return OrPredicate.<T>orPredicate(predicate1, predicate2); } /** * Create a new Predicate that returns true if any of the specified * predicates are true. * If the array of predicates is empty, then this predicate returns false. * * @param <T> the type that the predicate queries * @param predicates an array of predicates to check, may not be null * @return the <code>any</code> predicate * @throws IllegalArgumentException if the predicates array is null * @throws IllegalArgumentException if any predicate in the array is null * @see org.apache.commons.collections4.functors.AnyPredicate */ public static <T> Predicate<T> anyPredicate(final Predicate<? super T>... predicates) { return AnyPredicate.anyPredicate(predicates); } /** * Create a new Predicate that returns true if any of the specified * predicates are true. The predicates are checked in iterator order. * If the collection of predicates is empty, then this predicate returns false. * * @param <T> the type that the predicate queries * @param predicates a collection of predicates to check, may not be null * @return the <code>any</code> predicate * @throws IllegalArgumentException if the predicates collection is null * @throws IllegalArgumentException if any predicate in the collection is null * @see org.apache.commons.collections4.functors.AnyPredicate */ public static <T> Predicate<T> anyPredicate(final Collection<? extends Predicate<T>> predicates) { return AnyPredicate.anyPredicate(predicates); } /** * Create a new Predicate that returns true if one, but not both, of the * specified predicates are true. XOR * * @param <T> the type that the predicate queries * @param predicate1 the first predicate, may not be null * @param predicate2 the second predicate, may not be null * @return the <code>either</code> predicate * @throws IllegalArgumentException if either predicate is null * @see org.apache.commons.collections4.functors.OnePredicate */ public static <T> Predicate<T> eitherPredicate(final Predicate<? super T> predicate1, final Predicate<? super T> predicate2) { @SuppressWarnings("unchecked") final Predicate<T> onePredicate = PredicateUtils.<T>onePredicate(predicate1, predicate2); return onePredicate; } /** * Create a new Predicate that returns true if only one of the specified * predicates are true. * If the array of predicates is empty, then this predicate returns false. * * @param <T> the type that the predicate queries * @param predicates an array of predicates to check, may not be null * @return the <code>one</code> predicate * @throws IllegalArgumentException if the predicates array is null * @throws IllegalArgumentException if any predicate in the array is null * @see org.apache.commons.collections4.functors.OnePredicate */ public static <T> Predicate<T> onePredicate(final Predicate<? super T>... predicates) { return OnePredicate.onePredicate(predicates); } /** * Create a new Predicate that returns true if only one of the specified * predicates are true. The predicates are checked in iterator order. * If the collection of predicates is empty, then this predicate returns false. * * @param <T> the type that the predicate queries * @param predicates a collection of predicates to check, may not be null * @return the <code>one</code> predicate * @throws IllegalArgumentException if the predicates collection is null * @throws IllegalArgumentException if any predicate in the collection is null * @see org.apache.commons.collections4.functors.OnePredicate */ public static <T> Predicate<T> onePredicate(final Collection<Predicate<T>> predicates) { return OnePredicate.onePredicate(predicates); } /** * Create a new Predicate that returns true if neither of the specified * predicates are true. * * @param <T> the type that the predicate queries * @param predicate1 the first predicate, may not be null * @param predicate2 the second predicate, may not be null * @return the <code>neither</code> predicate * @throws IllegalArgumentException if either predicate is null * @see org.apache.commons.collections4.functors.NonePredicate */ public static <T> Predicate<T> neitherPredicate(final Predicate<? super T> predicate1, final Predicate<? super T> predicate2) { @SuppressWarnings("unchecked") final Predicate<T> nonePredicate = PredicateUtils.<T>nonePredicate(predicate1, predicate2); return nonePredicate; } /** * Create a new Predicate that returns true if none of the specified * predicates are true. * If the array of predicates is empty, then this predicate returns true. * * @param <T> the type that the predicate queries * @param predicates an array of predicates to check, may not be null * @return the <code>none</code> predicate * @throws IllegalArgumentException if the predicates array is null * @throws IllegalArgumentException if any predicate in the array is null * @see org.apache.commons.collections4.functors.NonePredicate */ public static <T> Predicate<T> nonePredicate(final Predicate<? super T>... predicates) { return NonePredicate.nonePredicate(predicates); } /** * Create a new Predicate that returns true if none of the specified * predicates are true. The predicates are checked in iterator order. * If the collection of predicates is empty, then this predicate returns true. * * @param <T> the type that the predicate queries * @param predicates a collection of predicates to check, may not be null * @return the <code>none</code> predicate * @throws IllegalArgumentException if the predicates collection is null * @throws IllegalArgumentException if any predicate in the collection is null * @see org.apache.commons.collections4.functors.NonePredicate */ public static <T> Predicate<T> nonePredicate(final Collection<? extends Predicate<T>> predicates) { return NonePredicate.nonePredicate(predicates); } /** * Create a new Predicate that returns true if the specified predicate * returns false and vice versa. * * @param <T> the type that the predicate queries * @param predicate the predicate to not * @return the <code>not</code> predicate * @throws IllegalArgumentException if the predicate is null * @see org.apache.commons.collections4.functors.NotPredicate */ public static <T> Predicate<T> notPredicate(final Predicate<? super T> predicate) { return NotPredicate.notPredicate(predicate); } // Adaptors //----------------------------------------------------------------------------- /** * Create a new Predicate that wraps a Transformer. The Transformer must * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException * will be thrown. * * @param <T> the type that the predicate queries * @param transformer the transformer to wrap, may not be null * @return the transformer wrapping predicate * @throws IllegalArgumentException if the transformer is null * @see org.apache.commons.collections4.functors.TransformerPredicate */ public static <T> Predicate<T> asPredicate(final Transformer<? super T, Boolean> transformer) { return TransformerPredicate.transformerPredicate(transformer); } // Null handlers //----------------------------------------------------------------------------- /** * Gets a Predicate that throws an exception if the input object is null, * otherwise it calls the specified Predicate. This allows null handling * behaviour to be added to Predicates that don't support nulls. * * @param <T> the type that the predicate queries * @param predicate the predicate to wrap, may not be null * @return the predicate * @throws IllegalArgumentException if the predicate is null. * @see org.apache.commons.collections4.functors.NullIsExceptionPredicate */ public static <T> Predicate<T> nullIsExceptionPredicate(final Predicate<? super T> predicate) { return NullIsExceptionPredicate.nullIsExceptionPredicate(predicate); } /** * Gets a Predicate that returns false if the input object is null, otherwise * it calls the specified Predicate. This allows null handling behaviour to * be added to Predicates that don't support nulls. * * @param <T> the type that the predicate queries * @param predicate the predicate to wrap, may not be null * @return the predicate * @throws IllegalArgumentException if the predicate is null. * @see org.apache.commons.collections4.functors.NullIsFalsePredicate */ public static <T> Predicate<T> nullIsFalsePredicate(final Predicate<? super T> predicate) { return NullIsFalsePredicate.nullIsFalsePredicate(predicate); } /** * Gets a Predicate that returns true if the input object is null, otherwise * it calls the specified Predicate. This allows null handling behaviour to * be added to Predicates that don't support nulls. * * @param <T> the type that the predicate queries * @param predicate the predicate to wrap, may not be null * @return the predicate * @throws IllegalArgumentException if the predicate is null. * @see org.apache.commons.collections4.functors.NullIsTruePredicate */ public static <T> Predicate<T> nullIsTruePredicate(final Predicate<? super T> predicate) { return NullIsTruePredicate.nullIsTruePredicate(predicate); } // Transformed //----------------------------------------------------------------------- /** * Creates a predicate that transforms the input object before passing it * to the predicate. * * @param <T> the type that the predicate queries * @param transformer the transformer to call first * @param predicate the predicate to call with the result of the transform * @return the predicate * @throws IllegalArgumentException if the transformer or the predicate is null * @see org.apache.commons.collections4.functors.TransformedPredicate * @since 3.1 */ public static <T> Predicate<T> transformedPredicate(final Transformer<? super T, ? extends T> transformer, final Predicate<? super T> predicate) { return TransformedPredicate.<T>transformedPredicate(transformer, predicate); } }