com.amazon.carbonado
Class RepositoryException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.amazon.carbonado.RepositoryException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

FetchException, PersistException, SupportException

public class RepositoryException
extends Exception

General checked exception thrown when accessing a Repository.

Some repository exceptions are the result of an optimistic lock failure or deadlock. One resolution strategy is to exit all transactions and try the operation again, after waiting some bounded random amount of time. As a convenience, this class provides a mechanism to support such a backoff strategy. For example:

 // Retry at most three more times
 for (int retryCount = 3;;) {
     try {
         ...
         myObject.load();
         ...
         myObject.update();
         break;
     } catch (OptimisticLockException e) {
         // Wait up to one second before retrying
         retryCount = e.backoff(e, retryCount, 1000);
     }
 }
 

If the retry count is zero (or less) when backoff is called, then the original exception is rethrown, indicating retry failure.

Author:

Brian S O'Neill

See Also:

Serialized Form

Constructor Summary

RepositoryException()

RepositoryException(String message)

RepositoryException(String message, Throwable cause)

RepositoryException(Throwable cause)

Method Summary

static <E extends Throwable> int	backoff(E e, int retryCount, int milliseconds) One strategy for resolving an optimistic lock failure is to try the operation again, after waiting some bounded random amount of time.
Throwable	getRootCause() Recursively calls getCause, until the root cause is found.
protected FetchException	makeFetchException(String message, Throwable cause) Subclasses can override this to provide a more specialized exception.
protected PersistException	makePersistException(String message, Throwable cause) Subclasses can override this to provide a more specialized exception.
FetchException	toFetchException() Converts RepositoryException into an appropriate FetchException.
FetchException	toFetchException(String message) Converts RepositoryException into an appropriate FetchException, prepending the specified message.
PersistException	toPersistException() Converts RepositoryException into an appropriate PersistException.
PersistException	toPersistException(String message) Converts RepositoryException into an appropriate PersistException, prepending the specified message.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RepositoryException

public RepositoryException()

RepositoryException

public RepositoryException(String message)

RepositoryException

public RepositoryException(String message,
                           Throwable cause)

RepositoryException

public RepositoryException(Throwable cause)

Method Detail

backoff

public static <E extends Throwable> int backoff(E e,
                                                int retryCount,
                                                int milliseconds)
                   throws E extends Throwable

One strategy for resolving an optimistic lock failure is to try the operation again, after waiting some bounded random amount of time. This method is provided as a convenience, to support such a random wait.

A retry count is required as well, which is decremented and returned by this method. If the retry count is zero (or less) when this method is called, then this exception is thrown again, indicating retry failure.

Parameters:

retryCount - current retry count, if zero, throw this exception again

milliseconds - upper bound on the random amount of time to wait

Returns:

retryCount minus one

Throws:

E - if retry count is zero

E extends Throwable

getRootCause

public Throwable getRootCause()

Recursively calls getCause, until the root cause is found. Returns this if no root cause.

toPersistException

public final PersistException toPersistException()

Converts RepositoryException into an appropriate PersistException.

toPersistException

public final PersistException toPersistException(String message)

Converts RepositoryException into an appropriate PersistException, prepending the specified message. If message is null, original exception message is preserved.

Parameters:

message - message to prepend, which may be null

toFetchException

public final FetchException toFetchException()

Converts RepositoryException into an appropriate FetchException.

toFetchException

public final FetchException toFetchException(String message)

Converts RepositoryException into an appropriate FetchException, prepending the specified message. If message is null, original exception message is preserved.

Parameters:

message - message to prepend, which may be null

makePersistException

protected PersistException makePersistException(String message,
                                                Throwable cause)

Subclasses can override this to provide a more specialized exception.

Parameters:

message - exception message, which may be null

cause - non-null cause

makeFetchException

protected FetchException makeFetchException(String message,
                                            Throwable cause)

Subclasses can override this to provide a more specialized exception.

Parameters:

message - exception message, which may be null

cause - non-null cause