    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.io.IOException;
    020import java.io.UncheckedIOException;
    021import java.lang.reflect.UndeclaredThrowableException;
    022import java.util.Arrays;
    023import java.util.Collection;
    024import java.util.Objects;
    025import java.util.concurrent.Callable;
    026import java.util.function.BiConsumer;
    027import java.util.function.BiFunction;
    028import java.util.function.BiPredicate;
    029import java.util.function.Consumer;
    030import java.util.function.Function;
    031import java.util.function.Predicate;
    032import java.util.function.Supplier;
    033import java.util.stream.Stream;
    034
    035import org.apache.commons.lang3.Streams.FailableStream;
    036import org.apache.commons.lang3.exception.ExceptionUtils;
    037import org.apache.commons.lang3.function.Failable;
    038import org.apache.commons.lang3.function.FailableBooleanSupplier;
    039
    040/**
    041 * This class provides utility functions, and classes for working with the {@code java.util.function} package, or more
    042 * generally, with Java 8 lambdas. More specifically, it attempts to address the fact that lambdas are supposed not to
    043 * throw Exceptions, at least not checked Exceptions, AKA instances of {@link Exception}. This enforces the use of
    044 * constructs like:
    045 *
    046 * <pre>
    047 * {@code
    048 *     Consumer<java.lang.reflect.Method> consumer = m -> {
    049 *         try {
    050 *             m.invoke(o, args);
    051 *         } catch (Throwable t) {
    052 *             throw Functions.rethrow(t);
    053 *         }
    054 *     };
    055 * }</pre>
    056 *
    057 * <p>
    058 * By replacing a {@link java.util.function.Consumer Consumer&lt;O&gt;} with a {@link FailableConsumer
    059 * FailableConsumer&lt;O,? extends Throwable&gt;}, this can be written like follows:
    060 * </p>
    061 *
    062 * <pre>
    063 * {@code
    064 *   Functions.accept((m) -> m.invoke(o,args));
    065 * }</pre>
    066 *
    067 * <p>
    068 * Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than the second
    069 * version.
    070 * </p>
    071 * @since 3.9
    072 * @deprecated Use {@link org.apache.commons.lang3.function.Failable}.
    073 */
    074@Deprecated
    075public class Functions {
    076
    077    /**
    078     * A functional interface like {@link BiConsumer} that declares a {@link Throwable}.
    079     *
    080     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    081     *
    082     * @param <O1> Consumed type 1.
    083     * @param <O2> Consumed type 2.
    084     * @param <T> Thrown exception.
    085     * @deprecated Use {@link org.apache.commons.lang3.function.FailableBiConsumer}.
    086     */
    087    @Deprecated
    088    @FunctionalInterface
    089    public interface FailableBiConsumer<O1, O2, T extends Throwable> {
    090
    091        /**
    092         * Accepts the consumer.
    093         *
    094         * @param object1 the first parameter for the consumable to accept
    095         * @param object2 the second parameter for the consumable to accept
    096         * @throws T Thrown when the consumer fails.
    097         */
    098        void accept(O1 object1, O2 object2) throws T;
    099    }
    100
    101    /**
    102     * A functional interface like {@link BiFunction} that declares a {@link Throwable}.
    103     *
    104     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    105     *
    106     * @param <O1> Input type 1.
    107     * @param <O2> Input type 2.
    108     * @param <R> Return type.
    109     * @param <T> Thrown exception.
    110     * @deprecated Use {@link org.apache.commons.lang3.function.FailableBiFunction}.
    111     */
    112    @Deprecated
    113    @FunctionalInterface
    114    public interface FailableBiFunction<O1, O2, R, T extends Throwable> {
    115
    116        /**
    117         * Applies this function.
    118         *
    119         * @param input1 the first input for the function
    120         * @param input2 the second input for the function
    121         * @return the result of the function
    122         * @throws T Thrown when the function fails.
    123         */
    124        R apply(O1 input1, O2 input2) throws T;
    125    }
    126
    127    /**
    128     * A functional interface like {@link BiPredicate} that declares a {@link Throwable}.
    129     *
    130     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    131     *
    132     * @param <O1> Predicate type 1.
    133     * @param <O2> Predicate type 2.
    134     * @param <T> Thrown exception.
    135     * @deprecated Use {@link org.apache.commons.lang3.function.FailableBiPredicate}.
    136     */
    137    @Deprecated
    138    @FunctionalInterface
    139    public interface FailableBiPredicate<O1, O2, T extends Throwable> {
    140
    141        /**
    142         * Tests the predicate.
    143         *
    144         * @param object1 the first object to test the predicate on
    145         * @param object2 the second object to test the predicate on
    146         * @return the predicate's evaluation
    147         * @throws T if the predicate fails
    148         */
    149        boolean test(O1 object1, O2 object2) throws T;
    150    }
    151
    152    /**
    153     * A functional interface like {@link java.util.concurrent.Callable} that declares a {@link Throwable}.
    154     *
    155     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    156     *
    157     * @param <R> Return type.
    158     * @param <T> Thrown exception.
    159     * @deprecated Use {@link org.apache.commons.lang3.function.FailableCallable}.
    160     */
    161    @Deprecated
    162    @FunctionalInterface
    163    public interface FailableCallable<R, T extends Throwable> {
    164
    165        /**
    166         * Calls the callable.
    167         *
    168         * @return The value returned from the callable
    169         * @throws T if the callable fails
    170         */
    171        R call() throws T;
    172    }
    173
    174    /**
    175     * A functional interface like {@link Consumer} that declares a {@link Throwable}.
    176     *
    177     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    178     *
    179     * @param <O> Consumed type 1.
    180     * @param <T> Thrown exception.
    181     * @deprecated Use {@link org.apache.commons.lang3.function.FailableConsumer}.
    182     */
    183    @Deprecated
    184    @FunctionalInterface
    185    public interface FailableConsumer<O, T extends Throwable> {
    186
    187        /**
    188         * Accepts the consumer.
    189         *
    190         * @param object the parameter for the consumable to accept
    191         * @throws T Thrown when the consumer fails.
    192         */
    193        void accept(O object) throws T;
    194    }
    195
    196    /**
    197     * A functional interface like {@link Function} that declares a {@link Throwable}.
    198     *
    199     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    200     *
    201     * @param <I> Input type 1.
    202     * @param <R> Return type.
    203     * @param <T> Thrown exception.
    204     * @deprecated Use {@link org.apache.commons.lang3.function.FailableFunction}.
    205     */
    206    @Deprecated
    207    @FunctionalInterface
    208    public interface FailableFunction<I, R, T extends Throwable> {
    209
    210        /**
    211         * Applies this function.
    212         *
    213         * @param input the input for the function
    214         * @return the result of the function
    215         * @throws T Thrown when the function fails.
    216         */
    217        R apply(I input) throws T;
    218    }
    219
    220    /**
    221     * A functional interface like {@link Predicate} that declares a {@link Throwable}.
    222     *
    223     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    224     *
    225     * @param <I> Predicate type 1.
    226     * @param <T> Thrown exception.
    227     * @deprecated Use {@link org.apache.commons.lang3.function.FailablePredicate}.
    228     */
    229    @Deprecated
    230    @FunctionalInterface
    231    public interface FailablePredicate<I, T extends Throwable> {
    232
    233        /**
    234         * Tests the predicate.
    235         *
    236         * @param object the object to test the predicate on
    237         * @return the predicate's evaluation
    238         * @throws T if the predicate fails
    239         */
    240        boolean test(I object) throws T;
    241    }
    242
    243    /**
    244     * A functional interface like {@link Runnable} that declares a {@link Throwable}.
    245     *
    246     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    247     *
    248     * @param <T> Thrown exception.
    249     * @deprecated Use {@link org.apache.commons.lang3.function.FailableRunnable}.
    250     */
    251    @Deprecated
    252    @FunctionalInterface
    253    public interface FailableRunnable<T extends Throwable> {
    254
    255        /**
    256         * Runs the function.
    257         *
    258         * @throws T Thrown when the function fails.
    259         */
    260        void run() throws T;
    261    }
    262
    263    /**
    264     * A functional interface like {@link Supplier} that declares a {@link Throwable}.
    265     *
    266     * <p>TODO for 4.0: Move to org.apache.commons.lang3.function.</p>
    267     *
    268     * @param <R> Return type.
    269     * @param <T> Thrown exception.
    270     * @deprecated Use {@link org.apache.commons.lang3.function.FailableSupplier}.
    271     */
    272    @Deprecated
    273    @FunctionalInterface
    274    public interface FailableSupplier<R, T extends Throwable> {
    275
    276        /**
    277         * Supplies an object
    278         *
    279         * @return a result
    280         * @throws T if the supplier fails
    281         */
    282        R get() throws T;
    283    }
    284
    285    /**
    286     * Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
    287     *
    288     * @param consumer the consumer to consume
    289     * @param object1 the first object to consume by {@code consumer}
    290     * @param object2 the second object to consume by {@code consumer}
    291     * @param <O1> the type of the first argument the consumer accepts
    292     * @param <O2> the type of the second argument the consumer accepts
    293     * @param <T> the type of checked exception the consumer may throw
    294     */
    295    public static <O1, O2, T extends Throwable> void accept(final FailableBiConsumer<O1, O2, T> consumer,
    296        final O1 object1, final O2 object2) {
    297        run(() -> consumer.accept(object1, object2));
    298    }
    299
    300    /**
    301     * Consumes a consumer and rethrows any exception as a {@link RuntimeException}.
    302     *
    303     * @param consumer the consumer to consume
    304     * @param object the object to consume by {@code consumer}
    305     * @param <O> the type the consumer accepts
    306     * @param <T> the type of checked exception the consumer may throw
    307     */
    308    public static <O, T extends Throwable> void accept(final FailableConsumer<O, T> consumer, final O object) {
    309        run(() -> consumer.accept(object));
    310    }
    311
    312    /**
    313     * Applies a function and rethrows any exception as a {@link RuntimeException}.
    314     *
    315     * @param function the function to apply
    316     * @param input1 the first input to apply {@code function} on
    317     * @param input2 the second input to apply {@code function} on
    318     * @param <O1> the type of the first argument the function accepts
    319     * @param <O2> the type of the second argument the function accepts
    320     * @param <O> the return type of the function
    321     * @param <T> the type of checked exception the function may throw
    322     * @return the value returned from the function
    323     */
    324    public static <O1, O2, O, T extends Throwable> O apply(final FailableBiFunction<O1, O2, O, T> function,
    325        final O1 input1, final O2 input2) {
    326        return get(() -> function.apply(input1, input2));
    327    }
    328
    329    /**
    330     * Applies a function and rethrows any exception as a {@link RuntimeException}.
    331     *
    332     * @param function the function to apply
    333     * @param input the input to apply {@code function} on
    334     * @param <I> the type of the argument the function accepts
    335     * @param <O> the return type of the function
    336     * @param <T> the type of checked exception the function may throw
    337     * @return the value returned from the function
    338     */
    339    public static <I, O, T extends Throwable> O apply(final FailableFunction<I, O, T> function, final I input) {
    340        return get(() -> function.apply(input));
    341    }
    342
    343    /**
    344     * Converts the given {@link FailableBiConsumer} into a standard {@link BiConsumer}.
    345     *
    346     * @param <O1> the type of the first argument of the consumers
    347     * @param <O2> the type of the second argument of the consumers
    348     * @param consumer a failable {@link BiConsumer}
    349     * @return a standard {@link BiConsumer}
    350     * @since 3.10
    351     */
    352    public static <O1, O2> BiConsumer<O1, O2> asBiConsumer(final FailableBiConsumer<O1, O2, ?> consumer) {
    353        return (input1, input2) -> accept(consumer, input1, input2);
    354    }
    355
    356    /**
    357     * Converts the given {@link FailableBiFunction} into a standard {@link BiFunction}.
    358     *
    359     * @param <O1> the type of the first argument of the input of the functions
    360     * @param <O2> the type of the second argument of the input of the functions
    361     * @param <O> the type of the output of the functions
    362     * @param function a {@link FailableBiFunction}
    363     * @return a standard {@link BiFunction}
    364     * @since 3.10
    365     */
    366    public static <O1, O2, O> BiFunction<O1, O2, O> asBiFunction(final FailableBiFunction<O1, O2, O, ?> function) {
    367        return (input1, input2) -> apply(function, input1, input2);
    368    }
    369
    370    /**
    371     * Converts the given {@link FailableBiPredicate} into a standard {@link BiPredicate}.
    372     *
    373     * @param <O1> the type of the first argument used by the predicates
    374     * @param <O2> the type of the second argument used by the predicates
    375     * @param predicate a {@link FailableBiPredicate}
    376     * @return a standard {@link BiPredicate}
    377     * @since 3.10
    378     */
    379    public static <O1, O2> BiPredicate<O1, O2> asBiPredicate(final FailableBiPredicate<O1, O2, ?> predicate) {
    380        return (input1, input2) -> test(predicate, input1, input2);
    381    }
    382
    383    /**
    384     * Converts the given {@link FailableCallable} into a standard {@link Callable}.
    385     *
    386     * @param <O> the type used by the callables
    387     * @param callable a {@link FailableCallable}
    388     * @return a standard {@link Callable}
    389     * @since 3.10
    390     */
    391    public static <O> Callable<O> asCallable(final FailableCallable<O, ?> callable) {
    392        return () -> call(callable);
    393    }
    394
    395    /**
    396     * Converts the given {@link FailableConsumer} into a standard {@link Consumer}.
    397     *
    398     * @param <I> the type used by the consumers
    399     * @param consumer a {@link FailableConsumer}
    400     * @return a standard {@link Consumer}
    401     * @since 3.10
    402     */
    403    public static <I> Consumer<I> asConsumer(final FailableConsumer<I, ?> consumer) {
    404        return input -> accept(consumer, input);
    405    }
    406
    407    /**
    408     * Converts the given {@link FailableFunction} into a standard {@link Function}.
    409     *
    410     * @param <I> the type of the input of the functions
    411     * @param <O> the type of the output of the functions
    412     * @param function a {code FailableFunction}
    413     * @return a standard {@link Function}
    414     * @since 3.10
    415     */
    416    public static <I, O> Function<I, O> asFunction(final FailableFunction<I, O, ?> function) {
    417        return input -> apply(function, input);
    418    }
    419
    420    /**
    421     * Converts the given {@link FailablePredicate} into a standard {@link Predicate}.
    422     *
    423     * @param <I> the type used by the predicates
    424     * @param predicate a {@link FailablePredicate}
    425     * @return a standard {@link Predicate}
    426     * @since 3.10
    427     */
    428    public static <I> Predicate<I> asPredicate(final FailablePredicate<I, ?> predicate) {
    429        return input -> test(predicate, input);
    430    }
    431
    432    /**
    433     * Converts the given {@link FailableRunnable} into a standard {@link Runnable}.
    434     *
    435     * @param runnable a {@link FailableRunnable}
    436     * @return a standard {@link Runnable}
    437     * @since 3.10
    438     */
    439    public static Runnable asRunnable(final FailableRunnable<?> runnable) {
    440        return () -> run(runnable);
    441    }
    442
    443    /**
    444     * Converts the given {@link FailableSupplier} into a standard {@link Supplier}.
    445     *
    446     * @param <O> the type supplied by the suppliers
    447     * @param supplier a {@link FailableSupplier}
    448     * @return a standard {@link Supplier}
    449     * @since 3.10
    450     */
    451    public static <O> Supplier<O> asSupplier(final FailableSupplier<O, ?> supplier) {
    452        return () -> get(supplier);
    453    }
    454
    455    /**
    456     * Calls a callable and rethrows any exception as a {@link RuntimeException}.
    457     *
    458     * @param callable the callable to call
    459     * @param <O> the return type of the callable
    460     * @param <T> the type of checked exception the callable may throw
    461     * @return the value returned from the callable
    462     */
    463    public static <O, T extends Throwable> O call(final FailableCallable<O, T> callable) {
    464        return get(callable::call);
    465    }
    466
    467    /**
    468     * Invokes a supplier, and returns the result.
    469     *
    470     * @param supplier The supplier to invoke.
    471     * @param <O> The suppliers output type.
    472     * @param <T> The type of checked exception, which the supplier can throw.
    473     * @return The object, which has been created by the supplier
    474     * @since 3.10
    475     */
    476    public static <O, T extends Throwable> O get(final FailableSupplier<O, T> supplier) {
    477        try {
    478            return supplier.get();
    479        } catch (final Throwable t) {
    480            throw rethrow(t);
    481        }
    482    }
    483
    484    /**
    485     * Invokes a boolean supplier, and returns the result.
    486     *
    487     * @param supplier The boolean supplier to invoke.
    488     * @param <T> The type of checked exception, which the supplier can throw.
    489     * @return The boolean, which has been created by the supplier
    490     */
    491    private static <T extends Throwable> boolean getAsBoolean(final FailableBooleanSupplier<T> supplier) {
    492        try {
    493            return supplier.getAsBoolean();
    494        } catch (final Throwable t) {
    495            throw rethrow(t);
    496        }
    497    }
    498
    499    /**
    500     * Rethrows a {@link Throwable} as an unchecked exception. If the argument is already unchecked, namely a
    501     * {@link RuntimeException} or {@link Error} then the argument will be rethrown without modification. If the
    502     * exception is {@link IOException} then it will be wrapped into a {@link UncheckedIOException}. In every other
    503     * cases the exception will be wrapped into a {@code
    504     * UndeclaredThrowableException}
    505     *
    506     * <p>
    507     * Note that there is a declared return type for this method, even though it never returns. The reason for that is
    508     * to support the usual pattern:
    509     * </p>
    510     *
    511     * <pre>
    512     * throw rethrow(myUncheckedException);</pre>
    513     *
    514     * <p>
    515     * instead of just calling the method. This pattern may help the Java compiler to recognize that at that point an
    516     * exception will be thrown and the code flow analysis will not demand otherwise mandatory commands that could
    517     * follow the method call, like a {@code return} statement from a value returning method.
    518     * </p>
    519     *
    520     * @param throwable The throwable to rethrow possibly wrapped into an unchecked exception
    521     * @return Never returns anything, this method never terminates normally.
    522     */
    523    public static RuntimeException rethrow(final Throwable throwable) {
    524        Objects.requireNonNull(throwable, "throwable");
    525        ExceptionUtils.throwUnchecked(throwable);
    526        if (throwable instanceof IOException) {
    527            throw new UncheckedIOException((IOException) throwable);
    528        }
    529        throw new UndeclaredThrowableException(throwable);
    530    }
    531
    532    /**
    533     * Runs a runnable and rethrows any exception as a {@link RuntimeException}.
    534     *
    535     * @param runnable The runnable to run
    536     * @param <T> the type of checked exception the runnable may throw
    537     */
    538    public static <T extends Throwable> void run(final FailableRunnable<T> runnable) {
    539        try {
    540            runnable.run();
    541        } catch (final Throwable t) {
    542            throw rethrow(t);
    543        }
    544    }
    545
    546    /**
    547     * Converts the given collection into a {@link FailableStream}. The {@link FailableStream} consists of the
    548     * collections elements. Shortcut for
    549     *
    550     * <pre>
    551     * Functions.stream(collection.stream());</pre>
    552     *
    553     * @param collection The collection, which is being converted into a {@link FailableStream}.
    554     * @param <O> The collections element type. (In turn, the result streams element type.)
    555     * @return The created {@link FailableStream}.
    556     * @since 3.10
    557     */
    558    public static <O> FailableStream<O> stream(final Collection<O> collection) {
    559        return new FailableStream<>(collection.stream());
    560    }
    561
    562    /**
    563     * Converts the given stream into a {@link FailableStream}. The {@link FailableStream} consists of the same
    564     * elements, than the input stream. However, failable lambdas, like {@link FailablePredicate},
    565     * {@link FailableFunction}, and {@link FailableConsumer} may be applied, rather than {@link Predicate},
    566     * {@link Function}, {@link Consumer}, etc.
    567     *
    568     * @param stream The stream, which is being converted into a {@link FailableStream}.
    569     * @param <O> The streams element type.
    570     * @return The created {@link FailableStream}.
    571     * @since 3.10
    572     */
    573    public static <O> FailableStream<O> stream(final Stream<O> stream) {
    574        return new FailableStream<>(stream);
    575    }
    576
    577    /**
    578     * Tests a predicate and rethrows any exception as a {@link RuntimeException}.
    579     *
    580     * @param predicate the predicate to test
    581     * @param object1 the first input to test by {@code predicate}
    582     * @param object2 the second input to test by {@code predicate}
    583     * @param <O1> the type of the first argument the predicate tests
    584     * @param <O2> the type of the second argument the predicate tests
    585     * @param <T> the type of checked exception the predicate may throw
    586     * @return the boolean value returned by the predicate
    587     */
    588    public static <O1, O2, T extends Throwable> boolean test(final FailableBiPredicate<O1, O2, T> predicate,
    589        final O1 object1, final O2 object2) {
    590        return getAsBoolean(() -> predicate.test(object1, object2));
    591    }
    592
    593    /**
    594     * Tests a predicate and rethrows any exception as a {@link RuntimeException}.
    595     *
    596     * @param predicate the predicate to test
    597     * @param object the input to test by {@code predicate}
    598     * @param <O> the type of argument the predicate tests
    599     * @param <T> the type of checked exception the predicate may throw
    600     * @return the boolean value returned by the predicate
    601     */
    602    public static <O, T extends Throwable> boolean test(final FailablePredicate<O, T> predicate, final O object) {
    603        return getAsBoolean(() -> predicate.test(object));
    604    }
    605
    606    /**
    607     * A simple try-with-resources implementation, that can be used, if your objects do not implement the
    608     * {@link AutoCloseable} interface. The method executes the {@code action}. The method guarantees, that <em>all</em>
    609     * the {@code resources} are being executed, in the given order, afterwards, and regardless of success, or failure.
    610     * If either the original action, or any of the resource action fails, then the <em>first</em> failure (AKA
    611     * {@link Throwable}) is rethrown. Example use:
    612     *
    613     * <pre>
    614     * {@code
    615     *     final FileInputStream fis = new FileInputStream("my.file");
    616     *     Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());
    617     * }</pre>
    618     *
    619     * @param action The action to execute. This object <em>will</em> always be invoked.
    620     * @param errorHandler An optional error handler, which will be invoked finally, if any error occurred. The error
    621     *        handler will receive the first error, AKA {@link Throwable}.
    622     * @param resources The resource actions to execute. <em>All</em> resource actions will be invoked, in the given
    623     *        order. A resource action is an instance of {@link FailableRunnable}, which will be executed.
    624     * @see #tryWithResources(FailableRunnable, FailableRunnable...)
    625     */
    626    @SafeVarargs
    627    public static void tryWithResources(final FailableRunnable<? extends Throwable> action,
    628        final FailableConsumer<Throwable, ? extends Throwable> errorHandler,
    629        final FailableRunnable<? extends Throwable>... resources) {
    630        final org.apache.commons.lang3.function.FailableRunnable<?>[] fr = new org.apache.commons.lang3.function.FailableRunnable[resources.length];
    631        Arrays.setAll(fr, i -> () -> resources[i].run());
    632        Failable.tryWithResources(action::run, errorHandler != null ? errorHandler::accept : null, fr);
    633    }
    634
    635    /**
    636     * A simple try-with-resources implementation, that can be used, if your objects do not implement the
    637     * {@link AutoCloseable} interface. The method executes the {@code action}. The method guarantees, that <em>all</em>
    638     * the {@code resources} are being executed, in the given order, afterwards, and regardless of success, or failure.
    639     * If either the original action, or any of the resource action fails, then the <em>first</em> failure (AKA
    640     * {@link Throwable}) is rethrown. Example use:
    641     *
    642     * <pre>
    643     * {@code
    644     *     final FileInputStream fis = new FileInputStream("my.file");
    645     *     Functions.tryWithResources(useInputStream(fis), () -> fis.close());
    646     * }</pre>
    647     *
    648     * @param action The action to execute. This object <em>will</em> always be invoked.
    649     * @param resources The resource actions to execute. <em>All</em> resource actions will be invoked, in the given
    650     *        order. A resource action is an instance of {@link FailableRunnable}, which will be executed.
    651     * @see #tryWithResources(FailableRunnable, FailableConsumer, FailableRunnable...)
    652     */
    653    @SafeVarargs
    654    public static void tryWithResources(final FailableRunnable<? extends Throwable> action,
    655        final FailableRunnable<? extends Throwable>... resources) {
    656        tryWithResources(action, null, resources);
    657    }
    658
    659    /**
    660     * Constructs a new instance.
    661     */
    662    public Functions() {
    663        // empty
    664    }
    665}