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

  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.