This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new e968ad5 Add missing @since 3.9 and 3.10 Javadoc tags. Clean up
formatting. Clean up Javadocs. Sort methods in AB order.
e968ad5 is described below
commit e968ad5a3f42f9eb7b3bd9ed95f827918d884e77
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Thu Jun 11 09:43:11 2020 -0400
Add missing @since 3.9 and 3.10 Javadoc tags.
Clean up formatting.
Clean up Javadocs.
Sort methods in AB order.
---
.../java/org/apache/commons/lang3/Functions.java | 575 +++++++++++----------
1 file changed, 312 insertions(+), 263 deletions(-)
diff --git a/src/main/java/org/apache/commons/lang3/Functions.java
b/src/main/java/org/apache/commons/lang3/Functions.java
index 2029b2e..896c93a 100644
--- a/src/main/java/org/apache/commons/lang3/Functions.java
+++ b/src/main/java/org/apache/commons/lang3/Functions.java
@@ -33,46 +33,89 @@ 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> {
+ public interface FailableBiConsumer<O1, O2, T extends Throwable> {
+
/**
- * Runs the function.
+ * 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
+ */
+ void accept(O1 object1, O2 object2) 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
* @throws T if the function fails
*/
- void run() throws T;
+ O apply(I1 input1, I2 input2) 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
+ * @throws T if the predicate fails
+ */
+ 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
*/
@@ -81,8 +124,11 @@ public class Functions {
@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
*/
@@ -90,20 +136,11 @@ public class Functions {
}
@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
- */
- 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
@@ -112,21 +149,11 @@ public class Functions {
}
@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
- * @throws T if the function fails
- */
- 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
@@ -135,21 +162,22 @@ public class Functions {
}
@FunctionalInterface
- public interface FailableBiPredicate<O1, O2, T extends Throwable> {
+ public interface FailableRunnable<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
- * @throws T if the predicate fails
+ * Runs the function.
+ *
+ * @throws T if the function fails
*/
- boolean test(O1 object1, O2 object2) throws T;
+ 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,35 +185,61 @@ 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);
+ 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));
}
/**
- * Converts the given {@link FailableConsumer} into a standard {@link
Consumer}.
+ * Consumes a consumer and rethrows any exception as a {@link
RuntimeException}.
*
- * @param <I> the type used by the consumers
- * @param consumer a {@code FailableConsumer}
- * @return a standard {@code Consumer}
+ * @param consumer the consumer to consume
+ * @param object the object to consume by {@code consumer}
+ * @param <O> the type the consumer accepts
+ * @param <T> the type of checked exception the consumer may throw
*/
- public static <I> Consumer<I> asConsumer(final FailableConsumer<I, ?>
consumer) {
- return input -> accept(consumer, input);
+ public static <O, T extends Throwable> void accept(final
FailableConsumer<O, T> consumer, final O object) {
+ run(() -> consumer.accept(object));
}
/**
- * Converts the given {@link FailableCallable} into a standard {@link
Callable}.
+ * Applies a function and rethrows any exception as a {@link
RuntimeException}.
*
- * @param <O> the type used by the callables
- * @param callable a {@code FailableCallable}
- * @return a standard {@code Callable}
+ * @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 <O> Callable<O> asCallable(final FailableCallable<O, ?>
callable) {
- return () -> call(callable);
+ 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
+ * @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 <I, O, T extends Throwable> O apply(final
FailableFunction<I, O, T> function, final I input) {
+ return get(() -> function.apply(input));
}
/**
@@ -195,24 +249,13 @@ public class Functions {
* @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> 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
@@ -220,32 +263,83 @@ public class 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 FailableBiPredicate} into a standard {@link
BiPredicate}.
+ * Converts the given {@link FailableRunnable} into a standard {@link
Runnable}.
*
- * @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}
+ * @param runnable a {@code FailableRunnable}
+ * @return a standard {@code Runnable}
+ * @since 3.10
*/
- public static <I1, I2> BiPredicate<I1, I2> asBiPredicate(final
FailableBiPredicate<I1, I2, ?> predicate) {
- return (input1, input2) -> test(predicate, input1, input2);
+ public static Runnable asRunnable(final FailableRunnable<?> runnable) {
+ return () -> run(runnable);
}
/**
@@ -254,26 +348,15 @@ public class Functions {
* @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);
}
/**
- * 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
@@ -284,71 +367,109 @@ public class Functions {
}
/**
- * 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
- * @param <T> the type of checked exception the consumer may throw
+ * 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> void accept(final
FailableConsumer<O, T> consumer, final O object) {
- run(() -> consumer.accept(object));
+ public static <O, T extends Throwable> O get(final FailableSupplier<O, T>
supplier) {
+ try {
+ return supplier.get();
+ } catch (final Throwable t) {
+ throw rethrow(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 <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
+ * <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 <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 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);
+ }
}
/**
- * 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
- * @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
+ * 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 <I, O, T extends Throwable> O apply(final
FailableFunction<I, O, T> function, final I input) {
- return get(() -> function.apply(input));
+ public static <T extends Throwable> void run(final FailableRunnable<T>
runnable) {
+ try {
+ runnable.run();
+ } catch (final Throwable t) {
+ throw rethrow(t);
+ }
}
/**
- * 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 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 <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 <O> FailableStream<O> stream(final Collection<O> collection)
{
+ return new FailableStream<>(collection.stream());
}
/**
- * 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
- * @param <T> the type of checked exception the predicate may throw
- * @return the boolean value returned by the predicate
+ * 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, T extends Throwable> boolean test(final
FailablePredicate<O, T> predicate, final O object) {
- return get(() -> predicate.test(object));
+ 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}
@@ -357,85 +478,49 @@ public class Functions {
* @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) {
+ 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}.
+ * 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
+ * @param <T> the type of checked exception the predicate may throw
+ * @return the boolean value returned by the predicate
*/
- public static <O> FailableStream<O> stream(final Collection<O> collection)
{
- return new FailableStream<>(collection.stream());
+ public static <O, T extends Throwable> boolean test(final
FailablePredicate<O, T> predicate, final O object) {
+ return get(() -> 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 <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);
- }
- }
}
