/* * 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.lang3; import java.io.IOException; import java.io.UncheckedIOException; import java.lang.reflect.UndeclaredThrowableException; import java.util.Collection; import java.util.Objects; import java.util.concurrent.Callable; import java.util.function.BiConsumer; import java.util.function.BiFunction; import java.util.function.BiPredicate; import java.util.function.Consumer; import java.util.function.Function; import java.util.function.Predicate; import java.util.function.Supplier; import java.util.stream.Stream; import org.apache.commons.lang3.Streams.FailableStream; import org.apache.commons.lang3.function.FailableBooleanSupplier; /** * This class provides utility functions, and classes for working with the * {@code java.util.function} package, or more generally, with Java 8 lambdas. * More specifically, it attempts to address the fact that lambdas are supposed * not to throw Exceptions, at least not checked Exceptions, AKA instances of * {@link Exception}. This enforces the use of constructs like: * *
 * {
 * 	@code
 * 	Consumer consumer = m -> {
 * 		try {
 * 			m.invoke(o, args);
 * 		} catch (Throwable t) {
 * 			throw Functions.rethrow(t);
 * 		}
 * 	};
 * }
 * 
* *

* By replacing a {@link java.util.function.Consumer Consumer<O>} with a * {@link FailableConsumer FailableConsumer<O,? extends Throwable>}, this * can be written like follows: *

* *
 * {@code
 *   Functions.accept((m) -> m.invoke(o,args));
 * }
 * 
* *

* Obviously, the second version is much more concise and the spirit of Lambda * expressions is met better than the second version. *

* * @since 3.9 * @deprecated Use {@link org.apache.commons.lang3.function.Failable}. */ @Deprecated public class Functions { /** * A functional interface like {@link BiConsumer} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Consumed type 1. * @param Consumed type 2. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableBiConsumer}. */ @Deprecated @FunctionalInterface public interface FailableBiConsumer { /** * Accepts the consumer. * * @param object1 the first parameter for the consumable to accept * @param object2 the second parameter for the consumable to accept * @throws T Thrown when the consumer fails. */ void accept(O1 object1, O2 object2) throws T; } /** * A functional interface like {@link BiFunction} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Input type 1. * @param Input type 2. * @param Return type. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableBiFunction}. */ @Deprecated @FunctionalInterface public interface FailableBiFunction { /** * Applies this function. * * @param input1 the first input for the function * @param input2 the second input for the function * @return the result of the function * @throws T Thrown when the function fails. */ R apply(O1 input1, O2 input2) throws T; } /** * A functional interface like {@link BiPredicate} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Predicate type 1. * @param Predicate type 2. * @param Thrown exception. * @deprecated Use * {@link org.apache.commons.lang3.function.FailableBiPredicate}. */ @Deprecated @FunctionalInterface public interface FailableBiPredicate { /** * Tests the predicate. * * @param object1 the first object to test the predicate on * @param object2 the second object to test the predicate on * @return the predicate's evaluation * @throws T if the predicate fails */ boolean test(O1 object1, O2 object2) throws T; } /** * A functional interface like {@link java.util.concurrent.Callable} that * declares a {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Return type. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableCallable}. */ @Deprecated @FunctionalInterface public interface FailableCallable { /** * Calls the callable. * * @return The value returned from the callable * @throws T if the callable fails */ R call() throws T; } /** * A functional interface like {@link Consumer} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Consumed type 1. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableConsumer}. */ @Deprecated @FunctionalInterface public interface FailableConsumer { /** * Accepts the consumer. * * @param object the parameter for the consumable to accept * @throws T Thrown when the consumer fails. */ void accept(O object) throws T; } /** * A functional interface like {@link Function} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Input type 1. * @param Return type. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableFunction}. */ @Deprecated @FunctionalInterface public interface FailableFunction { /** * Applies this function. * * @param input the input for the function * @return the result of the function * @throws T Thrown when the function fails. */ R apply(I input) throws T; } /** * A functional interface like {@link Predicate} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Predicate type 1. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailablePredicate}. */ @Deprecated @FunctionalInterface public interface FailablePredicate { /** * Tests the predicate. * * @param object the object to test the predicate on * @return the predicate's evaluation * @throws T if the predicate fails */ boolean test(I object) throws T; } /** * A functional interface like {@link Runnable} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableRunnable}. */ @Deprecated @FunctionalInterface public interface FailableRunnable { /** * Runs the function. * * @throws T Thrown when the function fails. */ void run() throws T; } /** * A functional interface like {@link Supplier} that declares a * {@code Throwable}. * *

* TODO for 4.0: Move to org.apache.commons.lang3.function. *

* * @param Return type. * @param Thrown exception. * @deprecated Use {@link org.apache.commons.lang3.function.FailableSupplier}. */ @Deprecated @FunctionalInterface public interface FailableSupplier { /** * Supplies an object * * @return a result * @throws T if the supplier fails */ R get() throws T; } /** * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. * * @param consumer the consumer to consume * @param object1 the first object to consume by {@code consumer} * @param object2 the second object to consume by {@code consumer} * @param the type of the first argument the consumer accepts * @param the type of the second argument the consumer accepts * @param the type of checked exception the consumer may throw */ public static void accept(final FailableBiConsumer consumer, final O1 object1, final O2 object2) { run(() -> consumer.accept(object1, object2)); } /** * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. * * @param consumer the consumer to consume * @param object the object to consume by {@code consumer} * @param the type the consumer accepts * @param the type of checked exception the consumer may throw */ public static void accept(final FailableConsumer consumer, final O object) { run(() -> consumer.accept(object)); } /** * Applies a function and rethrows any exception as a {@link RuntimeException}. * * @param function the function to apply * @param input1 the first input to apply {@code function} on * @param input2 the second input to apply {@code function} on * @param the type of the first argument the function accepts * @param the type of the second argument the function accepts * @param the return type of the function * @param the type of checked exception the function may throw * @return the value returned from the function */ public static O apply(final FailableBiFunction function, final O1 input1, final O2 input2) { return get(() -> function.apply(input1, input2)); } /** * Applies a function and rethrows any exception as a {@link RuntimeException}. * * @param function the function to apply * @param input the input to apply {@code function} on * @param the type of the argument the function accepts * @param the return type of the function * @param the type of checked exception the function may throw * @return the value returned from the function */ public static O apply(final FailableFunction function, final I input) { return get(() -> function.apply(input)); } /** * Converts the given {@link FailableBiConsumer} into a standard * {@link BiConsumer}. * * @param the type of the first argument of the consumers * @param the type of the second argument of the consumers * @param consumer a failable {@code BiConsumer} * @return a standard {@code BiConsumer} * @since 3.10 */ public static BiConsumer asBiConsumer(final FailableBiConsumer consumer) { return (input1, input2) -> accept(consumer, input1, input2); } /** * Converts the given {@link FailableBiFunction} into a standard * {@link BiFunction}. * * @param the type of the first argument of the input of the functions * @param the type of the second argument of the input of the functions * @param the type of the output of the functions * @param function a {@code FailableBiFunction} * @return a standard {@code BiFunction} * @since 3.10 */ public static BiFunction asBiFunction(final FailableBiFunction function) { return (input1, input2) -> apply(function, input1, input2); } /** * Converts the given {@link FailableBiPredicate} into a standard * {@link BiPredicate}. * * @param the type of the first argument used by the predicates * @param the type of the second argument used by the predicates * @param predicate a {@code FailableBiPredicate} * @return a standard {@code BiPredicate} * @since 3.10 */ public static BiPredicate asBiPredicate(final FailableBiPredicate predicate) { return (input1, input2) -> test(predicate, input1, input2); } /** * Converts the given {@link FailableCallable} into a standard {@link Callable}. * * @param the type used by the callables * @param callable a {@code FailableCallable} * @return a standard {@code Callable} * @since 3.10 */ public static Callable asCallable(final FailableCallable callable) { return () -> call(callable); } /** * Converts the given {@link FailableConsumer} into a standard {@link Consumer}. * * @param the type used by the consumers * @param consumer a {@code FailableConsumer} * @return a standard {@code Consumer} * @since 3.10 */ public static Consumer asConsumer(final FailableConsumer consumer) { return input -> accept(consumer, input); } /** * Converts the given {@link FailableFunction} into a standard {@link Function}. * * @param the type of the input of the functions * @param the type of the output of the functions * @param function a {code FailableFunction} * @return a standard {@code Function} * @since 3.10 */ public static Function asFunction(final FailableFunction function) { return input -> apply(function, input); } /** * Converts the given {@link FailablePredicate} into a standard * {@link Predicate}. * * @param the type used by the predicates * @param predicate a {@code FailablePredicate} * @return a standard {@code Predicate} * @since 3.10 */ public static Predicate asPredicate(final FailablePredicate predicate) { return input -> test(predicate, input); } /** * Converts the given {@link FailableRunnable} into a standard {@link Runnable}. * * @param runnable a {@code FailableRunnable} * @return a standard {@code Runnable} * @since 3.10 */ public static Runnable asRunnable(final FailableRunnable runnable) { return () -> run(runnable); } /** * Converts the given {@link FailableSupplier} into a standard {@link Supplier}. * * @param the type supplied by the suppliers * @param supplier a {@code FailableSupplier} * @return a standard {@code Supplier} * @since 3.10 */ public static Supplier asSupplier(final FailableSupplier supplier) { return () -> get(supplier); } /** * Calls a callable and rethrows any exception as a {@link RuntimeException}. * * @param callable the callable to call * @param the return type of the callable * @param the type of checked exception the callable may throw * @return the value returned from the callable */ public static O call(final FailableCallable callable) { return get(callable::call); } /** * Invokes a supplier, and returns the result. * * @param supplier The supplier to invoke. * @param The suppliers output type. * @param The type of checked exception, which the supplier can throw. * @return The object, which has been created by the supplier * @since 3.10 */ public static O get(final FailableSupplier supplier) { try { return supplier.get(); } catch (final Throwable t) { throw rethrow(t); } } /** * Invokes a boolean supplier, and returns the result. * * @param supplier The boolean supplier to invoke. * @param The type of checked exception, which the supplier can throw. * @return The boolean, which has been created by the supplier */ private static boolean getAsBoolean(final FailableBooleanSupplier supplier) { try { return supplier.getAsBoolean(); } catch (final Throwable t) { throw rethrow(t); } } /** *

* Rethrows a {@link Throwable} as an unchecked exception. If the argument is * already unchecked, namely a {@code RuntimeException} or {@code Error} then * the argument will be rethrown without modification. If the exception is * {@code IOException} then it will be wrapped into a * {@code UncheckedIOException}. In every other cases the exception will be * wrapped into a {@code * UndeclaredThrowableException} *

* *

* Note that there is a declared return type for this method, even though it * never returns. The reason for that is to support the usual pattern: *

* *
	 * throw rethrow(myUncheckedException);
	 * 
* *

* instead of just calling the method. This pattern may help the Java compiler * to recognize that at that point an exception will be thrown and the code flow * analysis will not demand otherwise mandatory commands that could follow the * method call, like a {@code return} statement from a value returning method. *

* * @param throwable The throwable to rethrow ossibly wrapped into an unchecked * exception * @return Never returns anything, this method never terminates normally. */ public static RuntimeException rethrow(final Throwable throwable) { Objects.requireNonNull(throwable, "throwable"); if (throwable instanceof RuntimeException) { throw (RuntimeException) throwable; } else if (throwable instanceof Error) { throw (Error) throwable; } else if (throwable instanceof IOException) { throw new UncheckedIOException((IOException) throwable); } else { throw new UndeclaredThrowableException(throwable); } } /** * Runs a runnable and rethrows any exception as a {@link RuntimeException}. * * @param runnable The runnable to run * @param the type of checked exception the runnable may throw */ public static void run(final FailableRunnable runnable) { try { runnable.run(); } catch (final Throwable t) { throw rethrow(t); } } /** * Converts the given collection into a {@link FailableStream}. The * {@link FailableStream} consists of the collections elements. Shortcut for * *
	 * Functions.stream(collection.stream());
	 * 
* * @param collection The collection, which is being converted into a * {@link FailableStream}. * @param The collections element type. (In turn, the result streams * element type.) * @return The created {@link FailableStream}. * @since 3.10 */ public static FailableStream stream(final Collection collection) { return new FailableStream<>(collection.stream()); } /** * Converts the given stream into a {@link FailableStream}. The * {@link FailableStream} consists of the same elements, than the input stream. * However, failable lambdas, like {@link FailablePredicate}, * {@link FailableFunction}, and {@link FailableConsumer} may be applied, rather * than {@link Predicate}, {@link Function}, {@link Consumer}, etc. * * @param stream The stream, which is being converted into a * {@link FailableStream}. * @param The streams element type. * @return The created {@link FailableStream}. * @since 3.10 */ public static FailableStream stream(final Stream stream) { return new FailableStream<>(stream); } /** * Tests a predicate and rethrows any exception as a {@link RuntimeException}. * * @param predicate the predicate to test * @param object1 the first input to test by {@code predicate} * @param object2 the second input to test by {@code predicate} * @param the type of the first argument the predicate tests * @param the type of the second argument the predicate tests * @param the type of checked exception the predicate may throw * @return the boolean value returned by the predicate */ public static boolean test(final FailableBiPredicate predicate, final O1 object1, final O2 object2) { return getAsBoolean(() -> predicate.test(object1, object2)); } /** * Tests a predicate and rethrows any exception as a {@link RuntimeException}. * * @param predicate the predicate to test * @param object the input to test by {@code predicate} * @param the type of argument the predicate tests * @param the type of checked exception the predicate may throw * @return the boolean value returned by the predicate */ public static boolean test(final FailablePredicate predicate, final O object) { return getAsBoolean(() -> predicate.test(object)); } /** * A simple try-with-resources implementation, that can be used, if your objects * do not implement the {@link AutoCloseable} interface. The method executes the * {@code action}. The method guarantees, that all the * {@code resources} are being executed, in the given order, afterwards, and * regardless of success, or failure. If either the original action, or any of * the resource action fails, then the first failure (AKA * {@link Throwable} is rethrown. Example use: * *
	 * {
	 * 	@code
	 * 	final FileInputStream fis = new FileInputStream("my.file");
	 * 	Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());
	 * }
	 * 
* * @param action The action to execute. This object will always * be invoked. * @param errorHandler An optional error handler, which will be invoked finally, * if any error occurred. The error handler will receive the * first error, AKA {@link Throwable}. * @param resources The resource actions to execute. All resource * actions will be invoked, in the given order. A resource * action is an instance of {@link FailableRunnable}, which * will be executed. * @see #tryWithResources(FailableRunnable, FailableRunnable...) */ @SafeVarargs public static void tryWithResources(final FailableRunnable action, final FailableConsumer errorHandler, final FailableRunnable... resources) { final FailableConsumer actualErrorHandler; if (errorHandler == null) { actualErrorHandler = Functions::rethrow; } else { actualErrorHandler = errorHandler; } if (resources != null) { for (final FailableRunnable failableRunnable : resources) { Objects.requireNonNull(failableRunnable, "runnable"); } } Throwable th = null; try { action.run(); } catch (final Throwable t) { th = t; } if (resources != null) { for (final FailableRunnable runnable : resources) { try { runnable.run(); } catch (final Throwable t) { if (th == null) { th = t; } } } } if (th != null) { try { actualErrorHandler.accept(th); } catch (final Throwable t) { throw rethrow(t); } } } /** * A simple try-with-resources implementation, that can be used, if your objects * do not implement the {@link AutoCloseable} interface. The method executes the * {@code action}. The method guarantees, that all the * {@code resources} are being executed, in the given order, afterwards, and * regardless of success, or failure. If either the original action, or any of * the resource action fails, then the first failure (AKA * {@link Throwable} is rethrown. Example use: * *
	 * {
	 * 	@code
	 * 	final FileInputStream fis = new FileInputStream("my.file");
	 * 	Functions.tryWithResources(useInputStream(fis), () -> fis.close());
	 * }
	 * 
* * @param action The action to execute. This object will always be * invoked. * @param resources The resource actions to execute. All resource * actions will be invoked, in the given order. A resource * action is an instance of {@link FailableRunnable}, which * will be executed. * @see #tryWithResources(FailableRunnable, FailableConsumer, * FailableRunnable...) */ @SafeVarargs public static void tryWithResources(final FailableRunnable action, final FailableRunnable... resources) { tryWithResources(action, null, resources); } }