org.apache.commons.lang3.function.Failable Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-lang3 Show documentation
Show all versions of commons-lang3 Show documentation
Apache Commons Lang, a package of Java utility classes for the
classes that are in java.lang's hierarchy, or are considered to be so
standard as to justify existence in java.lang.
The code is tested using the latest revision of the JDK for supported
LTS releases: 8, 11, 17 and 21 currently.
See https://github.com/apache/commons-lang/blob/master/.github/workflows/maven.yml
Please ensure your build environment is up-to-date and kindly report any build issues.
/*
* 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.function;
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.exception.ExceptionUtils;
import org.apache.commons.lang3.stream.Streams;
import org.apache.commons.lang3.stream.Streams.FailableStream;
/**
* 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:
*
*
* Consumer<java.lang.reflect.Method> consumer = m -> {
* try {
* m.invoke(o, args);
* } catch (Throwable t) {
* throw Failable.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:
*
*
*
* 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.11
*/
public class Failable {
/**
* 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 T object1,
final U 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 T object) {
run(() -> consumer.accept(object));
}
/**
* Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
*
* @param consumer the consumer to consume
* @param value the value to consume by {@code consumer}
* @param the type of checked exception the consumer may throw
*/
public static void accept(final FailableDoubleConsumer consumer, final double value) {
run(() -> consumer.accept(value));
}
/**
* Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
*
* @param consumer the consumer to consume
* @param value the value to consume by {@code consumer}
* @param the type of checked exception the consumer may throw
*/
public static void accept(final FailableIntConsumer consumer, final int value) {
run(() -> consumer.accept(value));
}
/**
* Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
*
* @param consumer the consumer to consume
* @param value the value to consume by {@code consumer}
* @param the type of checked exception the consumer may throw
*/
public static void accept(final FailableLongConsumer consumer, final long value) {
run(() -> consumer.accept(value));
}
/**
* 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 R apply(final FailableBiFunction function, final T input1,
final U 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 R apply(final FailableFunction function, final T input) {
return get(() -> function.apply(input));
}
/**
* Applies a function and rethrows any exception as a {@link RuntimeException}.
*
* @param function the function to apply
* @param left the first input to apply {@code function} on
* @param right the second input to apply {@code function} on
* @param the type of checked exception the function may throw
* @return the value returned from the function
*/
public static double applyAsDouble(final FailableDoubleBinaryOperator function,
final double left, final double right) {
return getAsDouble(() -> function.applyAsDouble(left, right));
}
/**
* 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 {@link BiConsumer}
* @return a standard {@link BiConsumer}
*/
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 {@link FailableBiFunction}
* @return a standard {@link BiFunction}
*/
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 {@link FailableBiPredicate}
* @return a standard {@link BiPredicate}
*/
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 {@link FailableCallable}
* @return a standard {@link Callable}
*/
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 {@link FailableConsumer}
* @return a standard {@link Consumer}
*/
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 {@link Function}
*/
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 {@link FailablePredicate}
* @return a standard {@link Predicate}
*/
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 {@link FailableRunnable}
* @return a standard {@link Runnable}
*/
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 {@link FailableSupplier}
* @return a standard {@link Supplier}
*/
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 V 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
*/
public static T 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
*/
public static boolean getAsBoolean(final FailableBooleanSupplier supplier) {
try {
return supplier.getAsBoolean();
} catch (final Throwable t) {
throw rethrow(t);
}
}
/**
* Invokes a double supplier, and returns the result.
*
* @param supplier The double supplier to invoke.
* @param The type of checked exception, which the supplier can throw.
* @return The double, which has been created by the supplier
*/
public static double getAsDouble(final FailableDoubleSupplier supplier) {
try {
return supplier.getAsDouble();
} catch (final Throwable t) {
throw rethrow(t);
}
}
/**
* Invokes an int supplier, and returns the result.
*
* @param supplier The int supplier to invoke.
* @param The type of checked exception, which the supplier can throw.
* @return The int, which has been created by the supplier
*/
public static int getAsInt(final FailableIntSupplier supplier) {
try {
return supplier.getAsInt();
} catch (final Throwable t) {
throw rethrow(t);
}
}
/**
* Invokes a long supplier, and returns the result.
*
* @param supplier The long supplier to invoke.
* @param The type of checked exception, which the supplier can throw.
* @return The long, which has been created by the supplier
*/
public static long getAsLong(final FailableLongSupplier supplier) {
try {
return supplier.getAsLong();
} catch (final Throwable t) {
throw rethrow(t);
}
}
/**
* Invokes a short supplier, and returns the result.
*
* @param supplier The short supplier to invoke.
* @param The type of checked exception, which the supplier can throw.
* @return The short, which has been created by the supplier
*/
public static short getAsShort(final FailableShortSupplier supplier) {
try {
return supplier.getAsShort();
} catch (final Throwable t) {
throw rethrow(t);
}
}
/**
* Rethrows a {@link Throwable} as an unchecked exception. If the argument is already unchecked, namely a
* {@link RuntimeException} or {@link Error} then the argument will be rethrown without modification. If the
* exception is {@link IOException} then it will be wrapped into a {@link 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 possibly 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");
ExceptionUtils.throwUnchecked(throwable);
if (throwable instanceof IOException) {
throw new UncheckedIOException((IOException) throwable);
}
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}.
*/
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}.
*/
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 T object1, final U 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 T 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:
*
*
* 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 = Failable::rethrow;
} else {
actualErrorHandler = errorHandler;
}
Streams.of(resources).forEach(r -> Objects.requireNonNull(r, "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:
*
*
* 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);
}
private Failable() {
// empty
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy