Sample 4: Introduction to Error Handling

Introduction

This sample demonstrates an introduction to error handling with the "fault" sequence. It sends a message from a sample client to a back-end service through the ESB through 3 mediation options as: success scenario, a failure scenario without error handling and a failure scenario with proper error handling.

Prerequisites

Refer to Prerequisites section in ESB Samples Setup page.

Building the Sample

1. Start the ESB with sample 4 configuration using the instructions given in Starting Sample ESB Configurations.

2. A message should appear in the command or text Linux console stating the server started successfully.

3. The synapse configuration in the ESB used for message mediation in this sample is provided in <ESB_HOME>/repository/samples/synapse_sample_4.xml as shown below:

<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>

4. Deploy the back-end service 'SimpleStockQuoteService' and start the Axis2 server using the instructions given in section Starting Sample Back-End Services.

5. Now you have a running ESB instance and a back-end service deployed. In the next section, we will send a message to the back-end service through the ESB using a sample client.

Executing the Sample

The sample client used here is 'Stock Quote Client' which can operate in several modes. For instructions on this sample client and its operation modes, refer to Stock Quote Client.

1. Run the following ant command from <ESB_HOME>/samples/axis2Client directory to trigger a sample message to the back-end service.

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

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. Therefore, a valid response message is shown at the client.

2. Next, execute the "MSFT" option in synapse_sample_4.xml file above where the ESB is instructed to route the message to the endpoint defined as the "bogus" endpoint, which does not exist.

synapse_sample_4.xml - MSFT Quote

<case regex="MSFT"> 
   <send> 
      <endpoint key="bogus"/> 
   </send> 
</case>

3. To trigger this fault scenario, execute the following ant command:

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

4. 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." As a result, the "fault" sequence starts executing and it writes generic error message to the logs.

[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

5. Next, execute the "SUN" option as follows.

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

6. It invokes a custom sequence by the name "sunSequence" which specifies sunErrorHandler as its error handler as specified in synapse_sample_4.xml file specified above.

<case regex="SUN">
 <sequence key="sunSequence"/>
</case>

7. When the send fails, you see proper error handler invocation and the custom error message printed as follows.

[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