Add missing @since 3.9 and 3.10 Javadoc tags.
Clean up formatting. Clean up Javadocs. Sort methods in AB order.
This commit is contained in:
Gary Gregory
parent
598e8bd51e
commit
e968ad5a3f
|
|
@ -33,66 +33,48 @@ import java.util.stream.Stream;
|
|||
|
||||
import org.apache.commons.lang3.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
|
||||
* <pre>{@code
|
||||
* Consumer<java.lang.reflect.Method> consumer = (m) -> {
|
||||
* try {
|
||||
* m.invoke(o, args);
|
||||
* } catch (Throwable t) {
|
||||
* throw Functions.rethrow(t);
|
||||
* }
|
||||
* };
|
||||
/**
|
||||
* 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:
|
||||
*
|
||||
* <pre>
|
||||
* {
|
||||
* @code
|
||||
* Consumer<java.lang.reflect.Method> consumer = (m) -> {
|
||||
* try {
|
||||
* m.invoke(o, args);
|
||||
* } catch (Throwable t) {
|
||||
* throw Functions.rethrow(t);
|
||||
* }
|
||||
* };
|
||||
* }</pre>
|
||||
* By replacing a {@link java.util.function.Consumer Consumer<O>} with a
|
||||
* {@link FailableConsumer FailableConsumer<O,? extends Throwable>}, this can be
|
||||
* written like follows:
|
||||
* <pre>{@code
|
||||
*
|
||||
* <p>
|
||||
* By replacing a {@link java.util.function.Consumer Consumer<O>} with a {@link FailableConsumer
|
||||
* FailableConsumer<O,? extends Throwable>}, this can be written like follows:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* {@code
|
||||
* Functions.accept((m) -> m.invoke(o,args));
|
||||
* }</pre>
|
||||
* Obviously, the second version is much more concise and the spirit of
|
||||
* Lambda expressions is met better than the second version.
|
||||
*
|
||||
* <p>
|
||||
* Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than the second
|
||||
* version.
|
||||
* </p>
|
||||
* @since 3.9
|
||||
*/
|
||||
public class Functions {
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableRunnable<T extends Throwable> {
|
||||
/**
|
||||
* Runs the function.
|
||||
* @throws T if the function fails
|
||||
*/
|
||||
void run() throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableCallable<O, T extends Throwable> {
|
||||
/**
|
||||
* Calls the callable.
|
||||
* @return The value returned from the callable
|
||||
* @throws T if the callable fails
|
||||
*/
|
||||
O call() throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableConsumer<O, T extends Throwable> {
|
||||
/**
|
||||
* Accepts the consumer.
|
||||
* @param object the parameter for the consumable to accept
|
||||
* @throws T if the consumer fails
|
||||
*/
|
||||
void accept(O object) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableBiConsumer<O1, O2, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* 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 if the consumer fails
|
||||
|
|
@ -100,21 +82,12 @@ public class Functions {
|
|||
void accept(O1 object1, O2 object2) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableFunction<I, O, T extends Throwable> {
|
||||
/**
|
||||
* Applies this function.
|
||||
* @param input the input for the function
|
||||
* @return the result of the function
|
||||
* @throws T if the function fails
|
||||
*/
|
||||
O apply(I input) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableBiFunction<I1, I2, O, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* 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
|
||||
|
|
@ -123,21 +96,12 @@ public class Functions {
|
|||
O apply(I1 input1, I2 input2) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailablePredicate<O, T extends Throwable> {
|
||||
/**
|
||||
* Test the predicate.
|
||||
* @param object the object to test the predicate on
|
||||
* @return the predicate's evaluation
|
||||
* @throws T if the predicate fails
|
||||
*/
|
||||
boolean test(O object) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableBiPredicate<O1, O2, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Test 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
|
||||
|
|
@ -146,10 +110,74 @@ public class Functions {
|
|||
boolean test(O1 object1, O2 object2) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableCallable<O, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Calls the callable.
|
||||
*
|
||||
* @return The value returned from the callable
|
||||
* @throws T if the callable fails
|
||||
*/
|
||||
O call() throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableConsumer<O, T extends Throwable> {
|
||||
|
||||
|
||||
/**
|
||||
* Accepts the consumer.
|
||||
*
|
||||
* @param object the parameter for the consumable to accept
|
||||
* @throws T if the consumer fails
|
||||
*/
|
||||
void accept(O object) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableFunction<I, O, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Applies this function.
|
||||
*
|
||||
* @param input the input for the function
|
||||
* @return the result of the function
|
||||
* @throws T if the function fails
|
||||
*/
|
||||
O apply(I input) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailablePredicate<O, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Test the predicate.
|
||||
*
|
||||
* @param object the object to test the predicate on
|
||||
* @return the predicate's evaluation
|
||||
* @throws T if the predicate fails
|
||||
*/
|
||||
boolean test(O object) throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableRunnable<T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Runs the function.
|
||||
*
|
||||
* @throws T if the function fails
|
||||
*/
|
||||
void run() throws T;
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface FailableSupplier<O, T extends Throwable> {
|
||||
|
||||
/**
|
||||
* Supplies an object
|
||||
*
|
||||
* @return the suppliers result
|
||||
* @throws T if the supplier fails
|
||||
*/
|
||||
|
|
@ -157,134 +185,23 @@ public class Functions {
|
|||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableRunnable} into a standard {@link Runnable}.
|
||||
* Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
|
||||
*
|
||||
* @param runnable a {@code FailableRunnable}
|
||||
* @return a standard {@code Runnable}
|
||||
* @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 <O1> the type of the first argument the consumer accepts
|
||||
* @param <O2> the type of the second argument the consumer accepts
|
||||
* @param <T> the type of checked exception the consumer may throw
|
||||
*/
|
||||
public static Runnable asRunnable(final FailableRunnable<?> runnable) {
|
||||
return () -> run(runnable);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableConsumer} into a standard {@link Consumer}.
|
||||
*
|
||||
* @param <I> the type used by the consumers
|
||||
* @param consumer a {@code FailableConsumer}
|
||||
* @return a standard {@code Consumer}
|
||||
*/
|
||||
public static <I> Consumer<I> asConsumer(final FailableConsumer<I, ?> consumer) {
|
||||
return input -> accept(consumer, input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableCallable} into a standard {@link Callable}.
|
||||
*
|
||||
* @param <O> the type used by the callables
|
||||
* @param callable a {@code FailableCallable}
|
||||
* @return a standard {@code Callable}
|
||||
*/
|
||||
public static <O> Callable<O> asCallable(final FailableCallable<O, ?> callable) {
|
||||
return () -> call(callable);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableBiConsumer} into a standard {@link BiConsumer}.
|
||||
*
|
||||
* @param <I1> the type of the first argument of the consumers
|
||||
* @param <I2> the type of the second argument of the consumers
|
||||
* @param consumer a failable {@code BiConsumer}
|
||||
* @return a standard {@code BiConsumer}
|
||||
*/
|
||||
public static <I1, I2> BiConsumer<I1, I2> asBiConsumer(final FailableBiConsumer<I1, I2, ?> consumer) {
|
||||
return (input1, input2) -> accept(consumer, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableFunction} into a standard {@link Function}.
|
||||
*
|
||||
* @param <I> the type of the input of the functions
|
||||
* @param <O> the type of the output of the functions
|
||||
* @param function a {code FailableFunction}
|
||||
* @return a standard {@code Function}
|
||||
*/
|
||||
public static <I, O> Function<I, O> asFunction(final FailableFunction<I, O, ?> function) {
|
||||
return input -> apply(function, input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableBiFunction} into a standard {@link BiFunction}.
|
||||
*
|
||||
* @param <I1> the type of the first argument of the input of the functions
|
||||
* @param <I2> the type of the second argument of the input of the functions
|
||||
* @param <O> the type of the output of the functions
|
||||
* @param function a {@code FailableBiFunction}
|
||||
* @return a standard {@code BiFunction}
|
||||
*/
|
||||
public static <I1, I2, O> BiFunction<I1, I2, O> asBiFunction(final FailableBiFunction<I1, I2, O, ?> function) {
|
||||
return (input1, input2) -> apply(function, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailablePredicate} into a standard {@link Predicate}.
|
||||
*
|
||||
* @param <I> the type used by the predicates
|
||||
* @param predicate a {@code FailablePredicate}
|
||||
* @return a standard {@code Predicate}
|
||||
*/
|
||||
public static <I> Predicate<I> asPredicate(final FailablePredicate<I, ?> predicate) {
|
||||
return input -> test(predicate, input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableBiPredicate} into a standard {@link BiPredicate}.
|
||||
*
|
||||
* @param <I1> the type of the first argument used by the predicates
|
||||
* @param <I2> the type of the second argument used by the predicates
|
||||
* @param predicate a {@code FailableBiPredicate}
|
||||
* @return a standard {@code BiPredicate}
|
||||
*/
|
||||
public static <I1, I2> BiPredicate<I1, I2> asBiPredicate(final FailableBiPredicate<I1, I2, ?> predicate) {
|
||||
return (input1, input2) -> test(predicate, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableSupplier} into a standard {@link Supplier}.
|
||||
*
|
||||
* @param <O> the type supplied by the suppliers
|
||||
* @param supplier a {@code FailableSupplier}
|
||||
* @return a standard {@code Supplier}
|
||||
*/
|
||||
public static <O> Supplier<O> asSupplier(final FailableSupplier<O, ?> supplier) {
|
||||
return () -> get(supplier);
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs a runnable and rethrows any exception as a {@link RuntimeException}.
|
||||
* @param runnable The runnable to run
|
||||
* @param <T> the type of checked exception the runnable may throw
|
||||
*/
|
||||
public static <T extends Throwable> void run(final FailableRunnable<T> runnable) {
|
||||
try {
|
||||
runnable.run();
|
||||
} catch (final Throwable t) {
|
||||
throw rethrow(t);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Calls a callable and rethrows any exception as a {@link RuntimeException}.
|
||||
* @param callable the callable to call
|
||||
* @param <O> the return type of the callable
|
||||
* @param <T> the type of checked exception the callable may throw
|
||||
* @return the value returned from the callable
|
||||
*/
|
||||
public static <O, T extends Throwable> O call(final FailableCallable<O, T> callable) {
|
||||
return get(callable::call);
|
||||
public static <O1, O2, T extends Throwable> void accept(final FailableBiConsumer<O1, O2, T> 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 <O> the type the consumer accepts
|
||||
|
|
@ -295,20 +212,25 @@ public class Functions {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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 <O1> the type of the first argument the consumer accepts
|
||||
* @param <O2> the type of the second argument the consumer accepts
|
||||
* @param <T> the type of checked exception the consumer may throw
|
||||
* 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 <I1> the type of the first argument the function accepts
|
||||
* @param <I2> the type of the second argument the function accepts
|
||||
* @param <O> the return type of the function
|
||||
* @param <T> the type of checked exception the function may throw
|
||||
* @return the value returned from the function
|
||||
*/
|
||||
public static <O1, O2, T extends Throwable> void accept(final FailableBiConsumer<O1, O2, T> consumer, final O1 object1, final O2 object2) {
|
||||
run(() -> consumer.accept(object1, object2));
|
||||
public static <I1, I2, O, T extends Throwable> O apply(final FailableBiFunction<I1, I2, O, T> function,
|
||||
final I1 input1, final I2 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 <I> the type of the argument the function accepts
|
||||
|
|
@ -321,22 +243,249 @@ public class Functions {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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 <I1> the type of the first argument the function accepts
|
||||
* @param <I2> the type of the second argument the function accepts
|
||||
* @param <O> the return type of the function
|
||||
* @param <T> the type of checked exception the function may throw
|
||||
* @return the value returned from the function
|
||||
* Converts the given {@link FailableBiConsumer} into a standard {@link BiConsumer}.
|
||||
*
|
||||
* @param <I1> the type of the first argument of the consumers
|
||||
* @param <I2> 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 <I1, I2, O, T extends Throwable> O apply(final FailableBiFunction<I1, I2, O, T> function, final I1 input1, final I2 input2) {
|
||||
return get(() -> function.apply(input1, input2));
|
||||
public static <I1, I2> BiConsumer<I1, I2> asBiConsumer(final FailableBiConsumer<I1, I2, ?> consumer) {
|
||||
return (input1, input2) -> accept(consumer, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableBiFunction} into a standard {@link BiFunction}.
|
||||
*
|
||||
* @param <I1> the type of the first argument of the input of the functions
|
||||
* @param <I2> the type of the second argument of the input of the functions
|
||||
* @param <O> the type of the output of the functions
|
||||
* @param function a {@code FailableBiFunction}
|
||||
* @return a standard {@code BiFunction}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <I1, I2, O> BiFunction<I1, I2, O> asBiFunction(final FailableBiFunction<I1, I2, O, ?> function) {
|
||||
return (input1, input2) -> apply(function, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableBiPredicate} into a standard {@link BiPredicate}.
|
||||
*
|
||||
* @param <I1> the type of the first argument used by the predicates
|
||||
* @param <I2> 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 <I1, I2> BiPredicate<I1, I2> asBiPredicate(final FailableBiPredicate<I1, I2, ?> predicate) {
|
||||
return (input1, input2) -> test(predicate, input1, input2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableCallable} into a standard {@link Callable}.
|
||||
*
|
||||
* @param <O> the type used by the callables
|
||||
* @param callable a {@code FailableCallable}
|
||||
* @return a standard {@code Callable}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <O> Callable<O> asCallable(final FailableCallable<O, ?> callable) {
|
||||
return () -> call(callable);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableConsumer} into a standard {@link Consumer}.
|
||||
*
|
||||
* @param <I> the type used by the consumers
|
||||
* @param consumer a {@code FailableConsumer}
|
||||
* @return a standard {@code Consumer}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <I> Consumer<I> asConsumer(final FailableConsumer<I, ?> consumer) {
|
||||
return input -> accept(consumer, input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailableFunction} into a standard {@link Function}.
|
||||
*
|
||||
* @param <I> the type of the input of the functions
|
||||
* @param <O> the type of the output of the functions
|
||||
* @param function a {code FailableFunction}
|
||||
* @return a standard {@code Function}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <I, O> Function<I, O> asFunction(final FailableFunction<I, O, ?> function) {
|
||||
return input -> apply(function, input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given {@link FailablePredicate} into a standard {@link Predicate}.
|
||||
*
|
||||
* @param <I> the type used by the predicates
|
||||
* @param predicate a {@code FailablePredicate}
|
||||
* @return a standard {@code Predicate}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <I> Predicate<I> asPredicate(final FailablePredicate<I, ?> 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 <O> the type supplied by the suppliers
|
||||
* @param supplier a {@code FailableSupplier}
|
||||
* @return a standard {@code Supplier}
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <O> Supplier<O> asSupplier(final FailableSupplier<O, ?> supplier) {
|
||||
return () -> get(supplier);
|
||||
}
|
||||
|
||||
/**
|
||||
* Calls a callable and rethrows any exception as a {@link RuntimeException}.
|
||||
*
|
||||
* @param callable the callable to call
|
||||
* @param <O> the return type of the callable
|
||||
* @param <T> the type of checked exception the callable may throw
|
||||
* @return the value returned from the callable
|
||||
*/
|
||||
public static <O, T extends Throwable> O call(final FailableCallable<O, T> callable) {
|
||||
return get(callable::call);
|
||||
}
|
||||
|
||||
/**
|
||||
* Invokes the supplier, and returns the result.
|
||||
*
|
||||
* @param supplier The supplier to invoke.
|
||||
* @param <O> The suppliers output type.
|
||||
* @param <T> 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, T extends Throwable> O get(final FailableSupplier<O, T> supplier) {
|
||||
try {
|
||||
return supplier.get();
|
||||
} catch (final Throwable t) {
|
||||
throw rethrow(t);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>
|
||||
* 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}
|
||||
* </p>
|
||||
*
|
||||
* <p>
|
||||
* 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:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* throw rethrow(myUncheckedException);</pre>
|
||||
*
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
*
|
||||
* @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 <T> the type of checked exception the runnable may throw
|
||||
*/
|
||||
public static <T extends Throwable> void run(final FailableRunnable<T> 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
|
||||
*
|
||||
* <pre>
|
||||
* Functions.stream(collection.stream());</pre>
|
||||
*
|
||||
* @param collection The collection, which is being converted into a {@link FailableStream}.
|
||||
* @param <O> The collections element type. (In turn, the result streams element type.)
|
||||
* @return The created {@link FailableStream}.
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <O> FailableStream<O> stream(final Collection<O> 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 <O> The streams element type.
|
||||
* @return The created {@link FailableStream}.
|
||||
* @since 3.10
|
||||
*/
|
||||
public static <O> FailableStream<O> stream(final Stream<O> 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 <O1> the type of the first argument the predicate tests
|
||||
* @param <O2> the type of the second argument the predicate tests
|
||||
* @param <T> the type of checked exception the predicate may throw
|
||||
* @return the boolean value returned by the predicate
|
||||
*/
|
||||
public static <O1, O2, T extends Throwable> boolean test(final FailableBiPredicate<O1, O2, T> predicate,
|
||||
final O1 object1, final O2 object2) {
|
||||
return get(() -> 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 <O> the type of argument the predicate tests
|
||||
|
|
@ -348,94 +497,30 @@ public class Functions {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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 <O1> the type of the first argument the predicate tests
|
||||
* @param <O2> the type of the second argument the predicate tests
|
||||
* @param <T> the type of checked exception the predicate may throw
|
||||
* @return the boolean value returned by the predicate
|
||||
*/
|
||||
public static <O1, O2, T extends Throwable> boolean test(final FailableBiPredicate<O1, O2, T> predicate, final O1 object1, final O2 object2) {
|
||||
return get(() -> predicate.test(object1, object2));
|
||||
}
|
||||
|
||||
/**
|
||||
* Invokes the supplier, and returns the result.
|
||||
* @param supplier The supplier to invoke.
|
||||
* @param <O> The suppliers output type.
|
||||
* @param <T> The type of checked exception, which the supplier can throw.
|
||||
* @return The object, which has been created by the supplier
|
||||
*/
|
||||
public static <O, T extends Throwable> O get(final FailableSupplier<O, T> supplier) {
|
||||
try {
|
||||
return supplier.get();
|
||||
} catch (final Throwable t) {
|
||||
throw rethrow(t);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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 <O> The streams element type.
|
||||
* @return The created {@link FailableStream}.
|
||||
*/
|
||||
public static <O> FailableStream<O> stream(final Stream<O> stream) {
|
||||
return new FailableStream<>(stream);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the given collection into a {@link FailableStream}.
|
||||
* The {@link FailableStream} consists of the collections
|
||||
* elements. Shortcut for
|
||||
* <pre>
|
||||
* Functions.stream(collection.stream());
|
||||
* </pre>
|
||||
* @param collection The collection, which is being converted into a
|
||||
* {@link FailableStream}.
|
||||
* @param <O> The collections element type. (In turn, the result
|
||||
* streams element type.)
|
||||
* @return The created {@link FailableStream}.
|
||||
*/
|
||||
public static <O> FailableStream<O> stream(final Collection<O> collection) {
|
||||
return new FailableStream<>(collection.stream());
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* 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 <em>all</em>
|
||||
* 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 <em>first</em> failure (aka
|
||||
* 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 <em>all</em>
|
||||
* 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 <em>first</em> failure (AKA
|
||||
* {@link Throwable} is rethrown. Example use:
|
||||
* <pre>{@code
|
||||
* final FileInputStream fis = new FileInputStream("my.file");
|
||||
* Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());
|
||||
*
|
||||
* <pre>
|
||||
* {
|
||||
* @code
|
||||
* final FileInputStream fis = new FileInputStream("my.file");
|
||||
* Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());
|
||||
* }</pre>
|
||||
* @param action The action to execute. This object <em>will</em> 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. <em>All</em> resource
|
||||
* actions will be invoked, in the given order. A resource action is an
|
||||
* instance of {@link FailableRunnable}, which will be executed.
|
||||
*
|
||||
* @param action The action to execute. This object <em>will</em> 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. <em>All</em> 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<? extends Throwable> action,
|
||||
final FailableConsumer<Throwable, ? extends Throwable> errorHandler,
|
||||
final FailableRunnable<? extends Throwable>... resources) {
|
||||
final FailableConsumer<Throwable, ? extends Throwable> errorHandler,
|
||||
final FailableRunnable<? extends Throwable>... resources) {
|
||||
final FailableConsumer<Throwable, ? extends Throwable> actualErrorHandler;
|
||||
if (errorHandler == null) {
|
||||
actualErrorHandler = Functions::rethrow;
|
||||
|
|
@ -474,63 +559,27 @@ public class Functions {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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 <em>all</em>
|
||||
* 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 <em>first</em> failure (aka
|
||||
* 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 <em>all</em>
|
||||
* 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 <em>first</em> failure (AKA
|
||||
* {@link Throwable} is rethrown. Example use:
|
||||
* <pre>{@code
|
||||
* final FileInputStream fis = new FileInputStream("my.file");
|
||||
* Functions.tryWithResources(useInputStream(fis), () -> fis.close());
|
||||
*
|
||||
* <pre>
|
||||
* {
|
||||
* @code
|
||||
* final FileInputStream fis = new FileInputStream("my.file");
|
||||
* Functions.tryWithResources(useInputStream(fis), () -> fis.close());
|
||||
* }</pre>
|
||||
* @param action The action to execute. This object <em>will</em> always
|
||||
* be invoked.
|
||||
* @param resources The resource actions to execute. <em>All</em> resource
|
||||
* actions will be invoked, in the given order. A resource action is an
|
||||
* instance of {@link FailableRunnable}, which will be executed.
|
||||
*
|
||||
* @param action The action to execute. This object <em>will</em> always be invoked.
|
||||
* @param resources The resource actions to execute. <em>All</em> 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<? extends Throwable> action,
|
||||
final FailableRunnable<? extends Throwable>... resources) {
|
||||
final FailableRunnable<? extends Throwable>... resources) {
|
||||
tryWithResources(action, null, resources);
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>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}</p>
|
||||
*
|
||||
* <p>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:</p>
|
||||
*
|
||||
* <pre>
|
||||
* throw rethrow(myUncheckedException);
|
||||
* </pre>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* @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);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue