Package org.apache.sis.util

# Class Exceptions

Object
Static
Exceptions

public final class Exceptions extends Static
Static methods working with `Exception` instances.

Since:
  0.3

Defined in the `sis-utility` module

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `formatChainedMessages(Locale locale, String header, Throwable cause)`
  Returns a string which contain the given message on the first line, followed by the localized message of the given exception on the next line.
  `static String`
  `getLocalizedMessage(Throwable exception, Locale locale)`
  Returns the message of the given exception, localized in the given locale if possible.
  `static boolean`
  `messageEquals(Throwable first, Throwable second)`
  Returns `true` if the given exceptions are of the same class and contains the same message.
  `static <T extends Throwable>
  T`
  `setMessage(T exception, String message, boolean append)`
  Returns an exception of the same kind and with the same stack trace than the given exception, but with a different message.
  `static Exception`
  `unwrap(Exception exception)`
  If the given exception is a wrapper for another exception, returns the unwrapped exception.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### getLocalizedMessage

    public static String getLocalizedMessage(Throwable exception, Locale locale)
    Returns the message of the given exception, localized in the given locale if possible. Some exceptions created by SIS can format a message in different locales. This method returns such localized message if possible, or fallback on the standard JDK methods otherwise. More specifically:
    - If the given `exception` is null, then this method returns `null`.
    - Otherwise if the given `locale` is null, then this method returns `Throwable​.getMessage()`. This is consistent with the `Localized` policy saying that null locale stands for "unlocalized" message (usually in English) or message in the JVM default locale.
    - Otherwise if the given `exception` is an instance of `LocalizedException` providing a non-null international message, then this method returns the result of `InternationalString​.toString(Locale)`.
    - Otherwise this method returns `Throwable​.getLocalizedMessage()`.
    Parameters:
      `exception` - the exception from which to get the localize message, or `null`.
      `locale` - the preferred locale for the message, or `null` for the JVM default locale. This locale is honored on a best-effort basis only.
    Returns:
      the message in the given locale if possible, or `null` if the `exception` argument was `null` or if the exception does not contain a message.
    See Also:
      - `LocalizedException​.getLocalizedMessage()`

  - ### setMessage

    public static <T extends Throwable> T setMessage(T exception, String message, boolean append)
    Returns an exception of the same kind and with the same stack trace than the given exception, but with a different message. This method simulates the functionality that we would have if `Throwable` defined a `setMessage(String)` method. We use this method when an external library throws an exception of the right type, but with too few details.

    This method tries to create a new exception using reflection. The exception class needs to provide a public constructor expecting a single `String` argument. If the exception class does not provide such constructor, then the given exception is returned unchanged.

    Type Parameters:
      `T` - the type of the exception.
    Parameters:
      `exception` - the exception to copy with a different message.
      `message` - the message to set in the exception to be returned.
      `append` - if `true`, the existing message in the original exception (if any) will be happened after the provided message.
    Returns:
      a new exception with the given message, or the given exception if the exception class does not provide public `Exception(String)` constructor.

  - ### messageEquals

    public static boolean messageEquals(Throwable first, Throwable second)
    Returns `true` if the given exceptions are of the same class and contains the same message. This method does not compare the stack trace, cause or suppressed exceptions.
    Parameters:
      `first` - the first exception, or `null`.
      `second` - the second exception, or `null`.
    Returns:
      `true` if both exceptions are `null`, or both exceptions are non-null, of the same class and with the same message.
    Since:
      1.0

  - ### formatChainedMessages

    public static String formatChainedMessages(Locale locale, String header, Throwable cause)
    Returns a string which contain the given message on the first line, followed by the localized message of the given exception on the next line. If the exception has a causes, then the class name and the localized message of the cause are formatted on the next line and the process is repeated for the whole cause chain, omitting duplicated messages.

    `SQLException` is handled especially in order to process the next exception instead of the cause.

    This method does not format the stack trace.

    Parameters:
      `locale` - the preferred locale for the exception message, or `null`.
      `header` - the message to insert on the first line, or `null` if none.
      `cause` - the exception, or `null` if none.
    Returns:
      the formatted message, or `null` if both the header was `null` and no exception provide a message.

  - ### unwrap

    public static Exception unwrap(Exception exception)
    If the given exception is a wrapper for another exception, returns the unwrapped exception. Otherwise returns the given argument unchanged. An exception is considered a wrapper if:
    - It is an instance of `InvocationTargetException` (could be wrapping anything).
    - It is an instance of `ExecutionException` (could be wrapping anything).
    - It is an instance of `BackingStoreException` (typically wrapping a checked exception).
    - It is an instance of `UncheckedIOException` (wrapping a `IOException`).
    - It is an instance of `DirectoryIteratorException` (wrapping a `IOException`).
    - It is a parent type of the cause. For example some JDBC drivers wrap `SQLException` in other `SQLException` without additional information.
    Note: `PrivilegedActionException` is also a wrapper exception, but is not included in above list because it is used in very specific contexts.
    This method uses only the exception class and the absence of suppressed exceptions as criterion; it does not verify if the exception messages are the same.
    Parameters:
      `exception` - the exception to unwrap (may be `null`.
    Returns:
      the unwrapped exception (may be the given argument itself).
    Since:
      0.8