Module dk.cloudcreate.essentials.shared

Package dk.cloudcreate.essentials.shared.functional

Interface CheckedConsumer<T>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface CheckedConsumer<T>

Variant of Consumer that behaves like Consumer, but which allows checked Exception's to be thrown from its accept(Object) method

See Also:

safe(CheckedConsumer), – the consumer argument type

Method Summary

Modifier and Type	Method	Description
void	accept(T arg)	This method performs the operation that may fail with a Checked Exception
static <T> Consumer<T>	safe(CheckedConsumer<T> runnableThatCanFailWithACheckedException)	Wraps a CheckedConsumer (basically a lambda with one argument that doesn't return any result and which throws a Checked Exception) by returning a new Consumer instance The returned Consumer.accept(Object) method delegates directly to the accept(Object) and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException Unless you provide a context-message (using safe(String, CheckedConsumer) then any caught checked Exception's message also becomes the CheckedExceptionRethrownException's message. Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown. Usage example: Let's say we have a method called someOperation that cannot change, but which accepts a Consumer with the purpose of the calling the Consumer.accept(Object).
static <T> Consumer<T>	safe(String contextMessage, CheckedConsumer<T> runnableThatCanFailWithACheckedException)	Wraps a CheckedConsumer (basically a lambda with one argument that doesn't return any result and which throws a Checked Exception) by returning a new Consumer instance The returned Consumer.accept(Object) method delegates directly to the accept(Object) and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown. Usage example: Let's say we have a method called someOperation that cannot change, but which accepts a Consumer with the purpose of the calling the Consumer.accept(Object).

Method Detail

safe

static <T> Consumer<T> safe(CheckedConsumer<T> runnableThatCanFailWithACheckedException)

Wraps a CheckedConsumer (basically a lambda with one argument that doesn't return any result and which throws a Checked Exception) by returning a new Consumer instance
The returned Consumer.accept(Object) method delegates directly to the accept(Object) and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException
Unless you provide a context-message (using safe(String, CheckedConsumer) then any caught checked Exception's message also becomes the CheckedExceptionRethrownException's message.
Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown.

Usage example:
Let's say we have a method called someOperation that cannot change, but which accepts a Consumer with the purpose of the calling the Consumer.accept(Object).

 public void someOperation(Consumer<String> operation) {
      // ... Logic ...

      operation.accept("some-value");

      // ... More logic ---
 }
 

The problem will Consumer.accept(Object) occurs when Consumer calls any API that throws a checked Exception, e.g. the File API.
Since Consumer.accept(Object) doesn't define that it throws any Exception's we're forced to add a try/catch to handle the IOException for the code to compile:

  someOperation(value -> {
                      try {
                          // Logic that uses the File API
                      } catch (IOException e) {
                          throw new RuntimeException(e);
                      }
                }));
 

This is where the CheckedConsumer comes to the aid as its accept(Object) methods defines that it throws a Checked Exception and its safe(CheckedConsumer) will return a new Consumer instance with a Consumer.accept(Object) method that ensures that the accept(Object) method is called and any checked Exception's thrown will be caught and rethrown as a CheckedExceptionRethrownException:

  someOperation(CheckedConsumer.safe(value -> {
                      // Logic that uses the File API that throws IOException
                }));
 
 

Parameters:

runnableThatCanFailWithACheckedException - the CheckedConsumer instance that will be wrapped as a Consumer

Returns:

a Consumer with a Consumer.accept(Object) method that ensures that the accept(Object) method is called when Consumer.accept(Object) and any checked Exception's thrown will be caught and rethrown as a CheckedExceptionRethrownException.
Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown.

Throws:

CheckedExceptionRethrownException - in case the accept(Object) method throws a checked Exception

safe

static <T> Consumer<T> safe(String contextMessage,
                            CheckedConsumer<T> runnableThatCanFailWithACheckedException)

Wraps a CheckedConsumer (basically a lambda with one argument that doesn't return any result and which throws a Checked Exception) by returning a new Consumer instance
The returned Consumer.accept(Object) method delegates directly to the accept(Object) and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException
Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown.

Usage example:
Let's say we have a method called someOperation that cannot change, but which accepts a Consumer with the purpose of the calling the Consumer.accept(Object).

 public void someOperation(Consumer<String> operation) {
      // ... Logic ...

      operation.accept("some-value");

      // ... More logic ---
 }
 

The problem will Consumer.accept(Object) occurs when Consumer calls any API that throws a checked Exception, e.g. the File API.
Since Consumer.accept(Object) doesn't define that it throws any Exception's we're forced to add a try/catch to handle the IOException for the code to compile:

  someOperation(value -> {
                      try {
                          // Logic that uses the File API
                      } catch (IOException e) {
                          throw new RuntimeException(e);
                      }
                }));
 

This is where the CheckedConsumer comes to the aid as its accept(Object) methods defines that it throws a Checked Exception and its safe(CheckedConsumer) will return a new Consumer instance with a Consumer.accept(Object) method that ensures that the accept(Object) method is called and any checked Exception's thrown will be caught and rethrown as a CheckedExceptionRethrownException:

  someOperation(CheckedConsumer.safe(msg("Processing file {}", fileName),
                                     value -> {
                                        // Logic that uses the File API that throws IOException
                                     }));
 
 

Parameters:

contextMessage - a string that the described the content for the CheckedConsumer and which will be used as message in any CheckedExceptionRethrownException thrown

runnableThatCanFailWithACheckedException - the CheckedConsumer instance that will be wrapped as a Consumer

Returns:

a Consumer with a Consumer.accept(Object) method that ensures that the accept(Object) method is called when Consumer.accept(Object) and any checked Exception's thrown will be caught and rethrown as a CheckedExceptionRethrownException.
Any RuntimeException's thrown aren't caught and the calling code will receive the original RuntimeException thrown.

Throws:

CheckedExceptionRethrownException - in case the accept(Object) method throws a checked Exception

accept

void accept(T arg)
     throws Exception

This method performs the operation that may fail with a Checked Exception

Parameters:

arg - the argument to the consumer

Throws:

Exception - this method can throw both checked Exception's as well as RuntimeException's