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

Java 8 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

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

  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 Details

  - ### 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 Details

  - ### 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);
                }
            }

    If this exception has suppressed exceptions and this method decided that this exception should be discarded in favor of `<E>` or `RuntimeException` cause, then this method copies the suppressed exceptions into the cause before to throw the cause.
    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.