Module dk.cloudcreate.essentials.shared

Package dk.cloudcreate.essentials.shared.functional

Interface CheckedRunnable

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 CheckedRunnable

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

See Also:

• safe(CheckedRunnable)
• safe(String, CheckedRunnable)

Method Summary

Modifier and Type	Method	Description
void	run()	This method performs the operation that may fail with a Checked Exception
static Runnable	safe(CheckedRunnable runnableThatCanFailWithACheckedException)	Wraps a CheckedRunnable (basically a lambda with no arguments that doesn't return any result and which throws a Checked Exception) by returning a new Runnable instance The returned Runnable.run() method delegates directly to the run() and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException Unless you provide a context-message (using safe(String, CheckedRunnable) 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 Runnable with the purpose of the calling the Runnable.run().
static Runnable	safe(String contextMessage, CheckedRunnable runnableThatCanFailWithACheckedException)	Wraps a CheckedRunnable (basically a lambda with no arguments that doesn't return any result and which throws a Checked Exception) by returning a new Runnable instance The returned Runnable.run() method delegates directly to the run() 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 Runnable with the purpose of the calling the Runnable.run().

Method Details

safe

static Runnable safe(CheckedRunnable runnableThatCanFailWithACheckedException)

Wraps a CheckedRunnable (basically a lambda with no arguments that doesn't return any result and which throws a Checked Exception) by returning a new Runnable instance
The returned Runnable.run() method delegates directly to the run() and catches any thrown checked Exception's and rethrows them as a CheckedExceptionRethrownException
Unless you provide a context-message (using safe(String, CheckedRunnable) 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 Runnable with the purpose of the calling the Runnable.run().

 public void someOperation(Runnable operation) {
      // ... Logic ...

      operation.run();

      // ... More logic ---
 }
 

The problem will Runnable.run() occurs when Runnable calls any API that throws a checked Exception, e.g. the File API.
Since Runnable.run() 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(() -> {
                      try {
                          // Logic that uses the File API
                      } catch (IOException e) {
                          throw new RuntimeException(e);
                      }
                }));
 

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

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

Parameters:

runnableThatCanFailWithACheckedException - the CheckedRunnable instance that will be wrapped as a Runnable

Returns:

a Runnable with a Runnable.run() method that ensures that the run() method is called when Runnable.run() 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 run() method throws a checked Exception

safe

static Runnable safe(String contextMessage,
 CheckedRunnable runnableThatCanFailWithACheckedException)

Wraps a CheckedRunnable (basically a lambda with no arguments that doesn't return any result and which throws a Checked Exception) by returning a new Runnable instance
The returned Runnable.run() method delegates directly to the run() 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 Runnable with the purpose of the calling the Runnable.run().

 public void someOperation(Runnable operation) {
      // ... Logic ...

      operation.run();

      // ... More logic ---
 }
 

The problem will Runnable.run() occurs when Runnable calls any API that throws a checked Exception, e.g. the File API.
Since Runnable.run() 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(() -> {
                      try {
                          // Logic that uses the File API
                      } catch (IOException e) {
                          throw new RuntimeException(e);
                      }
                }));
 

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

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

Parameters:

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

runnableThatCanFailWithACheckedException - the CheckedRunnable instance that will be wrapped as a Runnable

Returns:

a Runnable with a Runnable.run() method that ensures that the run() method is called when Runnable.run() 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 run() method throws a checked Exception

run

void run()
  throws Exception

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

Throws:

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