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

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

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

add­Suppressed, fill­In­Stack­Trace, get­Cause, get­Localized­Message, get­Message, get­Stack­Trace, get­Suppressed, init­Cause, print­Stack­Trace, print­Stack­Trace, print­Stack­Trace, set­Stack­Trace, to­String

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, 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.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 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 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);
    }
}

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.