Error codes and embedded service exceptions

When an exception is thrown from within the service of an application during its invocation, during the processing of common data when the invocation of OnSessionEnter causes the session to be aborted, or during the processing of common data update when the invocation of OnSessionUpdate causes the session to be aborted, that exception is propagated to the client.

The exception propagated to the client describes the error as it relates to the middleware. This error might or might not be immediately useful to the application because it presents itself in a format that is external to the application.

It is possible for an application to get more specific details about the error returned. The application must attach enough meaningful information to the exception before it is thrown within the service. In general, you can attach application-specific error information like a string description and/or an error code to an exception before throwing it in the service code. The error information is preserved and wrapped within a larger IBM® Spectrum Symphony exception, which is then propagated to the client.

This information can then be used to further qualify how the client responds to any failures it receives through an exception. For example, when a task fails, you might need to be able to determine whether an error pertains to the service or to the IBM Spectrum Symphony system itself.

Attach an error code to service exceptions

To associate an error code to service exceptions, when creating the error message as a FatalException or FailureException, add the error code and/or description to the exception when it is being constructed.

Retrieve embedded service exceptions

Service-specific exceptions thrown within the context of OnInvoke(), OnSessionEnter(), or OnSessionUpdate() are literally preserved and can be retrieved from the IBM Spectrum Symphony exception by the client. Note that stack trace preservation is not available. To retrieve the service-specific exception, use the SoamException::getEmbeddedException() method. Note that you must check for null before attempting to use the embedded exception. This embedded exception contains any specific information that was added in the service side of the application before the exception was thrown. If there is no exception embedded, then it is likely that the exception is being reported from the system, or the exception occurred as a result of an unexpected failure in the service code itself.

Example

The following pseudo-code illustrates how to retrieve embedded exceptions and associate error codes with exceptions. This example relates to a task failing and how it is handled:

If task was successful
{
Process task normally
}
else 
{
It must have failed so handle the failure case 
// get the exception associated with this task
SoamException ex = output.Exception;
Console.WriteLine(ex.ToString());
SoamException myEx = ex.EmbeddedException;
if (myEx != null) 
 {
  if (myEx.ErrorCode == myErrorCodes.error1)
    { 
   Handle specific application error 
   ...
   }
  else 
  if (myEx.ErrorCode == myErrorCodes.error2)
   {
   Handle specific error 
   ...
   }
 }
}