<?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 - Samples Setup Guide</title>
    </properties>
    <body>
        <section name="Introduction">
            <p>
                Apache Synapse comes with a collection of working examples that demonstrates the
                basic features of the Synapse ESB. In addition to the sample configurations, a set
                of sample client applications and services are provided which can be used to try out
                each of the examples. Most examples are self contained and can be run without any third
                party applications or libraries. A set of Ant build files and scripts are provided
                to make setting up the examples easier. A few examples however require deploying
                certain external libraries and using third party client applications.
            </p>
            <p>
                The main objectives of this article are:
                <ul>
                    <li>Introduce the concept of Synapse samples</li>
                    <li>Describe how to setup the environment for running samples</li>
                    <li>Describe how to run the sample client applications and services</li>
                    <li>Describe how to deploy third party libraries when required</li>
                </ul>
            </p>
        </section>
        <section name="Prerequisites">
            <p>
                Following applications are required to run any sample that comes with Synapse.
                Please make sure you have them properly installed and configured in your system.
            </p>
            <ul>
                <li>A Java runtime - JDK or JRE of version 1.6.0_23 or higher
                    </li>
                <li><a href="http://ant.apache.org">Apache Ant</a> version 1.6.5 or higher</li>
                <li>
                    A command line interface such as 'Command Prompt' on Windows and the Bash shell
                    on Unix/Linux systems
                </li>
            </ul>
            <p>
                When installing Java, make sure you setup the 'JAVA_HOME' environment variable
                properly. Also adding the JAVA_HOME/bin directory to the system path will make
                running the samples much easier.
            </p>
            <p>
                In addition to the applications listed above, some samples require setting up few
                other external resources such as JMS brokers and database engines. You can find the
                relevant documentation under the '<a href="#Setting_Up_Additional_Resources">Setting Up Additional Features</a>'
                section.
            </p>
            <p>
                It is also advisable to run Synapse in the debug mode when trying out the example
                configurations. This will give you important runtime status information that can be
                used to better understand the functionality of Synapse. To enable the debug mode,
                open up the lib/log4j.properties file and specify 'DEBUG' logging mode for the
                'org.apache.synapse' package.
            </p>
            <div class="consoleOutput">log4j.category.org.apache.synapse=DEBUG</div>
        </section>
        <section name="Understanding the Samples">
            <p>
                A Synapse sample scenario is generally comprised of three elements.
            </p>
            <ul>
                <li>
                    Sample Synapse configuration (an XML configuration file given as the input
                    of Synapse)
                </li>
                <li>
                    Sample service (an Axis2 based Web Service to which Synapse will send messages)
                </li>
                <li>
                    Sample client (an Axis2 based service client which is used to send requests to
                    Synapse)
                </li>
            </ul>
            <subsection name="Sample Synapse Configurations">
                <p>
                    All the sample Synapse configurations are housed under the repository/conf/sample
                    directory. These configuration files are named in the following format.
                </p>
                <div class="consoleOutput">synapse_sample_n.xml</div>
                <p>
                    Here 'n' is a number which uniquely identifies the sample. This number can be passed
                    as an argument to the Synapse startup script in order to start Synapse with a particular
                    sample configuration. For an example to start Synapse with the configuration numbered
                    100 (ie synapse_sample_100.xml) run one of the following commands in the command line
                    interface.
                </p>
                <div class="command">
                    Unix/Linux: sh synapse.sh -sample 100<br/>
                    Windows: synapse.bat -sample 100
                </div>
            </subsection>
            <subsection name="Sample Services">
                <p>
                    All the source of example services can be found in the samples/axis2Server/src directory.
                    You will find the source code for following services in this directory.
                </p>
                <table>
                    <tr>
                        <th>Service</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>SimpleStockQuoteService</td>
                        <td>
                            This service has four operations; getQuote (in-out), getFullQuote(in-out),
                            getMarketActivity(in-out) and placeOrder (in-only). The getQuote operation
                            will generate a sample stock quote for a given symbol. The getFullQuote
                            operation will generate a history of stock quotes for the symbol for a
                            number of days, and the getMarketActivity operation returns stock quotes
                            for a list of given symbols. The placeOrder operation will accept a one
                            way message for an order.
                        </td>
                    </tr>
                    <tr>
                        <td>SecureStockQuoteService</td>
                        <td>
                            This service is a clone of the SimpleStockQuoteService, but has
                            WS-Security enabled and an attached security policy for signing and
                            encryption of messages.
                        </td>
                    </tr>
                    <tr>
                        <td>ReliableStockQuoteService</td>
                        <td>
                            This service is a clone of the SimpleStockQuoteService, but has
                            WS-ReliableMessaging enabled.
                        </td>
                    </tr>
                    <tr>
                        <td>MTOMSwASampleService</td>
                        <td>
                            This service has three operations uploadFileUsingMTOM(in-out),
                            uploadFileUsingSwA(in-out) and oneWayUploadUsingMTOM(in-only) and
                            demonstrates the use of MTOM and SwA. The uploadFileUsingMTOM and
                            uploadFileUsingSwA operations accept a binary image from the SOAP request
                            as MTOM and SwA, and returns this image back again as the response, while
                            the oneWayUploadUsingMTOM saves the request message to disk.
                        </td>
                    </tr>
                    <tr>
                        <td>LoadbalanceFailoverService</td>
                        <td>
                            A simple web service that can be used to test state less as well as
                            session aware load balancing scenarios.
                        </td>
                    </tr>
                </table>
                <p>
                    You can compile and deploy any of these services into the provided sample Axis2
                    server by switching to the corresponding directory and invoking 'ant'. For an
                    example to setup the SimpleStockQuoteService, switch to the
                    samples/axis2Server/src/SimpleStockQuoteService directory and run the 'ant'
                    command. You will get an output similar to the following.
                </p>
                <div class="consoleOutput">user@host:/tmp/synapse-1.1/samples/axis2Server/src/SimpleStockQuoteService$ ant
Buildfile: build.xml
...
build-service:
   ....
      [jar] Building jar: /tmp/synapse-1.1/samples/axis2Server/repository/services/SimpleStockQuoteService.aar

BUILD SUCCESSFUL
Total time: 3 seconds</div>
                <p>
                    To start the Axis2 server, go to the samples/axis2Server directory and execute
                    the axis2server.sh or axis2server.bat script. This starts the Axis2 server with
                    the HTTP transport listener on port 9000 and HTTPS on port 9002 respectively.
                    For some samples it is required to enable additional transport listeners for the
                    sample Axis2 server. The resources listed under '<a href="#Setting_Up_Additional_Resources">Setting Up Additional Features'</a>
                    section provides more information on this.
                </p>
            </subsection>
            <subsection name="Sample Client Applications">
                <p>
                    The client applications that come with Synapse are able to send SOAP, REST or
                    POX messages over transports like HTTP/S and JMS. They also support WS-Addressing,
                    WS-Security and WS-ReliableMessaging. Some sample clients can be used to send
                    pure binary or plain text messages. They are also capable of sending optimized
                    binary content using MTOM or SwA. Most sample scenarios involve invoking one
                    of these clients to send messages to Synapse. Synapse will then mediate those
                    requests and forward them to the sample services deployed on Axis2.
                </p>
                <p>
                    The sample clients can be executed from the samples/axis2Client directory
                    using the provided ant script. Simply executing 'ant' displays the available
                    clients and some of the options used to configure them. The sample clients
                    available are further described in the next section.
                </p>
            </subsection>
        </section>
        <section name="Sample Axis2 Clients">
            <subsection name="Stock Quote Client">
                <p>
                    This is a simple SOAP client that can send stock quote requests, receive
                    generated quotes and display the last sale price for a stock symbol.
                </p>
                <div class="command">ant stockquote [-Dsymbol=IBM|MSFT|SUN|..]
  [-Dmode=quote | customquote | fullquote | placeorder | marketactivity]
  [-Dsoapver=soap11 | soap12]
  [-Daddurl=http://localhost:9000/services/SimpleStockQuoteService]
  [-Dtrpurl=http://localhost:8280] [-Dprxurl=http://localhost:8280]
  [-Dpolicy=../../repository/conf/sample/resources/policy/policy_1.xml]</div>
                <p>
                    The client is able to operate in the following modes, and send the payloads
                    listed below as SOAP messages.
                </p>
                <table>
                    <tr>
                        <th>Mode</th>
                        <th>Payload</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>quote</td>
                        <td>
                            <div class="xmlConf">&lt;m:getQuote xmlns:m="http://services.samples"&gt;
  &lt;m:request&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
  &lt;/m:request&gt;
&lt;/m:getQuote&gt;</div>
                        </td>
                        <td>
                            Sends a quote request for a single stock symbol. The response
                            contains the last sales price for the stock which will be displayed on
                            console.
                        </td>
                    </tr>
                    <tr>
                        <td>customquote</td>
                        <td>
                            <div class="xmlConf">&lt;m0:checkPriceRequest xmlns:m0="http://www.apache-synapse.org/test"&gt;
  &lt;m0:Code&gt;symbol&lt;/m0:Code&gt;
&lt;/m0:checkPriceRequest&gt;</div>
                        </td>
                        <td>
                            Sends a quote request in a custom format. Synapse will transform this
                            custom request to the standard stock quote request format and send it to
                            the Axis2 service. Upon receipt of the response, it will be transformed
                            again to a custom response format and returned to the client, which will
                            then display the last sales price.
                        </td>
                    </tr>
                    <tr>
                        <td>fullquote</td>
                        <td>
                            <div class="xmlConf">&lt;m:getFullQuote xmlns:m="http://services.samples"&gt;
  &lt;m:request&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
  &lt;/m:request&gt;
&lt;/m:getFullQuote&gt;</div>
                        </td>
                        <td>
                            Gets quote reports for a stock symbol over a number of days (i.e. last 100
                            days of the year).
                        </td>
                    </tr>
                    <tr>
                        <td>placeorder</td>
                        <td><div class="xmlConf">&lt;m:placeOrder xmlns:m="http://services.samples"&gt;
  &lt;m:order&gt;
    &lt;m:price&gt;3.141593E0&lt;/m:price&gt;
    &lt;m:quantity&gt;4&lt;/m:quantity&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
  &lt;/m:order&gt;
&lt;/m:placeOrder&gt;</div></td>
                        <td>
                            Places an order for stocks using a one way request.
                        </td>
                    </tr>
                    <tr>
                        <td>marketactivity</td>
                        <td><div class="xmlConf">&lt;m:getMarketActivity xmlns:m="http://services.samples"&gt;
  &lt;m:request&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
    ...
    &lt;m:symbol&gt;MSFT&lt;/m:symbol&gt;
  &lt;/m:request&gt;
&lt;/m:getMarketActivity&gt;</div></td>
                        <td>
                             Gets a market activity report for the day (i.e. quotes for multiple
                            symbols)
                        </td>
                    </tr>
                </table>
                <p>
                    To run the stock quote client in a particular mode, pass the name of the mode
                    as a system property as follows.
                </p>
                <div class="command">ant stockquote -Dmode=placeorder</div>
                <p>
                    Behavior of the sample Axis2 client can be further customized by using the 'addurl',
                    'trpurl' and 'prxurl' parameters. These parameters enable the following modes of
                    operation.
                </p>
                <h5>Smart Client Mode</h5>
                <p>
                    The 'addurl' property sets the WS-Addressing EPR, and the 'trpurl' sets a
                    transport URL for a message. Thus by specifying both of these properties,
                    the client can operate in the 'smart client' mode, where the addressing EPR can
                    specify the ultimate receiver, while the transport URL set to Synapse will ensure
                    that any necessary mediation takes place before the message is delivered to the
                    ultimate receiver.
                </p>
                <div class="command">ant stockquote -Daddurl=&lt;addressingEPR&gt; -Dtrpurl=&lt;synapse&gt;</div>
                <h5>Gateway/Dumb Client Mode</h5>
                <p>
                    By specifying only a transport URL, the client operates in the 'dumb client'
                    mode, where it sends the message to Synapse and depends on the rules configured
                    in Synapse for proper mediation and routing of the message to the ultimate
                    destination.
                </p>
                <div class="command">ant stockquote -Dtrpurl=&lt;synapse&gt;</div>
                <h5>Proxy Client Mode</h5>
                <p>
                    In this mode, the client uses the 'prxurl' as a HTTP proxy to send the request.
                    Thus by setting the 'prxurl' to Synapse, the client can ensure that the message
                    will reach Synapse for mediation. The client can optionally set a WS-Addressing
                    EPR if required.
                </p>
                <div class="command">ant stockquote -Dprxurl=&lt;synapse&gt; [-Daddurl=&lt;addressingEPR&gt;]</div>
            </subsection>
            <subsection name="Generic JMS Client">
                <p>
                    The JMS client is able to send plain text, plain binary content or POX content
                    by directly publishing a JMS message to the specified destination. The JMS
                    destination name should be specified with the 'jms_dest' property. The 'jms_type'
                    property can specify 'text', 'binary' or 'pox' to specify the type of message
                    payload.
                </p>
                <p>
                    The plain text payload for a 'text' message can be specified through the 'payload'
                    property. For binary messages, the 'payload' property will contain the path to
                    the binary file. For POX messages, the 'payload' property will hold a stock
                    symbol name to be used within the POX request for stock order placement requests.
                </p>
                <div class="command">ant jmsclient -Djms_type=text -Djms_dest=dynamicQueues/JMSTextProxy -Djms_payload="24.34 100 IBM"
ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/JMSPoxProxy -Djms_payload=MSFT
ant jmsclient -Djms_type=binary -Djms_dest=dynamicQueues/JMSFileUploadProxy
                     -Djms_payload=./../../repository/conf/sample/resources/mtom/asf-logo.gif</div>
                <p>
                    The JMS client assumes the existence of a default ActiveMQ (v4.1.0 or above)
                    installation on the local machine. Refer JMS setup guide for more details.
                </p>
            </subsection>
            <subsection name="MTOM/SwA Client">
                <p>
                    The MTOM / SwA client is able to send a binary image file as a MTOM or SwA
                    optimized message, and receive the same file again through the response and save
                    it as a temporary file. The 'opt_mode' can specify 'mtom' or 'swa' respectively
                    for the above mentioned optimizations. Optionally the path to a custom file can
                    be specified through the 'opt_file' property, and the destination address can be
                    changed through the 'opt_url' property if required.
                </p>
                <div class="command">ant optimizeclient -Dopt_mode=[mtom | swa]</div>
            </subsection>
        </section>
        <section name="Setting Up Additional Features">
            <ul>
                <li><a href="jms.html">JMS Setup Guide</a></li>
                <li><a href="fix.html">FIX Setup Guide</a></li>
                <li><a href="tcp_udp.html">TCP/UDP Setup Guide</a></li>
                <li><a href="db.html">Database Setup Guide</a></li>
                <li><a href="script.html">Script Setup Guide</a></li>
                <li><a href="script.html#json-syn3">JSON Setup Guide</a></li>
                <li><a href="mail.html">E-Mail Setup Guide</a></li>
            </ul>
        </section>
    </body>
</document>
