Functions¶

@Deprecated public class org.apache.commons.lang3.Functions[source]¶

Deprecated: Use org.apache.commons.lang3.function.Failable.

This class provides utility functions, and classes for working with the 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 Exception. This enforces the use of constructs like:

    Consumer<java.lang.reflect.Method> consumer = m -> {
        try {
            m.invoke(o, args);
        } catch (Throwable t) {
            throw Functions.rethrow(t);
        }
    };

By replacing a Consumer<O> with a FailableConsumer<O,? extends Throwable>, this can be written like follows:

  Functions.accept((m) -> m.invoke(o,args));

Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than the second version.

Since:: 3.9

Constructors¶

Functions()

Constructs a new instance.

public Functions()[source]¶: Constructs a new instance.

Methods¶

`accept(FailableBiConsumer, Object, Object)`	Consumes a consumer and rethrows any exception as a `RuntimeException`.
`accept(FailableConsumer, Object)`	Consumes a consumer and rethrows any exception as a `RuntimeException`.
`apply(FailableBiFunction, Object, Object)`	Applies a function and rethrows any exception as a `RuntimeException`.
`apply(FailableFunction, Object)`	Applies a function and rethrows any exception as a `RuntimeException`.
`asBiConsumer(FailableBiConsumer)`	Converts the given `FailableBiConsumer` into a standard `BiConsumer`.
`asBiFunction(FailableBiFunction)`	Converts the given `FailableBiFunction` into a standard `BiFunction`.
`asBiPredicate(FailableBiPredicate)`	Converts the given `FailableBiPredicate` into a standard `BiPredicate`.
`asCallable(FailableCallable)`	Converts the given `FailableCallable` into a standard `Callable`.
`asConsumer(FailableConsumer)`	Converts the given `FailableConsumer` into a standard `Consumer`.
`asFunction(FailableFunction)`	Converts the given `FailableFunction` into a standard `Function`.
`asPredicate(FailablePredicate)`	Converts the given `FailablePredicate` into a standard `Predicate`.
`asRunnable(FailableRunnable)`	Converts the given `FailableRunnable` into a standard `Runnable`.
`asSupplier(FailableSupplier)`	Converts the given `FailableSupplier` into a standard `Supplier`.
`call(FailableCallable)`	Calls a callable and rethrows any exception as a `RuntimeException`.
`get(FailableSupplier)`	Gets the result of invoking the supplier.
`rethrow(Throwable)`	Rethrows a `Throwable` as an unchecked exception.
`run(FailableRunnable)`	Runs a runnable and rethrows any exception as a `RuntimeException`.
`stream(Collection)`	Converts the given collection into a `FailableStream`.
`stream(Stream)`	Converts the given stream into a `FailableStream`.
`test(FailableBiPredicate, Object, Object)`	Tests a predicate and rethrows any exception as a `RuntimeException`.
`test(FailablePredicate, Object)`	Tests a predicate and rethrows any exception as a `RuntimeException`.
`tryWithResources(FailableRunnable, FailableConsumer, FailableRunnable[])`	A simple try-with-resources implementation, that can be used, if your objects do not implement the `AutoCloseable` interface.
`tryWithResources(FailableRunnable, FailableRunnable[])`	A simple try-with-resources implementation, that can be used, if your objects do not implement the `AutoCloseable` interface.

public static <O1, O2, T extends Throwable> void accept(Functions.FailableBiConsumer<O1, O2, T> consumer, O1 object1, O2 object2)[source]¶

Consumes a consumer and rethrows any exception as a RuntimeException.

Parameters:

consumer – The consumer to consume
object1 – The first object to consume by consumer
object2 – The second object to consume by consumer

Type parameters:

<O1> – the type of the first argument the consumer accepts
<O2> – the type of the second argument the consumer accepts
<T> – The type of checked exception the consumer may throw

public static <O, T extends Throwable> void accept(Functions.FailableConsumer<O, T> consumer, O object)[source]¶

Consumes a consumer and rethrows any exception as a RuntimeException.

Parameters:

consumer – The consumer to consume
object – The object to consume by consumer

Type parameters:

<O> – The type the consumer accepts
<T> – The type of checked exception the consumer may throw

public static <O1, O2, O, T extends Throwable> O apply(Functions.FailableBiFunction<O1, O2, O, T> function, O1 input1, O2 input2)[source]¶

Applies a function and rethrows any exception as a RuntimeException.

Parameters:

function – The function to apply
input1 – The first input to apply function on
input2 – The second input to apply function on

Type parameters:

<O1> – the type of the first argument the function accepts
<O2> – the type of the second argument the function accepts
<O> – The return type of the function
<T> – The type of checked exception the function may throw

Returns:

The value returned from the function

public static <I, O, T extends Throwable> O apply(Functions.FailableFunction<I, O, T> function, I input)[source]¶

Applies a function and rethrows any exception as a RuntimeException.

Parameters:

function – The function to apply
input – The input to apply function on

Type parameters:

 – The type of the argument the function accepts
<O> – The return type of the function
<T> – The type of checked exception the function may throw

Returns:

The value returned from the function

public static <O1, O2> BiConsumer<O1, O2> asBiConsumer(Functions.FailableBiConsumer<O1, O2, ?> consumer)[source]¶

Converts the given FailableBiConsumer into a standard BiConsumer.

Type parameters:

<O1> – the type of the first argument of the consumers
<O2> – the type of the second argument of the consumers

Parameters:

consumer – A failable BiConsumer

Returns:

A standard BiConsumer

Since:

3.10

public static <O1, O2, O> BiFunction<O1, O2, O> asBiFunction(Functions.FailableBiFunction<O1, O2, O, ?> function)[source]¶

Converts the given FailableBiFunction into a standard BiFunction.

Type parameters:

<O1> – the type of the first argument of the input of the functions
<O2> – the type of the second argument of the input of the functions
<O> – The type of the output of the functions

Parameters:

function – A FailableBiFunction

Returns:

A standard BiFunction

Since:

3.10

public static <O1, O2> BiPredicate<O1, O2> asBiPredicate(Functions.FailableBiPredicate<O1, O2, ?> predicate)[source]¶

Converts the given FailableBiPredicate into a standard BiPredicate.

Type parameters:

<O1> – the type of the first argument used by the predicates
<O2> – the type of the second argument used by the predicates

Parameters:

predicate – A FailableBiPredicate

Returns:

A standard BiPredicate

Since:

3.10

public static <O> Callable<O> asCallable(Functions.FailableCallable<O, ?> callable)[source]¶

Converts the given FailableCallable into a standard Callable.

Type parameters:: <O> – The type used by the callables
Parameters:: callable – A FailableCallable
Returns:: A standard Callable
Since:: 3.10

public static Consumer asConsumer(Functions.FailableConsumer<I, ?> consumer)[source]¶

Converts the given FailableConsumer into a standard Consumer.

Type parameters::  – The type used by the consumers
Parameters:: consumer – A FailableConsumer
Returns:: A standard Consumer
Since:: 3.10

public static <I, O> Function<I, O> asFunction(Functions.FailableFunction<I, O, ?> function)[source]¶

Converts the given FailableFunction into a standard Function.

Type parameters:

 – The type of the input of the functions
<O> – The type of the output of the functions

Parameters:

function – A {code FailableFunction}

Returns:

A standard Function

Since:

3.10

public static Predicate asPredicate(Functions.FailablePredicate<I, ?> predicate)[source]¶

Converts the given FailablePredicate into a standard Predicate.

Type parameters::  – The type used by the predicates
Parameters:: predicate – A FailablePredicate
Returns:: A standard Predicate
Since:: 3.10

public static Runnable asRunnable(Functions.FailableRunnable<?> runnable)[source]¶

Converts the given FailableRunnable into a standard Runnable.

Parameters:: runnable – A FailableRunnable
Returns:: A standard Runnable
Since:: 3.10

public static <O> Supplier<O> asSupplier(Functions.FailableSupplier<O, ?> supplier)[source]¶

Converts the given FailableSupplier into a standard Supplier.

Type parameters:: <O> – The type supplied by the suppliers
Parameters:: supplier – A FailableSupplier
Returns:: A standard Supplier
Since:: 3.10

public static <O, T extends Throwable> O call(Functions.FailableCallable<O, T> callable)[source]¶

Calls a callable and rethrows any exception as a RuntimeException.

Parameters:

callable – The callable to call

Type parameters:

<O> – The return type of the callable
<T> – The type of checked exception the callable may throw

Returns:

The value returned from the callable

public static <O, T extends Throwable> O get(Functions.FailableSupplier<O, T> supplier)[source]¶

Gets the result of invoking the supplier.

Parameters:

supplier – The supplier to invoke.

Type parameters:

<O> – The supplier’s output type.
<T> – The type of checked exception, which the supplier can throw.

Returns:

The object, which has been created by the supplier

Since:

3.10

public static RuntimeException rethrow(Throwable throwable)[source]¶

Rethrows a Throwable as an unchecked exception. If the argument is already unchecked, namely a RuntimeException or Error then the argument will be rethrown without modification. If the exception is IOException then it will be wrapped into a UncheckedIOException. In every other cases the exception will be wrapped into a UndeclaredThrowableException

Note that there is a declared return type for this method, even though it never returns. The reason for that is to support the usual pattern:

throw rethrow(myUncheckedException);

instead of just calling the method. This pattern may help the Java compiler to recognize that at that point an exception will be thrown and the code flow analysis will not demand otherwise mandatory commands that could follow the method call, like a return statement from a value returning method.

Parameters:: throwable – The throwable to rethrow possibly wrapped into an unchecked exception
Returns:: Never returns anything, this method never terminates normally.

public static <T extends Throwable> void run(Functions.FailableRunnable<T> runnable)[source]¶

Runs a runnable and rethrows any exception as a RuntimeException.

Parameters:: runnable – The runnable to run
Type parameters:: <T> – The type of checked exception the runnable may throw

public static <O> Streams.FailableStream<O> stream(Collection<O> collection)[source]¶

Converts the given collection into a FailableStream. The FailableStream consists of the collections elements. Shortcut for

Functions.stream(collection.stream());

Parameters:: collection – The collection, which is being converted into a FailableStream.
Type parameters:: <O> – The collections element type. (In turn, the result streams element type.)
Returns:: The created FailableStream.
Since:: 3.10

public static <O> Streams.FailableStream<O> stream(Stream<O> stream)[source]¶

Converts the given stream into a FailableStream. The FailableStream consists of the same elements, than the input stream. However, failable lambdas, like FailablePredicate, FailableFunction, and FailableConsumer may be applied, rather than Predicate, Function, Consumer, etc.

Parameters:: stream – The stream, which is being converted into a FailableStream.
Type parameters:: <O> – The streams element type.
Returns:: The created FailableStream.
Since:: 3.10

public static <O1, O2, T extends Throwable> boolean test(Functions.FailableBiPredicate<O1, O2, T> predicate, O1 object1, O2 object2)[source]¶

Tests a predicate and rethrows any exception as a RuntimeException.

Parameters:

predicate – The predicate to test
object1 – The first input to test by predicate
object2 – The second input to test by predicate

Type parameters:

<O1> – the type of the first argument the predicate tests
<O2> – the type of the second argument the predicate tests
<T> – The type of checked exception the predicate may throw

Returns:

The boolean value returned by the predicate

public static <O, T extends Throwable> boolean test(Functions.FailablePredicate<O, T> predicate, O object)[source]¶

Tests a predicate and rethrows any exception as a RuntimeException.

Parameters:

predicate – The predicate to test
object – The input to test by predicate

Type parameters:

<O> – The type of argument the predicate tests
<T> – The type of checked exception the predicate may throw

Returns:

The boolean value returned by the predicate

@SafeVarargs public static void tryWithResources(Functions.FailableRunnable<? extends Throwable> action, Functions.FailableConsumer<Throwable, ? extends Throwable> errorHandler, Functions.FailableRunnable<? extends Throwable>... resources)[source]¶

A simple try-with-resources implementation, that can be used, if your objects do not implement the AutoCloseable interface. The method executes the action. The method guarantees, that all the resources are being executed, in the given order, afterwards, and regardless of success, or failure. If either the original action, or any of the resource action fails, then the first failure (AKA Throwable) is rethrown. Example use:

    final FileInputStream fis = new FileInputStream("my.file");
    Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());

Parameters:

action – The action to execute. This object will always be invoked.
errorHandler – An optional error handler, which will be invoked finally, if any error occurred. The error handler will receive the first error, AKA Throwable.
resources – The resource actions to execute. All resource actions will be invoked, in the given order. A resource action is an instance of FailableRunnable, which will be executed.

@SafeVarargs public static void tryWithResources(Functions.FailableRunnable<? extends Throwable> action, Functions.FailableRunnable<? extends Throwable>... resources)[source]¶

    final FileInputStream fis = new FileInputStream("my.file");
    Functions.tryWithResources(useInputStream(fis), () -> fis.close());

Parameters:

action – The action to execute. This object will always be invoked.
resources – The resource actions to execute. All resource actions will be invoked, in the given order. A resource action is an instance of FailableRunnable, which will be executed.