Module org.apache.sis.util
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 unwrap­Or­Rethrow(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​.Unchecked­IOException

Java 8 provides a Unchecked­IOException which partially overlaps the purpose of this Backing­Store­Exception. While Apache SIS still uses Backing­Store­Exception 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:

  • 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​.get­Message() 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​.get­Cause() 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​.get­Message() method.
      cause - the cause, saved for later retrieval by the Throwable​.get­Cause() 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 Runtime­Exception, 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 Runtime­Exception 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:
      Runtime­Exception - if the cause is an instance of Runtime­Exception, in which case that instance is re-thrown.
      Backing­Store­Exception - if the cause is neither the given type or an instance of Runtime­Exception, in which case this exception is re-thrown.