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 targeting JDK8 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 and 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 and 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.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.