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

    All Methods Static Methods Concrete Methods
    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 Detail

    - #### 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 than 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 `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 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