Class BackingStoreException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.apache.sis.util.collection.BackingStoreException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MetadataVisitorException

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.

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
Version:
1.1
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      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.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: 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.
    • copySuppressed

      private void copySuppressed(Throwable cause)
      Copies suppressed exceptions to the given target. This method is invoked before the cause is re-thrown. Current version does not verify that this copy operation does not create duplicated values. Most of the time, this exception has no suppressed exceptions and this method does nothing.

      This copy operation is useful if a BackingStoreException was thrown inside a try-with-resource block, especially when the AutoCloseable is a Stream.