Exception and Error Handling - optimaize/anythingworks GitHub Wiki

Exceptional cases are thrown on the server as Java Exceptions, and are converted by the system to Faults and transmitted as such to the client. The client library then translates them back to Exceptions containing the additional FaultInfo data.

It's easy for the web service server method: Just throw a certain kind of Exception. It's easy for the web service client: catch the kinds of Exceptions you want to catch, and have all the detail info at hands.

For REST there is the RestFaultInfo subclass that additionally contains the http status code information.

FaultInfo

This object contains all the detail about what happened. We believe that the few codes available in the HTTP protocol (for REST) are rarely enough for non-trivial applications. It's thinkable to extend the class and use a custom subclass with additional fields. In that case a few places in the system may need refactoring.

Marshalling in REST

This happens in the FaultInfoRestExceptionMapper which is registered in the system.

Marshalling in SOAP

Because of the automatic marshalling, the ServiceException types are converted into a SoapWebServiceException before leaving the web service method.

Web Service Methods

To throw an exception, do something like this:

throw InternalServerErrorServiceExceptions.internalServerError("No one knows what happened.");

HTTP Status Codes

SOAP uses 400/500 (only 500 in SOAP 1.1), and REST can use all codes.

Exception Names

Exceptions are named by who's to blame, not who threw the exception. A server can throw a ClientException just like in HTTP a server can return a code 400 (client error).

Exception Translation for SOAP

On the client there are the DefaultClientExceptionTranslator and SoapFaultExceptionTranslator classes. They take what's coming from the server and put it back into a nice Exception object.

On the server there's the SoapWebServiceExceptionTranslator class. Any exception that already is a ServiceException goes through untouched. It was carefully selected as exception type by the user's server application code. Other "basic" Java exception types including IllegalArgumentException, UnsupportedOperationException, NullPointerException etc are converted to a matching InternalServerErrorServiceException.