Local and Dispatch Exceptions

Local Exceptions

The Ice runtime reports errors to the application by throwing exceptions. Ice occasionally throws standard exceptions such as std::invalid_argument(C++) or IllegalArgumentException(Java), but generally it throws exceptions derived from LocalExceptionLocalExceptionLocalExceptionLocalExceptionLocalExceptionLocalExceptionLocalExceptionLocalExceptionLocalException. These exceptions are known as local exceptions.

As far as Ice is concerned, the opposite of a local exception is a user exception. User exceptions are defined in Slice and derive from UserExceptionUserExceptionUserExceptionUserExceptionUserExceptionUserExceptionUserExceptionUserExceptionUserException; local exceptions are not defined in Slice and derive from LocalException.

Dispatch Exceptions

When an API call throws an exception, this exception is necessarily thrown in the caller's process. This exception can represent an error that was detected locally by the Ice runtime (for example, failed to establish a connection), or it can represent an error that was reported “over the wire” by a remote Ice server (for example, could not find a servant to dispatch this request to).

In the Ice exception type system, all these exceptions are local exceptions, derived from LocalException. The exceptions that represent errors reported “over the wire” are a special kind of local exceptions, called dispatch exceptions.

A dispatch exception represents a failure that occurred in the server while dispatching an incoming request. If you get a dispatch exception, it means Ice was able to communicate with the server - and got a failure-response from the server.

A dispatch exception carries information transmitted in a Reply message, namely:

• a ReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatus enumerator
• one or more fields that depend on the ReplyStatus enumerator

A dispatch exception without an associated exception class is an instance of DispatchExceptionDispatchExceptionDispatchExceptionDispatchExceptionDispatchExceptionDispatchExceptionDispatchExceptionDispatchExceptionDispatchException. The three NotExist exceptions derive from RequestFailedException, and UnknownLocalException and UnknownUserException derive from UnknownException. RequestFailedException and UnknownException derive from DispatchException. The replyStatus member of a dispatch exception holds its reply status.