Add missing @since 3.9 and 3.10 Javadoc tags.
Clean up formatting.
Clean up Javadocs.
Sort methods in AB order.
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,66 +33,48 @@
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
@@ -101,20 +83,11 @@ public interface FailableBiConsumer<O1, O2, T extends Throwable> {
}
@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
@@ -124,20 +97,11 @@ public interface FailableBiFunction<I1, I2, O, T extends Throwable> {
}
@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
@@ -147,9 +111,73 @@ public interface FailableBiPredicate<O1, O2, T extends Throwable> {
}
@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 interface FailableSupplier<O, T extends Throwable> {
}
/**
- * 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 static <O, T extends Throwable> void accept(final FailableConsumer<O, 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
+ * 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 static <I, O, T extends Throwable> O apply(final FailableFunction<I, O, 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 {@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 static <O, T extends Throwable> boolean test(final FailablePredicate<O, T
}
/**
- * 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 static void tryWithResources(final FailableRunnable<? extends Throwable>
}
/**
- * 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);
- }
- }
}