<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--
  ~  Licensed to the Apache Software Foundation (ASF) under one
  ~  or more contributor license agreements.  See the NOTICE file
  ~  distributed with this work for additional information
  ~  regarding copyright ownership.  The ASF licenses this file
  ~  to you under the Apache License, Version 2.0 (the
  ~  "License"); you may not use this file except in compliance
  ~  with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<document>
    <properties>
        <title>Apache Synapse - Sample 4</title>
    </properties>
    <body>
        <section name="Sample 4: Introduction to Error Handling">
            <div class="xmlConf">&lt;definitions xmlns="http://ws.apache.org/ns/synapse"&gt;

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

    &lt;sequence name="sunErrorHandler"&gt;
        &lt;log level="custom"&gt;
            &lt;property name="text" value="An unexpected error occured for stock SUN"/&gt;
            &lt;property name="message" expression="get-property('ERROR_MESSAGE')"/&gt;
            &lt;!--&lt;property name="detail" expression="get-property('ERROR_DETAIL')"/&gt;--&gt;
        &lt;/log&gt;
        &lt;drop/&gt;
    &lt;/sequence&gt;

    &lt;sequence name="main"&gt;
        &lt;in&gt;
            &lt;switch xmlns:m0="http://services.samples" source="//m0:getQuote/m0:request/m0:symbol"&gt;
                &lt;case regex="IBM"&gt;
                    &lt;send&gt;
                        &lt;endpoint&gt;
                            &lt;address uri="http://localhost:9000/services/SimpleStockQuoteService"/&gt;
                        &lt;/endpoint&gt;
                    &lt;/send&gt;
                &lt;/case&gt;
                &lt;case regex="MSFT"&gt;
                    &lt;send&gt;
                        &lt;endpoint key="bogus"/&gt;
                    &lt;/send&gt;
                &lt;/case&gt;
                &lt;case regex="SUN"&gt;
                    &lt;sequence key="sunSequence"/&gt;
                &lt;/case&gt;
            &lt;/switch&gt;
            &lt;drop/&gt;
        &lt;/in&gt;

        &lt;out&gt;
            &lt;send/&gt;
        &lt;/out&gt;
    &lt;/sequence&gt;

    &lt;sequence name="sunSequence" onError="sunErrorHandler"&gt;
        &lt;send&gt;
            &lt;endpoint key="sunPort"/&gt;
        &lt;/send&gt;
    &lt;/sequence&gt;

&lt;/definitions&gt;</div>
            <subsection name="Objective">
                <p>
                    Introduction to error handling with the 'fault' sequence
                </p>
            </subsection>
            <subsection name="Pre-requisites">
                <p>
                    <ul>
                        <li>
                            Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
                        </li>
                        <li>
                            Start Synapse using the configuration numbered 4 (repository/conf/sample/synapse_sample_4.xml)
                            <div class="command">
                                Unix/Linux: sh synapse.sh -sample 4<br/>
                                Windows: synapse.bat -sample 4
                            </div>
                        </li>
                    </ul>
                </p>
            </subsection>
            <subsection name="Executing the Client">
                <p>
                    First send a stock quote request from the sample client for the symbol 'IBM' as
                    follows.
                </p>
                <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM</div>
                <p>
                    The request will be routed to the Axis2 server and client will receive a response
                    as expected.
                </p>
                <div class="consoleOutput">Standard :: Stock price = $95.26454380258552</div>
                <p>
                    Now send another stock quote request for the symbol 'MSFT' as follows.
                </p>
                <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT</div>
                <p>
                    For MSFT requests Synapse is instructed to route the messages to an endpoint named
                    'bogus', which does not exist. Synapse 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 Synapse 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.
                </p>
                <div class="consoleOutput">[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 &lt;fault&gt; :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO LogMediator text = An unexpected error occured, message = Couldn't find the endpoint with the key : bogus</div>
                <p>
                    Now send another stock quote request for the symbol 'SUN'.
                </p>
                <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN</div>
                <p>
                    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.
                </p>
                <div class="consoleOutput">[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator &lt;sunSequence&gt; :: mediate()
[HttpServerWorker-1] DEBUG SequenceMediator - Setting the onError handler for the sequence
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence &lt;SequenceMediator&gt; :: 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 &lt;sunErrorHandler&gt; :: mediate()
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence &lt;SequenceMediator&gt; :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO LogMediator text = An unexpected error occured for stock SUN, message = Couldn't find the endpoint with the key : sunPort</div>
            </subsection>
        </section>
        <p><a href="../samples.html">Back to Catalog</a></p>        
    </body>
</document>