sirius.kernel.health

Class Exceptions

java.lang.Object

sirius.kernel.health.Exceptions

public class Exceptions
extends Object

Central point for handling all system errors and exceptions.

Provides various methods to handle errors and exceptions. Each method returns a HandledException which signals the developer that no further action is required (error is logged and reacted upon). Also, those exceptions always contain a translated error message which can be directly shown to the user

Nested Class Summary

Nested Classes

Modifier and Type

Class and Description

static class

Exceptions.ErrorHandler Fluent API to create a HandledException based on given parameters The intention is to use a call like: Exceptions.handler() .error(anException) // Sets the exception to handle .to(aLogger) // Sets the logger to use for logging .withNLSKey("nls.key") // Sets the i18n key to create the error message .set("param",value) // Sets a named parameter which occurs in the message .handle(); // logs an creates the HandledException Since none of the methods must be called (except handle() of course), this provides a lot of flexibility and permits to handle several different error situations without having methods with long parameter lists and lots of null values.

Field Summary

Fields

Modifier and Type	Field and Description
protected static Log	DEPRECATION_LOG Used to log warnings if deprecated APIs are called.
protected static Log	IGNORED_EXCEPTIONS_LOG Used to log exceptions which are normally just discarded.
protected static Log	LOG Used as a fallback logger, if no logger was provided.

Method Summary

Modifier and Type	Method and Description
static Exceptions.ErrorHandler	createHandled() Generates a new Exceptions.ErrorHandler which creates a HandledException without actually logging or processing it.
static Exceptions.ErrorHandler	handle() Generates a new Exceptions.ErrorHandler which gracefully handles all kinds of errors
static HandledException	handle(Log log, Throwable e) Boilerplate method the directly handle the given exception without a special message
static HandledException	handle(Throwable e) Boilerplate method the directly handle the given exception without a special message or logger
static void	ignore(Throwable t) Can be used to mark an exception as ignored.
static void	logDeprecatedMethodUse() Can be used to log if a deprecated method has been called.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

protected static final Log LOG

Used as a fallback logger, if no logger was provided. Logs everything as "errors".

IGNORED_EXCEPTIONS_LOG

protected static final Log IGNORED_EXCEPTIONS_LOG

Used to log exceptions which are normally just discarded. This are either exception handled with ignore(Throwable) or exceptions created by createHandled()

DEPRECATION_LOG

protected static final Log DEPRECATION_LOG

Used to log warnings if deprecated APIs are called.

See Also:

logDeprecatedMethodUse()

Method Detail

handle

public static Exceptions.ErrorHandler handle()

Generates a new Exceptions.ErrorHandler which gracefully handles all kinds of errors

Returns:

a new ErrorHandler to handle an error or exception

handle

public static HandledException handle(Throwable e)

Boilerplate method the directly handle the given exception without a special message or logger

Parameters:

e - the exception to handle

Returns:

a HandledException which notifies surrounding calls that an error occurred, which has already been taken care of.

handle

public static HandledException handle(Log log,
                                      Throwable e)

Boilerplate method the directly handle the given exception without a special message

Parameters:

log - the logger used to log the exception

e - the exception to handle

Returns:

a HandledException which notifies surrounding calls that an error occurred, which has already been taken care of.

createHandled

public static Exceptions.ErrorHandler createHandled()

Generates a new Exceptions.ErrorHandler which creates a HandledException without actually logging or processing it.

This can be used to generate a HandledException based on a user error (invalid input) which doesn't need to be logged.

Returns:

a new ErrorHandler to handle an error or exception

ignore

public static void ignore(Throwable t)

Can be used to mark an exception as ignored.

Instead of leading a try / catch block empty, the method can be invoked. Therefore it is known, that the exception is wanted to be ignored. Additionally, the ignoredExceptions logger can be turned on, to still see those exceptions.

Parameters:

t - the exception to be ignored. This exception will be discarded unless the ignoredExceptions logger is set to INFO.

logDeprecatedMethodUse

public static void logDeprecatedMethodUse()

Can be used to log if a deprecated method has been called.

This method must be called from the deprecated one and will report the name of the deprecated method and its caller.