org.ogf.saga.error
Class SagaException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          org.ogf.saga.error.SagaException

All Implemented Interfaces:

Serializable, Comparable<SagaException>, Iterable<SagaException>

Direct Known Subclasses:

AlreadyExistsException, AuthenticationFailedException, AuthorizationFailedException, BadParameterException, DoesNotExistException, IncorrectStateException, IncorrectURLException, NoSuccessException, NotImplementedException, PermissionDeniedException, SagaIOException, TimeoutException

public abstract class SagaException
extends Exception
implements Comparable<SagaException>, Iterable<SagaException>

This is the base class for all exceptions in SAGA. It is a checked exception, so all exceptions in SAGA are checked exceptions. The Throwable.getMessage() method does not quite behave as specified in the SAGA specs, because Java already has toString() for exactly that behavior. So, Throwable.getMessage() does what it always does for Java throwables.

A simple mechanism exists for storing and examining exceptions that may be thrown by adaptors in adaptor-based Saga implementations. In such implementations, the top-level exception (the one highest up in the Saga exception hierarchy) is not always the most informative one, and the implementation is not always capable of selecting the most informative exception. In these cases, the implementation may opt to add the individual exceptions as nested exceptions to the exception thrown. The nested exceptions can be examined using the getAllExceptions() or getAllMessages() methods.

In addition to the getAllExceptions() and getAllMessages() mechanisms, this implementation also allows the user to iterate over the lower-level exception list.

See Also:

Serialized Form

Field Summary

protected static int	ALREADY_EXISTS
protected static int	AUTHENTICATION_FAILED
protected static int	AUTHORIZATION_FAILED
protected static int	BAD_PARAMETER
protected static int	DOES_NOT_EXIST
protected static int	INCORRECT_STATE
protected static int	INCORRECT_URL
protected static int	IO_EXCEPTION
protected static int	NO_SUCCESS
protected static int	NOT_IMPLEMENTED
protected static int	PERMISSION_DENIED
protected static int	TIMEOUT

Constructor Summary

protected	SagaException(int order) Constructs a new SAGA exception.
protected	SagaException(int order, String message) Constructs a new SAGA exception with the specified detail message.
protected	SagaException(int order, String message, SagaObject object) Constructs a new SAGA exception with the specified detail message and associated SAGA object.
protected	SagaException(int order, String message, Throwable cause) Constructs a new SAGA exception with the specified detail message and cause.
protected	SagaException(int order, String detail, Throwable cause, SagaObject object) Constructs a new SAGA exception with the specified detail message, specified cause and associated SAGA object.
protected	SagaException(int order, Throwable cause) Constructs a new SAGA exception with the specified cause.
protected	SagaException(int order, Throwable cause, SagaObject object) Constructs a new SAGA exception with the specified cause and associated SAGA object.

Method Summary

void	addNestedException(SagaException e) Adds an exception to the list of nested exceptions.
int	compareTo(SagaException o) Gives preference to the most specific exception.
List<SagaException>	getAllExceptions() Gets the list of lower-level exceptions.
List<String>	getAllMessages() Gets the list of lower-level exception messages.
SagaObject	getObject() Returns the SAGA object associated with this exception.
Iterator<SagaException>	iterator() Returns an iterator that iterates over the nested exceptions.
String	toString() Returns a short description of this SagaException.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Field Detail

INCORRECT_URL

protected static final int INCORRECT_URL

See Also:

Constant Field Values

BAD_PARAMETER

protected static final int BAD_PARAMETER

See Also:

Constant Field Values

ALREADY_EXISTS

protected static final int ALREADY_EXISTS

See Also:

Constant Field Values

DOES_NOT_EXIST

protected static final int DOES_NOT_EXIST

See Also:

Constant Field Values

INCORRECT_STATE

protected static final int INCORRECT_STATE

See Also:

Constant Field Values

PERMISSION_DENIED

protected static final int PERMISSION_DENIED

See Also:

Constant Field Values

AUTHORIZATION_FAILED

protected static final int AUTHORIZATION_FAILED

See Also:

Constant Field Values

AUTHENTICATION_FAILED

protected static final int AUTHENTICATION_FAILED

See Also:

Constant Field Values

IO_EXCEPTION

protected static final int IO_EXCEPTION

See Also:

Constant Field Values

TIMEOUT

protected static final int TIMEOUT

See Also:

Constant Field Values

NO_SUCCESS

protected static final int NO_SUCCESS

See Also:

Constant Field Values

NOT_IMPLEMENTED

protected static final int NOT_IMPLEMENTED

See Also:

Constant Field Values

Constructor Detail

SagaException

protected SagaException(int order)

Constructs a new SAGA exception.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

SagaException

protected SagaException(int order,
                        String message)

Constructs a new SAGA exception with the specified detail message.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

message - the detail message.

SagaException

protected SagaException(int order,
                        Throwable cause)

Constructs a new SAGA exception with the specified cause.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

cause - the cause.

SagaException

protected SagaException(int order,
                        String message,
                        Throwable cause)

Constructs a new SAGA exception with the specified detail message and cause.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

message - the detail message.

cause - the cause.

SagaException

protected SagaException(int order,
                        String message,
                        SagaObject object)

Constructs a new SAGA exception with the specified detail message and associated SAGA object.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

message - the detail message.

object - the SAGA object associated with the exception.

SagaException

protected SagaException(int order,
                        Throwable cause,
                        SagaObject object)

Constructs a new SAGA exception with the specified cause and associated SAGA object.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

cause - the cause.

object - the SAGA object associated with the exception.

SagaException

protected SagaException(int order,
                        String detail,
                        Throwable cause,
                        SagaObject object)

Constructs a new SAGA exception with the specified detail message, specified cause and associated SAGA object.

Parameters:

order - initializes the exceptionOrder field that determines which exception is more specific.

message - the detail message.

cause - the cause.

object - the SAGA object associated with the exception.

Method Detail

getObject

public SagaObject getObject()
                     throws DoesNotExistException,
                            NoSuccessException

Returns the SAGA object associated with this exception.

Returns:

the associated SAGA object.

Throws:

DoesNotExistException - is thrown when there is no object associated with this exception.

NoSuccessException - is thrown when the operation was not successfully performed, and none of the other exceptions apply.

compareTo

public int compareTo(SagaException o)

Gives preference to the most specific exception. This implements the ordering as in the SAGA specs. Returns < 0 if this exception is more specific than the specified exception, 0 if equal, and > 0 if less.

Specified by:

compareTo in interface Comparable<SagaException>

toString

public String toString()

Returns a short description of this SagaException. If this SagaException object was created with a non-null detail message string, then the result is the concatenation of three strings:

• The simple (unqualified) name of the actual class of this object
• ": " (a colon and a space)
• The result of the Throwable.getMessage() method for this object

If this SagaException object was created with a null detail message string, then only the simple (unqualified) name of the actual class of this object is returned.

Overrides:

toString in class Throwable

Returns:

a string representation of this SagaException.

addNestedException

public void addNestedException(SagaException e)

Adds an exception to the list of nested exceptions. This method should only be used by SAGA implementations.

Parameters:

e - the exception to be added to the list.

iterator

public Iterator<SagaException> iterator()

Returns an iterator that iterates over the nested exceptions.

Specified by:

iterator in interface Iterable<SagaException>

Returns:

the iterator.

getAllExceptions

public List<SagaException> getAllExceptions()

Gets the list of lower-level exceptions. The first exception in the list is the one on which this method is invoked, but without lower-level exceptions.

Returns:

the list of exceptions.

getAllMessages

public List<String> getAllMessages()

Gets the list of lower-level exception messages. The first message in the list is from the one on which this method is invoked.

Returns:

the list of exception messages.