Powerunit-extensions-exceptions

This version doesn't support anymore Java 9. Please use an older version, for instance the version 2.2.0

This library provides support to wraps checked exception, to be used as target functional interface (which by default only support RuntimeException).

The library exposes several functional interface, similar to the one from java.util.function, but that may throw exception. Then several methods are provided to convert these exception to RuntimeException or lift the function.

For example:

FunctionWithException<String, String, IOException> fonctionThrowingException = ...;

Function<String, String> functionThrowingRuntimeException = FunctionWithException
  .unchecked(fonctionThrowingException);

wraps the exception from IOException into a RuntimeException (which cause is the original one).

Usage

Add the following dependency to your maven project :

<dependency>
  <groupId>ch.powerunit.extensions</groupId>
  <artifactId>powerunit-extensions-exceptions</artifactId>
  <version>3.0.0</version>
</dependency>

And then just use the interface from the package ch.powerunit.extensions.exceptions. Each available interface has a name similar with the one from the java.util.function package, but ending with WithException. Three essential static entry methods are available :

Method	Description	Example
unchecked	Converts the functional interface to the one without exception, by wrapping the exception to a RuntimeException	FunctionWithException<T,R,E> to Function<T,R>
lifted	Converts the functional interface to the one without exception, by returning an Optional or a default value in case of exception (or ignore exception for interface without return value)	FunctionWithException<T,R,E> to Function<T,Optional<R>>
ignored	Converts the functional interface to the one without exception, by returning a default value in case of exception (or ignore exception for interface without return value)	FunctionWithException<T,R,E> to Function<T,R>

Also, non static version (uncheck, lift, ignore) of the methods are available.

The method unchecked also support an additional parameter to define how to wrap the exception by passing a Function<Exception,RuntimeException> to do it.

An additional method stage(d) is also available on several interface.

uncheck(ed)

This method converts the functional interface to the one without exception, by wrapping the exception to a RuntimeException.

Three versions of this methods exists :

• uncheck() converting the functional interface directly.

  FunctionWithException<String,String,IOException> myFunction = ...;
  
  Function<String,String> myUncheckedFunction = myFunction.uncheck();

• unchecked(myInterface) converting the received parameter.

  Function<String,String> myUncheckedFunction = FunctionWithException.unchecked(x->x);

• unchecked(myInterface,myExceptionMapper) converting the received parameter, and using the received exception mapper to wrap the exception.

  Function<String,String> myUncheckedFunction = 
    FunctionWithException.unchecked(
      x->x,
      IllegalArgumentException::new
    );

  The resulting exceptions are :

  Original With Exception Interface	Uncheck(ed) without exception mapper	Unchecked with exception mapper
  The original exception	An instance of ch.powerunit.extensions.exceptions.WrappedException having the original exception as cause	A instance of RuntimeException returned by the exception mapper

  A more concrete example may be :

  Function<Exception, RuntimeException> mapper = 
    ExceptionMapper.forException(
      SQLException.class,
      s -> 
           new WrappedException(
             String.format(
               "%s ; ErrorCode=%s ; SQLState=%s", 
               s.getMessage(),
               s.getErrorCode(), 
               s.getSQLState()
             ), 
             s
           )
    );

  In this example, it extracts the SQL information from the SQLException. The exceptionMapperFor method ensures that in case the exception is not a SQLException, a standard wrapping is done. Please see the dedicated section for more information.

lift(ed)

This method converts the functional interface to the one without exception, by returning an Optional or a default value in case of exception or ignore the exception for interface without return value.

Two versions of this methods exists :

• lift() converting the functional interface directly.

  FunctionWithException<String,String,IOException> myFunction = ...;
  
  Function<String,Optional<String>> myLiftedFunction = myFunction.lift();

• lifted(myInterface) converting the received parameter.

  Function<String,Optional<String>> myLiftedFunction = FunctionWithException.lifted(x->x);

ignore(d)

This method converts the functional interface to the one without exception, by returning a default value in case of exception or ignore the exception for interface without return value.

Two versions of this methods exists :

• ignore() converting the functional interface directly.

  FunctionWithException<String,String,IOException> myFunction = ...;
  
  Function<String,String> myLiftedFunction = myFunction.ignore();

• ignored(myInterface) converting the received parameter.

  Function<String,String> myLiftedFunction = FunctionWithException.ignored(x->x);

stage(d)

This method converts the functional interface to the one without exception, by returning an CompletionStage. This is not available on interface returning primitive type.

For functional interface without result, a CompletionStage<Void> is returned.

Two versions of this methods exists :

• stage() converting the functional interface directly.

  FunctionWithException<String,String,IOException> myFunction = ...;
  
  Function<String,CompletionStage<String>> myStagedFunction = myFunction.stage();

• staged(myInterface) converting the received parameter.

  Function<String,CompletionStage<String>> myStagedFunction = FunctionWithException.staged(x->x);

Exception Mapper

The various methods forExceptions from ExceptionMapper provides a way to chain several Exception Mapper.

Also, some dedicated, ready to used, Exception Mapper are provided :

• sqlExceptionMapper() - Return an exception mapper that adds to the message of the RuntimeException the SQL Error from the underlying exception. This is only usable when the module java.sql is available.
• jaxbExceptionMapper() - Return an exception mapper that adds to the message of the RuntimeException the JAXB Error from the underlying exception. This is only usable when JAXB is available.
• saxExceptionMapper() - Return an exception mapper that adds to the message of the RuntimeException the SAX Error from the underlying exception. This is only usable when the module java.xml is available.
• transformerExceptionMapper() - Return an exception mapper that adds to the message of the RuntimeException the Transformer Error from the underlying exception. This is only usable when the module java.xml is available.

Define global ExceptionMapper

It is possible to define a default exception mappers by using service loader.

By default, the exception are wrapped in a WrappedException. This behaviour may be change by implementing the required ExceptionMapper and register them as service implementation.

To do so, create all the required implementation, for example :

public class MyExceptionMapper implements ch.powerunit.extensions.exceptions.ExceptionMapper {
  public RuntimeException apply(Exception e) {
    //Add code here
  }

  public Class<? extends Exception> targetException() {
    return //Add code here;
  }
	
  // Optional, to define the order between the ExceptionMapper
  public int order() {
    return 100;
  }

}

Then this may be registered in the module-info.java file:

module XXX {
  requires powerunit.exceptions;

  provides ch.powerunit.extensions.exceptions.ExceptionMapper
    with ....MyExceptionMapper;
}

CommonsCollections4Helper

This helper is only available if the commons-collections4 library is available

The class CommonsCollections4Helper provides several static methods to convert interface from this library to the corresponding version in commons-collections4.

Reference

The following classes are provided:

Standard functional interface	Exception functional interface	Unchecked version	Lifted version	Ignored version	Stage version
BiFunction<T,U,R>	BiFunctionWithException<T,U,R,E>	BiFunction<T,U,R>	BiFunction<T,U,Optional<R>>	BiFunction<T,U,R>	BiFunction<T,U,CompletionStage<R>>
BiConsumer<T,U>	BiConsumerWithException<T,U,E>	BiConsumer<T,U>	BiConsumer<T,U>	BiConsumer<T,U>	BiFunction<T,U,CompletionStage<Void>>
BiPredicate<T,U>	BiPredicateWithException<T,U,E>	BiPredicate<T,U>	BiPredicate<T,U>	BiPredicate<T,U>	N/A
BinaryOperator<T>	BinaryOperatorWithException<T,E>	BinaryOperator<T,U>	BinaryFunction<T,T,Optional<T>>	BinaryOperator<T>	BinaryFunction<T,T,CompletionStage<T>>
BooleanSupplier	BooleanSupplierWithException<E>	BooleanSupplier	BooleanSupplier	BooleanSupplier	N/A
Consumer<T>	ConsumerWithException<T,E>	Consumer<T>	Consumer<T>	Consumer<T>	Function<T,CompletionStage<Void>>
DoubleBinaryOperator	DoubleBinaryOperatorWithException<E>	DoubleBinaryOperator	DoubleBinaryOperator	DoubleBinaryOperator	N/A
DoubleConsumer	DoubleConsumerWithException<E>	DoubleConsumer	DoubleConsumer	DoubleConsumer	DoubleFunction<CompletionStage<Void>>
DoubleFunction<R>	DoubleFunctionWithException<R,E>	DoubleFunction<R>	DoubleFunction<Optional<R>>	DoubleFunction<R>	DoubleFunction<CompletionStage<R>>
DoublePredicate	DoublePredicateWithException<E>	DoublePredicate	DoublePredicate	DoublePredicate	N/A
DoubleSupplier	DoubleSupplierWithException<E>	DoubleSupplier	DoubleSupplier	DoubleSupplier	N/A
DoubleToIntFunction	DoubleToIntFunctionWithException<E>	DoubleToIntFunction	DoubleToIntFunction	DoubleToIntFunction	N/A
DoubleToLongFunction	DoubleToLongFunctionWithException<E>	DoubleToLongFunction	DoubleToLongFunction	DoubleToLongFunction	N/A
DoubleUnaryOperator	DoubleUnaryOperatorWithException<E>	DoubleUnaryOperator	DoubleUnaryOperator	DoubleUnaryOperator	N/A
FileFilter	FileFilterWithException<E>	FileFilter	FileFilter	FileFilter	N/A
FilenameFilter	FilenameFilterWithException<E>	FilenameFilter	FilenameFilter	FilenameFilter	N/A
Function<T,R>	FunctionWithException<T,R,E>	Function<T,R>	Function<T,Optional<R>>	Function<T,R>	Function<T,CompletionStage<R>>
IntBinaryOperator	IntBinaryOperatorWithException<E>	IntBinaryOperator	IntBinaryOperator	IntBinaryOperator	N/A
IntConsumer	IntConsumerWithException<E>	IntConsumer	IntConsumer	IntConsumer	IntFunction<CompletionStage<Void>>
IntFunction<R>	IntFunctionWithException<R,E>	IntFunction<R>	IntFunction<Optional<R>>	IntFunction<R>	IntFunction<CompletionStage<R>>
IntPredicate	IntPredicateWithException<E>	IntPredicate	IntPredicate	IntPredicate	N/A
IntSupplier	IntSupplierWithException<E>	IntSupplier	IntSupplier	IntSupplier	N/A
IntToDoubleFunction	IntToDoubleFunctionWithException<E>	IntToDoubleFunction	IntToDoubleFunction	IntToDoubleFunction	N/A
IntToLongFunction	IntToLongFunctionWithException<E>	IntToLongFunction	IntToLongFunction	IntToLongFunction	N/A
IntUnaryOperator	IntUnaryOperatorWithException<E>	IntUnaryOperator	IntUnaryOperator	IntUnaryOperator	N/A
LongBinaryOperator	LongBinaryOperatorWithException<E>	LongBinaryOperator	LongBinaryOperator	LongBinaryOperator	N/A
LongConsumer	LongConsumerWithException<E>	LongConsumer	LongConsumer	LongConsumer	LongFunction<CompletionStage<Void>>
LongFunction<R>	LongFunctionWithException<R,E>	LongFunction<R>	LongFunction<Optional<R>>	LongFunction<R>	LongFunction<CompletionStage<R>>
LongPredicate	LongPredicateWithException<E>	LongPredicate	LongPredicate	LongPredicate	N/A
LongSupplier	LongSupplierWithException<E>	LongSupplier	LongSupplier	LongSupplier	N/A
LongToDoubleFunction	LongToDoubleFunctionWithException<E>	LongToDoubleFunction	LongToDoubleFunction	LongToDoubleFunction	N/A
LongToIntFunction	LongToIntFunctionWithException	LongToIntFunction	LongToIntFunction	LongToIntFunction	N/A
LongUnaryOperator	LongUnaryOperatorWithException	LongUnaryOperator	LongUnaryOperator	LongUnaryOperator	N/A
ObjectInputFilter	ObjectInputFilterWithException<T,R,E>	ObjectInputFilter	Function<FilterInfo,Optional<Status>>	ObjectInputFilter	Function<FilterInfo,CompletionStage<Status>>
ObjDoubleConsumer<T>	ObjDoubleConsumerWithException<T,E>	ObjDoubleConsumer<T>	ObjDoubleConsumer<T>	ObjDoubleConsumer<T>	Function<T,Double,CompletionStage<Void>>
ObjIntConsumer<T>	ObjIntConsumerWithException<T,E>	ObjIntConsumer<T>	ObjIntConsumer<T>	ObjIntConsumer<T>	Function<T,Integer,CompletionStage<Void>>
ObjLongConsumer<T>	ObjLongConsumerWithException<T,E>	ObjLongConsumer<T>	ObjLongConsumer<T>	ObjLongConsumer<T>	Function<T,Long,CompletionStage<Void>>
PathMatcher	PathMatcherWithException<E>	PathMatcher	PathMatcher	PathMatcher	N/A
Predicate<T>	PredicateWithException<T,E>	Predicate<T>	Predicate<T>	Predicate<T>	N/A
Runnable	RunnableWithException<E>	Runnable	Runnable	Runnable	Supplier<CompletionStage<Void>>
Supplier<T>	SupplierWithException<T,E>	Supplier<T>	Supplier<Optional<T>>	Supplier<T>	Supplier<CompletionStage<T>>
ToDoubleBiFunction<T,U>	ToDoubleBiFunctionWithException<T,U,E>	ToDoubleBiFunction<T,U>	ToDoubleBiFunction<T,U>	ToDoubleBiFunction<T,U>	N/A
ToDoubleFunction<T>	ToDoubleFunctionWithException<T,E>	ToDoubleFunction<T>	ToDoubleFunction<T>	ToDoubleFunction<T>	N/A
ToIntBiFunction<T,U>	ToIntBiFunctionWithException<T,U,E>	ToIntBiFunction<T,U>	ToIntBiFunction<T,U>	ToIntBiFunction<T,U>	N/A
ToIntFunction<T>	ToIntFunctionWithException<T,E>	ToIntFunction<T>	ToIntFunction<T>	ToIntFunction<T>	N/A
ToLongBiFunction<T,U>	ToLongBiFunctionWithException<T,U,E>	ToLongBiFunction<T,U>	ToLongBiFunction<T,U>	ToLongBiFunction<T,U>	N/A
ToLongFunction<T>	ToLongFunctionWithException<T,E>	ToLongFunction<T>	ToLongFunction<T>	ToLongFunction<T>	N/A
UnaryOperator<T>	UnaryOperatorWithException<T,E>	UnaryOperator<T>	Function<T,Optional<T>>	UnaryOperator<T>	Function<T,CompletionStage<T>>