Module org.klojang.util
Package org.klojang.util.exception

Class UncheckedException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.klojang.util.exception.UncheckedException
All Implemented Interfaces:
Serializable
public final class UncheckedException extends RuntimeException
A RuntimeException that behaves just like Exception it wraps. it overrides all methods from Exception by delegating to the same method on the wrapped exception. For example, getCause() does not return the wrapped exception but the cause of the wrapped exception. You can provide a custom message that pertains to UncheckedException itself, but it must be retrieved via getCustomMessage() as getMessage() would return the message of the wrapped exception.

This behaviour can be useful when wrapping checked exceptions that in practice cannot sensibly be dealt with. This is often the case with, for example, IOException, SQLException and other exceptions where the Javadocs state that they are thrown "when something goes wrong". These exceptions are runtime exceptions for all practical purposes.

By hiding completely behind the wrapped exception, an UncheckedException has a less cumbersome stack trace than a straight RuntimeException. Beware of surprises though, as the only way of knowing you are dealing with an UncheckedException is by calling getClass() on it.

An UncheckedException can be safely wrapped into an UncheckedException. The constructors "bore through" the causes until they find something that is not an UncheckedException and not a RootException.

See Also:

  • Constructor Details

    • UncheckedException

      public UncheckedException(Throwable cause)
      Creates an UncheckedException wrapping the provided Throwable.
      Parameters:
      cause - the exception to wrap and mask

    • UncheckedException

      public UncheckedException(String message, Throwable cause)
      Creates an UncheckedException with the provided custom message, wrapping the provided Throwable.
      Parameters:
      message - a custom message
      cause - the exception to wrap and mask

  • Method Details

    • unwrap

      public <E extends Throwable> E unwrap()
      Returns the exception wrapped by this UncheckedException. Note that getCause() does not return that exception. It returns the cause of the cause.
      Type Parameters:
      E - the type of the exception
      Returns:
      the exception directly wrapped by this UncheckedException

    • getCustomMessage

      public Optional<String> getCustomMessage()
      Returns an Optional containing the custom message passed in through the two-arg constructor, or an empty Optional if the single-arg constructor was used.
      Returns:
      an Optional containing the custom message passed in through the constructor

    • getMessage

      public String getMessage()
      Calls getMessage() on the wrapped exception
      Overrides:
      getMessage in class Throwable
      Returns:
      the result of calling getMessage() on the wrapped exception

    • getLocalizedMessage

      public String getLocalizedMessage()
      Calls getLocalizedMessage() on the wrapped exception
      Overrides:
      getLocalizedMessage in class Throwable
      Returns:
      the result of calling getLocalizedMessage() on the wrapped exception

    • getCause

      public Throwable getCause()
      Calls getCause() on the wrapped exception.
      Overrides:
      getCause in class Throwable
      Returns:
      the result of calling getCause() on the wrapped exception

    • printStackTrace

      public void printStackTrace()
      Calls printStackTrace() on the wrapped exception
      Overrides:
      printStackTrace in class Throwable

    • printStackTrace

      public void printStackTrace(PrintStream s)
      Calls printStackTrace() on the wrapped exception
      Overrides:
      printStackTrace in class Throwable

    • printStackTrace

      public void printStackTrace(PrintWriter s)
      Calls printStackTrace on the wrapped exception.
      Overrides:
      printStackTrace in class Throwable

    • getStackTrace

      public StackTraceElement[] getStackTrace()
      Calls getStackTrace() on the wrapped exception
      Overrides:
      getStackTrace in class Throwable
      Returns:
      the result of calling getStackTrace() on the wrapped exception

    • setStackTrace

      public void setStackTrace(StackTraceElement[] stackTrace)
      Throws an UnsupportedOperationException.
      Overrides:
      setStackTrace in class Throwable

    • toString

      public String toString()
      Calls toString() on the wrapped exception.
      Overrides:
      toString in class Throwable
      Returns:
      the result of calling toString() on the wrapped exception

    • initCause

      public Throwable initCause(Throwable cause)
      Throws an UnsupportedOperationException.
      Overrides:
      initCause in class Throwable