Package org.ogf.saga.error

Each SAGA API call has an associated list of exceptions it may throw, which are described in this package.

See: Description

Exception Summary

Exception	Description
AlreadyExistsException	This exception indicate that an operation cannot succeed because the entity to be created or registered already exists or is already registered.
AuthenticationFailedException	This exception indicates that a method fails because none of the available session contexts could succesfully be used for authentication.
AuthorizationFailedException	This exception indicates that a method fails because none of the available session contexts could succesfully be used for authorization.
BadParameterException	This exception indicates that one or more of the parameters of an operation are ill-formed, invalid, out of bound, or otherwise not usable.
DoesNotExistException	This exception indicates that an operation cannot succeed because a required entity is missing.
IncorrectStateException	This exception indicates that the object on which a method is called is in a state where that method cannot succeed.
IncorrectURLException	This exception indicates that a method is given an URL argument that could not be handled.
NoSuccessException	This exception indicates that an operation failed semantically.
NotImplementedException	This exception indicates that a SAGA method is not implemented.
PermissionDeniedException	This exception indicates that the identity used for the operation did not have sufficient permissions to perform the operation successfully.
SagaException	This is the base class for all exceptions in SAGA.
SagaIOException	This exception is specific to the Java Language Bindings for SAGA, which uses this exception for some methods, instead of returning POSIX error code.
TimeoutException	This exception indicates that a remote operation did not complete successfully because the network communication or the remote service timed out.

Package org.ogf.saga.error Description

Each SAGA API call has an associated list of exceptions it may throw, which are described in this package. These exceptions all extend the SagaException class.

Since Java has excellent exception handling support, the Java language bindings use the Java mechanism instead of the error_handler interface as described in the language-independent SAGA specification. The language-independent SAGA specification specifies that in languages with exception-handling mechanisms, such as Java, C++ and Perl, the language binding may allow exceptions to be thrown. If an exception handling mechanism is included in a language binding, the error_handler must not be included in the same binding.

The SAGA specifications say that in languages bindings where this is appropriate, some API methods return POSIX errno codes for errors. For Java, this is not appropriate. The "usual" Java read and write methods throw an exception when an error occurs. The Java language binding versions of these SAGA API methods throw an SagaIOException when an error occurs. If a specific error code is available, it can be examined through the getPosixErrorCode() method.

The SagaIOException is specific for the Java Language Bindings for SAGA. In the ordering of SAGA exceptions, as discussed in the language-independent SAGA specification, the SagaIOException is considered almost the most specific, inbetween NotImplementedException and IncorrectURLException.

The layout of the result of getMessage() deviates from that as specified in the language-independent SAGA specification. The usual Java convention is followed instead. To obtain a result as required by the language-independent SAGA specification, toString() can be used, again as usual in Java.

The IncorrectType exception as described in the language-independent SAGA specification does not exist in the Java Language Bindings for SAGA, as Java has a ClassCastException for that purpose.

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.