Exception Reporting

Preliminaries

Based on the INB1 proposal (RFC #1863) for exception reporting in bioMoby, this document is now the definitive specification of the exception-reporting mechanism for BioMOBY. The proposal was discussed at the INB Meeting in Málaga (July, 2005) with the participation of Martin Senger and Edward Kawas, and in the BioMOBY mailing lists during summer 2005, and has been accepted by the BioMOBY developers as part of the specification.

This specification standardises exception reporting in bioMOBY by supplying a more detailed description of common errors and a way to enable uniform notification. Additional information on exceptions is now available, thus allowing the BioMOBY clients to better inform their users about what is going on. Additionally, exceptions related to asynchronous communication can be specified using this proposal. This document focuses on BioMOBY only (i.e., exceptions rose during service execution that can be reported to the client using a BioMOBY XML payload). In some cases, an exception can be considered critical and the service not able to transmit a bioMOBY XML to the requesting client, but the underlying protocols still able to raise an exception and inform the client. It's been proposed to handle the exceptions at this transport level using SOAP Fault mechanism, but the details of such mechanism (faultCode, faultStrings, etc) are not covered in this document.

A description of the old (pre v0.86) specification can be found here.

New Specification

Extending the structure of the serviceNotes tag

BioMOBY has to consider reporting exceptions for every layer of information the service request can contain: whole invocation (mobyContent), individual queries (mobyData), and single objects provided as input to the service (Simples, Collections, or even Simples inside a Collection).

A structured mobyException child element under serviceNotes is the placeholder for exception reporting information. (The downside is that the definition of serviceNotes has to be changed slightly. This should not be a problem but the corresponding documentation should be updated to inform developers.). It is worth noting that other additional children elements can be incorporated in future under the serviceNotes tag (to fully enrich the response message with whatever metadata the service would want to communicate to the client).

The mobyException tag is used to report exception conditions. Using the mandatory attribute severity, different types of exceptions can be described:

  • error: Corresponds to fatal errors in a service, which causes running of the program to be terminated. Fatal errors are characterised by containing empty objects.
  • warning: Corresponds to an informative diagnostic message that is issued when a service detects an error or potential problem but continues processing and results are provided.
  • information: Corresponds to a free text message not related with any error, containing information that the service wishes to communicate to the user, i.e., non erroneous informative service messages.
One mobyException tag is associated to each input tag that needs to raise an exception. The link between the erroneous tag and the exception message is made by referring to the queryID and articleName of the offending input article. Two optional referrer attributes of the mobyException tag fulfil this linkage function:
  • refQueryID - refers to the queryID of the offending input mobyData
  • refElement - refers to the articleName of the offending input Simple or Collection
Referrer attributes in mobyException are optional. An exception can refer to the whole mobyContent input if no referrer attributes are present, to a whole query if only refQueryID is present, or to a single Simple or Collection input if also its refElement is present. This way it is possible to report exceptions for every input or combination of inputs to the service.

The mobyException tag contains two elements to describe the error:
  • exceptionCode - exception value (error code)
  • exceptionMessage - human readable description. The message gives more detailed information, complementing the information given by the exception code.
The set of error codes is based on the recommended exception codes system specified in OMG's Life Sciences Analysis Engine (LSAE standard)

Examples

  1. Example of using the mobyException tag to report error for Simple inputs

    Request service XML package (unchanged): 

    <?xml version="1.0" encoding="UTF-8"?>
<MOBY xmlns="http://www.biomoby.org/moby">
<mobyContent>
<mobyData queryID='1'>
<Simple articleName = "input1">
<!-- BioMOBY Object -->
</Simple>
</mobyData>
<mobyData queryID="2">
<Simple articleName = "input2">
<!-- BioMOBY Object -->
</Simple>
</mobyData>
<mobyData queryID="3">
<Simple articleName = "input3">
<!-- BioMOBY Object -->
</Simple>
</mobyData>
</mobyContent>
</MOBY>
    Response service XML package: 
    <?xml version="1.0" encoding="UTF-8"?>
<MOBY xmlns="http://www.biomoby.org/moby">
<mobyContent>
<serviceNotes>
<mobyException refElement="input1"
refQueryID="1"
severity ="error">
<exceptionCode>600</exceptionCode>
<exceptionMessage>Unable to execute the service</exceptionMessage>
</mobyException>
<mobyException refElement="input2"
refQueryID="2"
severity ="warning">
<exceptionCode>600</exceptionCode>
<exceptionMessage>Service execution had non critical problems</exceptionMessage>
</mobyException>
<mobyException refElement="input3"
refQueryID="3"
severity ="information">
<exceptionCode>600</exceptionCode>
<exceptionMessage>No problems in service execution</exceptionMessage>
</mobyException>
<Notes>Free text Service Notes</Notes>
</serviceNotes>
<mobyData queryID="1">
<!-- Error: Empty response -->
<Simple articleName="output1"/>
</mobyData>
<mobyData queryID="2">
<!-- Warning: Normal response -->
<Simple articleName="output2">
<!-- BioMOBY Object -->
</Simple>
</mobyData>
<mobyData queryID="3">
<!-- Information: Normal response -->
<Simple articleName="output3">
<!-- BioMOBY Object -->
</Simple>
</mobyData>
</mobyContent>
</MOBY>
The obsolete exception-handling mechanism is described here