Sample 4: Introduction to Error Handling

Objective: Introduction to error handling with the "fault" sequence.

<definitions xmlns="http://ws.apache.org/ns/synapse">

    <!-- the default fault handling sequence used by Synapse - named 'fault' -->
    <sequence name="fault">
        <log level="custom">
            <property name="text" value="An unexpected error occured"/>
            <property name="message" expression="get-property('ERROR_MESSAGE')"/>
        </log>
        <drop/>
    </sequence>

    <sequence name="sunErrorHandler">
        <log level="custom">
            <property name="text" value="An unexpected error occured for stock SUN"/>
            <property name="message" expression="get-property('ERROR_MESSAGE')"/>
        </log>
        <drop/>
    </sequence>

    <!-- default message handling sequence used by Synapse - named 'main' -->
    <sequence name="main">
        <in>
            <switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples">
                <case regex="IBM">
                    <send>
                        <endpoint><address uri="http://localhost:9000/services/SimpleStockQuoteService"/></endpoint>
                    </send>
                </case>
                <case regex="MSFT">
                    <send>
                        <endpoint key="bogus"/>
                    </send>
                </case>
                <case regex="SUN">
                    <sequence key="sunSequence"/>
                </case>
            </switch>
            <drop/>
        </in>

        <out>
            <send/>
        </out>
    </sequence>

    <sequence name="sunSequence" onError="sunErrorHandler">
        <send>
            <endpoint key="sunPort"/>
        </send>
    </sequence>

</definitions>

Prerequisites

Start the Synapse configuration numbered 4: wso2esb-samples.sh -sn 4
Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

When the IBM stock quote is requested, the configuration routes it to the defined inline endpoint, which routes the message to the SimpleStockQuoteService on the local Axis2 instance. Hence a valid response message is shown at the client.

If you lookup a stock quote for "MSFT," ESB is instructed to route the message to the endpoint defined as the "bogus" endpoint, which does not exist. ESB executes the specified error handler sequence closest to the point where the error was encountered. In this case the currently executing sequence is "main" and it does not specify an "onError" attribute. Whenever ESB cannot find an error handler, it looks for a sequence named "fault." Thus, the "fault" sequence can be seen executing and writing the generic error message to the logs.

ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT

[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : bogus
[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <fault> :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO  LogMediator - text = An unexpected error occured, message = Reference to non-existent endpoint for key : bogus

When the "SUN" quote is requested, a custom sequence "sunSequence" is invoked, and it specifies sunErrorHandler as its error handler. Hence, when the send fails, you could see the proper error handler invocation and the custom error message printed as follows.

ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN

[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunSequence> :: mediate()
[HttpServerWorker-1] DEBUG SequenceMediator - Setting the onError handler for the sequence
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : sunPort
[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunErrorHandler> :: mediate()
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO  LogMediator - text = An unexpected error occured for stock SUN, message = Reference to non-existent endpoint for key : sunPort

For information on best practices for handling errors in WSO2 ESB, see WSO2 ESB by Example - Best practices for error handling on the WSO2 ESB.