com.diffplug.common.base

Class Errors

java.lang.Object

com.diffplug.common.base.Errors

All Implemented Interfaces:

Consumer<Throwable>

Direct Known Subclasses:

Errors.Handling, Errors.Rethrowing

public abstract class Errors
extends Object
implements Consumer<Throwable>

Converts functions which throw exceptions into functions that don’t by passing exceptions to an error policy.

Let’s say you have a method void eat(Food food) throws Barf, and you wanted to pass a List<Food> to this method.

List<Food> foodOnPlate = Arrays.asList(
    cook("salmon"),
    cook("asparagus"),
    cook("enterotoxin"));

// without Errors, we have to write this
foodOnPlate.forEach(val -> {
    try {
        eat(val);
    } catch (Barf e) {
        // get out the baking soda
    }
});

Because the Consumer required by Iterable.forEach(Consumer) doesn’t allow checked exceptions, and void eat(Food food) throws Barf has a checked exception, we can’t take advantage of method references.

With Errors, we can do this succinctly:

//                         sweep it under the rug
foodOnPlate.forEach(Errors.suppress().wrap(this::eat));
//                         save it for later
foodOnPlate.forEach(Errors.log().wrap(this::eat));
//                         make mom deal with it
foodOnPlate.forEach(Errors.rethrow().wrap(this::eat));
//                         ask the user deal with it
foodOnPlate.forEach(Errors.dialog().wrap(this::eat));

Errors comes with four built-in error handling policies: suppress(), log(), rethrow(), and dialog(). If you don’t like their default behaviors, you can change them using Errors.Plugins and DurianPlugins.

You can also create your own error handling policies using createHandling(Consumer) and createRethrowing(Function).

For a deep-dive into how Errors works, see ErrorsExample.java.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Errors.ConstrainedTo<E extends Throwable> Generated by calling constrainTo(Class).
static class	Errors.Handling An Errors which is free to rethrow the exception, but it might not.
static interface	Errors.Plugins Namespace for the plugins which Errors supports.
static class	Errors.Rethrowing An Errors which is guaranteed to always throw a RuntimeException.
static class	Errors.WrappedAsRuntimeException A RuntimeException specifically for the purpose of wrapping non-runtime Throwables as RuntimeExceptions.

Field Summary

Fields

Modifier and Type	Field and Description
protected Consumer<Throwable>	handler

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Errors(Consumer<Throwable> error)

Method Summary

Modifier and Type	Method and Description
void	accept(Throwable error) Passes the given error to this Errors.
static RuntimeException	asRuntime(Throwable e) Casts or wraps the given exception to be a RuntimeException.
Consumer<Optional<Throwable>>	asTerminal() Converts this Consumer<Throwable> to a Consumer<Optional<Throwable>>.
static <E extends Throwable> Errors.ConstrainedTo<E>	constrainTo(Class<E> exceptionClass) A fluent API for calling functions which throw an overly-broad exception (e.g.
static Errors.Handling	createHandling(Consumer<Throwable> handler) Creates an Errors.Handling which passes any exceptions it receives to the given handler.
static Errors.Rethrowing	createRethrowing(Function<Throwable,RuntimeException> transform) Creates an Errors.Rethrowing which transforms any exceptions it receives into a RuntimeException as specified by the given function, and then throws that RuntimeException.
static Errors.Handling	dialog() Opens a dialog to notify the user of any exceptions.
static Errors.Handling	log() Logs any exceptions.
static Errors.Rethrowing	rethrow() Rethrows any exceptions as runtime exceptions.
void	run(Throwing.Runnable runnable) Attempts to run the given runnable.
static Errors.Handling	suppress() Suppresses errors entirely.
<T> Consumer<T>	wrap(Throwing.Consumer<T> consumer) Returns a Consumer whose exceptions are handled by this Errors.
Runnable	wrap(Throwing.Runnable runnable) Returns a Runnable whose exceptions are handled by this Errors.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.function.Consumer

andThen

Field Detail

handler

protected final Consumer<Throwable> handler

Constructor Detail

Errors

protected Errors(Consumer<Throwable> error)

Method Detail

createHandling

public static Errors.Handling createHandling(Consumer<Throwable> handler)

Creates an Errors.Handling which passes any exceptions it receives to the given handler.

The handler is free to throw a RuntimeException if it wants to. If it always throws a RuntimeException, then you should instead create an Errors.Rethrowing using createRethrowing(java.util.function.Function<java.lang.Throwable, java.lang.RuntimeException>).

createRethrowing

public static Errors.Rethrowing createRethrowing(Function<Throwable,RuntimeException> transform)

Creates an Errors.Rethrowing which transforms any exceptions it receives into a RuntimeException as specified by the given function, and then throws that RuntimeException.

If that function happens to throw an unchecked error itself, that’ll work just fine too.

suppress

public static Errors.Handling suppress()

Suppresses errors entirely.

rethrow

public static Errors.Rethrowing rethrow()

Rethrows any exceptions as runtime exceptions.

log

public static Errors.Handling log()

Logs any exceptions.

By default, log() calls Throwable.printStackTrace(). To modify this behavior in your application, call DurianPlugins.set(Errors.Plugins.Log.class, error -> myCustomLog(error));

See Also:

DurianPlugins, Errors.Plugins.OnErrorThrowAssertion

dialog

public static Errors.Handling dialog()

Opens a dialog to notify the user of any exceptions. It should be used in cases where an error is too severe to be silently logged.

By default, dialog() opens a JOptionPane. To modify this behavior in your application, call DurianPlugins.set(Errors.Plugins.Dialog.class, error -> openMyDialog(error));

For a non-interactive console application, a good implementation of would probably print the error and call System.exit().

See Also:

DurianPlugins, Errors.Plugins.OnErrorThrowAssertion

accept

public void accept(Throwable error)

Passes the given error to this Errors.

Specified by:

accept in interface Consumer<Throwable>

asTerminal

public Consumer<Optional<Throwable>> asTerminal()

Converts this Consumer<Throwable> to a Consumer<Optional<Throwable>>.

run

public void run(Throwing.Runnable runnable)

Attempts to run the given runnable.

wrap

public Runnable wrap(Throwing.Runnable runnable)

Returns a Runnable whose exceptions are handled by this Errors.

wrap

public <T> Consumer<T> wrap(Throwing.Consumer<T> consumer)

Returns a Consumer whose exceptions are handled by this Errors.

asRuntime

public static RuntimeException asRuntime(Throwable e)

Casts or wraps the given exception to be a RuntimeException.

If the input exception is a RuntimeException, it is simply cast and returned. Otherwise, it wrapped in a Errors.WrappedAsRuntimeException and returned.

constrainTo

public static <E extends Throwable> Errors.ConstrainedTo<E> constrainTo(Class<E> exceptionClass)

A fluent API for calling functions which throw an overly-broad exception (e.g. Throwable, Exception) in way that will throw the given exception unchanged, and rethrow other exceptions wrapped up in a RuntimeException according to asRuntime(Throwable).

Errors.constrainTo(IOException.class).run(() -> methodWhichThrowsSomethingTooBroad());
String result = Errors.constrainTo(IOException.class).get(() -> methodWhichThrowsSomethingTooBroad());