org.apache.commons.lang3

Class Functions

java.lang.Object

org.apache.commons.lang3.Functions

public class Functions
extends Object

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Functions.FailableBiConsumer<O1,O2,T extends Throwable>
static interface	Functions.FailableBiFunction<I1,I2,O,T extends Throwable>
static interface	Functions.FailableBiPredicate<O1,O2,T extends Throwable>
static interface	Functions.FailableCallable<O,T extends Throwable>
static interface	Functions.FailableConsumer<O,T extends Throwable>
static interface	Functions.FailableFunction<I,O,T extends Throwable>
static interface	Functions.FailablePredicate<O,T extends Throwable>
static interface	Functions.FailableRunnable<T extends Throwable>
static interface	Functions.FailableSupplier<O,T extends Throwable>

Constructor Summary

Constructors

Constructor and Description
Functions()

Method Summary

Modifier and Type	Method and Description
static <O1,O2,T extends Throwable> void	accept(Functions.FailableBiConsumer<O1,O2,T> pConsumer, O1 pObject1, O2 pObject2) Consumes a consumer and rethrows any exception as a RuntimeException.
static <O,T extends Throwable> void	accept(Functions.FailableConsumer<O,T> pConsumer, O pObject) Consumes a consumer and rethrows any exception as a RuntimeException.
static <I1,I2,O,T extends Throwable> O	apply(Functions.FailableBiFunction<I1,I2,O,T> pFunction, I1 pInput1, I2 pInput2) Applies a function and rethrows any exception as a RuntimeException.
static <I,O,T extends Throwable> O	apply(Functions.FailableFunction<I,O,T> pFunction, I pInput) Applies a function and rethrows any exception as a RuntimeException.
static <I1,I2> BiConsumer<I1,I2>	asBiConsumer(Functions.FailableBiConsumer<I1,I2,?> pConsumer) Converts the given Functions.FailableBiConsumer into a standard BiConsumer.
static <I1,I2,O> BiFunction<I1,I2,O>	asBiFunction(Functions.FailableBiFunction<I1,I2,O,?> pFunction) Converts the given Functions.FailableBiFunction into a standard BiFunction.
static <I1,I2> BiPredicate<I1,I2>	asBiPredicate(Functions.FailableBiPredicate<I1,I2,?> pPredicate) Converts the given Functions.FailableBiPredicate into a standard BiPredicate.
static <O> Callable<O>	asCallable(Functions.FailableCallable<O,?> pCallable) Converts the given Functions.FailableCallable into a standard Callable.
static <I> Consumer<I>	asConsumer(Functions.FailableConsumer<I,?> pConsumer) Converts the given Functions.FailableConsumer into a standard Consumer.
static <I,O> Function<I,O>	asFunction(Functions.FailableFunction<I,O,?> pFunction) Converts the given Functions.FailableFunction into a standard Function.
static <I> Predicate<I>	asPredicate(Functions.FailablePredicate<I,?> pPredicate) Converts the given Functions.FailablePredicate into a standard Predicate.
static Runnable	asRunnable(Functions.FailableRunnable<?> pRunnable) Converts the given Functions.FailableRunnable into a standard Runnable.
static <O> Supplier<O>	asSupplier(Functions.FailableSupplier<O,?> pSupplier) Converts the given Functions.FailableSupplier into a standard Supplier.
static <O,T extends Throwable> O	call(Functions.FailableCallable<O,T> pCallable) Calls a callable and rethrows any exception as a RuntimeException.
static <O,T extends Throwable> O	get(Functions.FailableSupplier<O,T> pSupplier) Invokes the supplier, and returns the result.
static RuntimeException	rethrow(Throwable pThrowable) Rethrows a Throwable as an unchecked exception.
static <T extends Throwable> void	run(Functions.FailableRunnable<T> pRunnable) Runs a runnable and rethrows any exception as a RuntimeException.
static <O1,O2,T extends Throwable> boolean	test(Functions.FailableBiPredicate<O1,O2,T> pPredicate, O1 pObject1, O2 pObject2) Tests a predicate and rethrows any exception as a RuntimeException.
static <O,T extends Throwable> boolean	test(Functions.FailablePredicate<O,T> pPredicate, O pObject) Tests a predicate and rethrows any exception as a RuntimeException.
static void	tryWithResources(Functions.FailableRunnable<? extends Throwable> pAction, Functions.FailableConsumer<Throwable,? extends Throwable> pErrorHandler, Functions.FailableRunnable<? extends Throwable>... pResources) A simple try-with-resources implementation, that can be used, if your objects do not implement the AutoCloseable interface.
static void	tryWithResources(Functions.FailableRunnable<? extends Throwable> pAction, Functions.FailableRunnable<? extends Throwable>... pResources) A simple try-with-resources implementation, that can be used, if your objects do not implement the AutoCloseable interface.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Functions

public Functions()

Method Detail

asRunnable

public static Runnable asRunnable(Functions.FailableRunnable<?> pRunnable)

Converts the given Functions.FailableRunnable into a standard Runnable.

Parameters:

pRunnable - a FailableRunnable

Returns:

a standard Runnable

asConsumer

public static <I> Consumer<I> asConsumer(Functions.FailableConsumer<I,?> pConsumer)

Converts the given Functions.FailableConsumer into a standard Consumer.

Type Parameters:

I - the type used by the consumers

Parameters:

pConsumer - a FailableConsumer

Returns:

a standard Consumer

asCallable

public static <O> Callable<O> asCallable(Functions.FailableCallable<O,?> pCallable)

Converts the given Functions.FailableCallable into a standard Callable.

Type Parameters:

O - the type used by the callables

Parameters:

pCallable - a FailableCallable

Returns:

a standard Callable

asBiConsumer

public static <I1,I2> BiConsumer<I1,I2> asBiConsumer(Functions.FailableBiConsumer<I1,I2,?> pConsumer)

Converts the given Functions.FailableBiConsumer into a standard BiConsumer.

Type Parameters:

I1 - the type of the first argument of the consumers

I2 - the type of the second argument of the consumers

Parameters:

pConsumer - a failable BiConsumer

Returns:

a standard BiConsumer

asFunction

public static <I,O> Function<I,O> asFunction(Functions.FailableFunction<I,O,?> pFunction)

Converts the given Functions.FailableFunction into a standard Function.

Type Parameters:

I - the type of the input of the functions

O - the type of the output of the functions

Parameters:

pFunction - a {code FailableFunction}

Returns:

a standard Function

asBiFunction

public static <I1,I2,O> BiFunction<I1,I2,O> asBiFunction(Functions.FailableBiFunction<I1,I2,O,?> pFunction)

Converts the given Functions.FailableBiFunction into a standard BiFunction.

Type Parameters:

I1 - the type of the first argument of the input of the functions

I2 - the type of the second argument of the input of the functions

O - the type of the output of the functions

Parameters:

pFunction - a FailableBiFunction

Returns:

a standard BiFunction

asPredicate

public static <I> Predicate<I> asPredicate(Functions.FailablePredicate<I,?> pPredicate)

Converts the given Functions.FailablePredicate into a standard Predicate.

Type Parameters:

I - the type used by the predicates

Parameters:

pPredicate - a FailablePredicate

Returns:

a standard Predicate

asBiPredicate

public static <I1,I2> BiPredicate<I1,I2> asBiPredicate(Functions.FailableBiPredicate<I1,I2,?> pPredicate)

Converts the given Functions.FailableBiPredicate into a standard BiPredicate.

Type Parameters:

I1 - the type of the first argument used by the predicates

I2 - the type of the second argument used by the predicates

Parameters:

pPredicate - a FailableBiPredicate

Returns:

a standard BiPredicate

asSupplier

public static <O> Supplier<O> asSupplier(Functions.FailableSupplier<O,?> pSupplier)

Converts the given Functions.FailableSupplier into a standard Supplier.

Type Parameters:

O - the type supplied by the suppliers

Parameters:

pSupplier - a FailableSupplier

Returns:

a standard Supplier

run

public static <T extends Throwable> void run(Functions.FailableRunnable<T> pRunnable)

Runs a runnable and rethrows any exception as a RuntimeException.

Type Parameters:

T - the type of checked exception the runnable may throw

Parameters:

pRunnable - The runnable to run

call

public static <O,T extends Throwable> O call(Functions.FailableCallable<O,T> pCallable)

Calls a callable and rethrows any exception as a RuntimeException.

Type Parameters:

O - the return type of the callable

T - the type of checked exception the callable may throw

Parameters:

pCallable - the callable to call

Returns:

the value returned from the callable

accept

public static <O,T extends Throwable> void accept(Functions.FailableConsumer<O,T> pConsumer,
                                                  O pObject)

Consumes a consumer and rethrows any exception as a RuntimeException.

Type Parameters:

O - the type the consumer accepts

T - the type of checked exception the consumer may throw

Parameters:

pConsumer - the consumer to consume

pObject - the object to consume by pConsumer

accept

public static <O1,O2,T extends Throwable> void accept(Functions.FailableBiConsumer<O1,O2,T> pConsumer,
                                                      O1 pObject1,
                                                      O2 pObject2)

Consumes a consumer and rethrows any exception as a RuntimeException.

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

Parameters:

pConsumer - the consumer to consume

pObject1 - the first object to consume by pConsumer

pObject2 - the second object to consume by pConsumer

apply

public static <I,O,T extends Throwable> O apply(Functions.FailableFunction<I,O,T> pFunction,
                                                I pInput)

Applies a function and rethrows any exception as a RuntimeException.

Type Parameters:

I - 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

Parameters:

pFunction - the function to apply

pInput - the input to apply pFunction on

Returns:

the value returned from the function

apply

public static <I1,I2,O,T extends Throwable> O apply(Functions.FailableBiFunction<I1,I2,O,T> pFunction,
                                                    I1 pInput1,
                                                    I2 pInput2)

Applies a function and rethrows any exception as a RuntimeException.

Type Parameters:

I1 - the type of the first argument the function accepts

I2 - 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

Parameters:

pFunction - the function to apply

pInput1 - the first input to apply pFunction on

pInput2 - the second input to apply pFunction on

Returns:

the value returned from the function

test

public static <O,T extends Throwable> boolean test(Functions.FailablePredicate<O,T> pPredicate,
                                                   O pObject)

Tests a predicate and rethrows any exception as a RuntimeException.

Type Parameters:

O - the type of argument the predicate tests

T - the type of checked exception the predicate may throw

Parameters:

pPredicate - the predicate to test

pObject - the input to test by pPredicate

Returns:

the boolean value returned by the predicate

test

public static <O1,O2,T extends Throwable> boolean test(Functions.FailableBiPredicate<O1,O2,T> pPredicate,
                                                       O1 pObject1,
                                                       O2 pObject2)

Tests a predicate and rethrows any exception as a RuntimeException.

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

Parameters:

pPredicate - the predicate to test

pObject1 - the first input to test by pPredicate

pObject2 - the second input to test by pPredicate

Returns:

the boolean value returned by the predicate

get

public static <O,T extends Throwable> O get(Functions.FailableSupplier<O,T> pSupplier)

Invokes the supplier, and returns the result.

Type Parameters:

O - The suppliers output type.

T - The type of checked exception, which the supplier can throw.

Parameters:

pSupplier - The supplier to invoke.

Returns:

The object, which has been created by the supplier

tryWithResources

@SafeVarargs
public static void tryWithResources(Functions.FailableRunnable<? extends Throwable> pAction,
                                                 Functions.FailableConsumer<Throwable,? extends Throwable> pErrorHandler,
                                                 Functions.FailableRunnable<? extends Throwable>... pResources)

A simple try-with-resources implementation, that can be used, if your objects do not implement the AutoCloseable interface. The method executes the pAction. The method guarantees, that all the pResources 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:

pAction - The action to execute. This object will always be invoked.

pErrorHandler - An optional error handler, which will be invoked finally, if any error occurred. The error handler will receive the first error, aka Throwable.

pResources - The resource actions to execute. All resource actions will be invoked, in the given order. A resource action is an instance of Functions.FailableRunnable, which will be executed.

See Also:

tryWithResources(FailableRunnable, FailableRunnable...)

tryWithResources

@SafeVarargs
public static void tryWithResources(Functions.FailableRunnable<? extends Throwable> pAction,
                                                 Functions.FailableRunnable<? extends Throwable>... pResources)

A simple try-with-resources implementation, that can be used, if your objects do not implement the AutoCloseable interface. The method executes the pAction. The method guarantees, that all the pResources 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), () -> fis.close());
 

Parameters:

pAction - The action to execute. This object will always be invoked.

pResources - The resource actions to execute. All resource actions will be invoked, in the given order. A resource action is an instance of Functions.FailableRunnable, which will be executed.

See Also:

tryWithResources(FailableRunnable, FailableConsumer, FailableRunnable...)

rethrow

public static RuntimeException rethrow(Throwable pThrowable)

Rethrows a Throwable as an unchecked exception.

Parameters:

pThrowable - The throwable to rethrow

Returns:

Never returns anything, this method never terminates normally