Package org.apache.sis.util.collection

## Class BackingStoreException

- Object
- - Throwable
  - - Exception
    - - RuntimeException
      - - BackingStoreException

- All Implemented Interfaces:
    `Serializable`

      public class BackingStoreException
      extends RuntimeException

  Thrown to indicate that an operation could not complete because of a failure in the backing store (a file or a database). This exception is thrown by implementations of API (collection, streams, etc. that are not allowed to throw checked exceptions. This exception usually has an `IOException` or a `SQLException` as its cause.

  This method provides a `unwrapOrRethrow(Class)` convenience method which can be used for re-throwing the cause as in the example below. This allows client code to behave as if a `Collection` interface was allowed to declare checked exceptions.

  >     void myMethod() throws IOException {
  >         Collection c = ...;
  >         try {
  >             c.doSomeStuff();
  >         } catch (BackingStoreException e) {
  >             throw e.unwrapOrRethrow(IOException.class);
  >         }
  >     }

  Relationship with `java​.io​.UncheckedIOException`
  JDK8 provides a `UncheckedIOException` which partially overlaps the purpose of this `BackingStoreException`. While Apache SIS still uses `BackingStoreException` as a general mechanism for any kind of checked exceptions, client code would be well advised to catch both kind of exceptions for robustness.
  Since:
    0.3
  See Also:
    Serialized Form

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BackingStoreException()` | Constructs a new exception with no detail message.
    `BackingStoreException​(String message)` | Constructs a new exception with the specified detail message.
    `BackingStoreException​(String message, Throwable cause)` | Constructs a new exception with the specified detail message and cause.
    `BackingStoreException​(Throwable cause)` | Constructs a new exception with the specified cause.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<E extends Exception> E` | `unwrapOrRethrow​(Class<E> type)` | Returns the underlying cause as an exception of the given type, or re-throw the exception.

    - ### Methods inherited from class Throwable

      `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### BackingStoreException

          public BackingStoreException()

      Constructs a new exception with no detail message.

    - #### BackingStoreException

          public BackingStoreException​(String message)

      Constructs a new exception with the specified detail message.
      Parameters:
        `message` - the detail message, saved for later retrieval by the `Throwable​.getMessage()` method.

    - #### BackingStoreException

          public BackingStoreException​(Throwable cause)

      Constructs a new exception with the specified cause.
      Parameters:
        `cause` - the cause, saved for later retrieval by the `Throwable​.getCause()` method.

    - #### BackingStoreException

          public BackingStoreException​(String message,
                                       Throwable cause)

      Constructs a new exception with the specified detail message and cause.
      Parameters:
        `message` - the detail message, saved for later retrieval by the `Throwable​.getMessage()` method.
        `cause` - the cause, saved for later retrieval by the `Throwable​.getCause()` method.

  - ### Method Detail

    - #### unwrapOrRethrow

          public <E extends Exception> E unwrapOrRethrow​(Class<E> type)
                                                  throws RuntimeException,
                                                         BackingStoreException

      Returns the underlying cause as an exception of the given type, or re-throw the exception. More specifically, this method makes the following choices:
      - If the cause is an instance of the given type, returns the cause.
      - Otherwise if the cause is an instance of `RuntimeException`, throws that exception.
      - Otherwise re-throws `this`.
      This method should be used as in the example below:

      >     void myMethod() throws IOException {
      >         Collection c = ...;
      >         try {
      >             c.doSomeStuff();
      >         } catch (BackingStoreException e) {
      >             throw e.unwrapOrRethrow(IOException.class);
      >         }
      >     }

      Type Parameters:
        `E` - the type of the exception to unwrap.
      Parameters:
        `type` - the type of the exception to unwrap.
      Returns:
        the cause as an exception of the given type (never `null`).
      Throws:
        `RuntimeException` - if the cause is an instance of `RuntimeException`, in which case that instance is re-thrown.
        `BackingStoreException` - if the cause is neither the given type or an instance of `RuntimeException`, in which case `this` exception is re-thrown.