<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <title>Apache Synapse Samples</title>
  <meta name="generator" content="Amaya 9.54, see http://www.w3.org/Amaya/">
  <style type="text/css">
    .command {
        border: 1px dashed #3c78b5;
        text-align: left;
        background-color: #f0f0f0;
        padding: 3px;
        font-size: 11px;
        font-family: Courier;
        margin: 10px;
        line-height: 13px;
    }
    .consoleOutput {
        border: 1px dashed #3c78b5;
        font-size: 11px;
        font-family: Courier;
        margin: 10px;
        line-height: 13px;
        background-color: #f0f0f0;
        border-bottom: 1px dashed #3c78b5;
        padding: 3px;
        border-style: solid;
    }
    .info {
        border-style: solid;
        border-width: 1px;
        border-color: #090;
        background-color: #dfd;
        text-align:left;
        margin-top: 5px;
        margin-bottom: 5px;
    }
    li {
        font-family: Verdana, arial, sans-serif;
        font-size: 11px;
        line-height: 16px;
        color: #000000;
        font-weight: normal;
    }
    p {
        font-family: Verdana, arial, sans-serif;
        font-size: 11px;
        line-height: 16px;
        color: #000000;
        font-weight: normal;
    }
    pre {
        padding: 0px;
        margin-top: 5px;
        margin-left: 15px;
        margin-bottom: 5px;
        margin-right: 5px;
        text-align: left;
        background-color: #f0f0f0;
        padding: 3px;
        border: 1px dashed #3c78b5;
        font-size: 11px;
        font-family: Courier;
        margin: 10px;
        line-height: 13px;
    }
    h1 {
        font-size: 24px;
        line-height: normal;
        font-weight: bold;
        background-color: #f0f0f0;
        color: #003366;
        border-bottom: 1px solid #3c78b5;
        padding: 2px;
        margin: 36px 0px 4px 0px;
    }
    h2 {
        font-size: 18px;
        line-height: normal;
        font-weight: bold;
        background-color: #f0f0f0;
        border-bottom: 1px solid #3c78b5;
        padding: 2px;
        margin: 27px 0px 4px 0px;
    }
    h3 {
        font-size: 14px;
        line-height: normal;
        font-weight: bold;
        background-color: #f0f0f0;
        padding: 2px;
        margin: 21px 0px 4px 0px;
    }
    h4 {
        font-size: 12px;
        line-height: normal;
        font-weight: bold;
        background-color: #f0f0f0;
        padding: 2px;
        margin: 18px 0px 4px 0px;
    }</style>
</head>

<body>
<h1>Overview</h1>

<p></p>

<p>Synapse ships with a set of working examples that demonstrate some of the
basic features and capabilities of Synapse. A set of sample clients and
services are provided in addition to the sample configurations. Scripts are
provided to execute the sample scenarios as explained below. </p>

<h4>Prerequisites</h4>

<p>To try out the samples you will need Java development kit version 1.5.x or
later and Apache Ant version 1.6.5 or later. Ant can be downloaded from
http://ant.apache.org. The JMS examples can be executed against an ActiveMQ
installation by default (or another JMS provider with relevant configuration
changes.)</p>

<p></p>

<p>Note*: The samples and the documentation assume that you are running
Synapse in DEBUG mode. You can switch from the default INFO log messages to
DEBUG log messages by changing the line
"log4j.category.org.apache.synapse=INFO" as
"log4j.category.org.apache.synapse=DEBUG" in the lib/log4j.properties
file.</p>

<h2>Understanding the Samples</h2>

<table border="1" style="width: 100%">
  <caption></caption>
  <tbody>
    <tr>
      <td>Client</td>
      <td>Synapse</td>
      <td>Service</td>
    </tr>
    <tr>
      <td></td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td>ant stockquote</td>
      <td>./synapse.sh -sample &lt;n&gt;</td>
      <td>SimpleStockQuoteService</td>
    </tr>
    <tr>
      <td></td>
      <td></td>
      <td>SecureStockQuoteService etc.</td>
    </tr>
  </tbody>
</table>

<p>The above diagram depicts the interactions between the clients, Synapse
and the services at a higher level. The Clients are able to send SOAP/REST or
POX messages over transports such as http/s or JMS with WS-Addressing,
WS-Security or WS-Reliable messaging. They can send binary optimized content
using MTOM or SwA or binary or plain text JMS messages. After mediation
through Synapse, the requests are passed over to the sample services. The
sample clients and services are explained below.</p>

<p></p>

<h2>Using the Sample Clients</h2>

<p></p>

<p>The sample clients can be executed from the samples/axis2Client directory
through the provided ant script. Simply executing 'ant' displays the
available clients and some of the sample options used to configure them. The
sample clients available are listed below:</p>

<h3>1. Stock Quote Client</h3>

<p></p>

<p>This is a simple SOAP client that can send stock quote requests, and
receive and display the last sale price for a stock symbol. </p>
<pre>ant stockquote [-Dsymbol=IBM|MSFT|SUN|..]
  [-Dmode=quote | customquote | fullquote | placeorder | marketactivity]
  [-Daddurl=http://localhost:9000/soap/SimpleStockQuoteService]
  [-Dtrpurl=http://localhost:8080] [-Dprxurl=http://localhost:8080]
  [-Dpolicy=../../repository/conf/sample/resources/policy/policy_1.xml]</pre>

<p>The client is able to operate in the following modes, and send the
payloads listed below as SOAP messages:</p>
<ul>
  <li>quote - send a quote request for a single stock as follows. The
    response contains the last sales price for the stock which will be
    displayed 
    <pre>&lt;m:getQuote xmlns:m="http://services.samples/xsd"&gt;
  &lt;m:request&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
  &lt;/m:request&gt;
&lt;/m:getQuote&gt;</pre>
  </li>
  <li>customquote - send 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 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. 
    <pre>&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;</pre>
  </li>
  <li>fullquote - get quote reports for the stock over a number of days (i.e.
    last 100 days of the year). 
    <pre>&lt;m:getFullQuote xmlns:m="http://services.samples/xsd"&gt;
  &lt;m:request&gt;
    &lt;m:symbol&gt;IBM&lt;/m:symbol&gt;
  &lt;/m:request&gt;
&lt;/m:getFullQuote&gt;</pre>
  </li>
  <li>placeorder - place an order for stocks using a one way request 
    <pre>&lt;m:placeOrder xmlns:m="http://services.samples/xsd"&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;</pre>
  </li>
  <li>marketactivity - get a market activity report for the day (i.e. quotes
    for multiple symbols) 
    <pre>&lt;m:getMarketActivity xmlns:m="http://services.samples/xsd"&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;</pre>
  </li>
</ul>

<p>Note : See samples/axis2Client/src/samples/common/StockQuoteHandler.java
for sample responses expected by the clients.</p>

<h4>Smart Client Mode:</h4>

<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>
<pre>e.g: ant stockquote -Daddurl=&lt;addressingEPR&gt; -Dtrpurl=&lt;synapse&gt;</pre>

<h4>Gateway / Dumb Client Mode:</h4>

<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
Synapse rules for proper mediation and routing of the message to the ultimate
destination.</p>
<pre>e.g: ant stockquote -Dtrpurl=&lt;synapse&gt;</pre>

<h4>Proxy Client Mode:</h4>

<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>
<pre>e.g: ant stockquote -Dprxurl=&lt;synapse&gt; [-Daddurl=&lt;addressingEPR&gt;]</pre>

<p></p>

<p>Specifying a policy</p>

<p>By specifying a WS-Policy using the 'policy' property, QoS aspects such as
WS-Security can be enforced on the request. The policy can specify details
such as timestamps, signatures and encryption. See Apache Axis2 and Apache
Rampart documentation for more information.</p>

<p></p>

<h3>2. Generic JMS Client</h3>

<p></p>

<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></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 request.</p>

<p>e.g: </p>
<pre>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</pre>

<p>Note: The JMS client assumes the existence of a default ActiveMQ (4.1.0 or
above) installation on the local machine.</p>

<p></p>

<h3>3. MTOM / SwA Client</h3>

<p></p>

<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>
<pre>e.g. ant optimizeclient -Dopt_mode=[mtom | swa]</pre>

<p></p>

<h2>Starting the Sample Services</h2>

<p></p>

<p>The sample services ship with a pre-configured Axis2 server and
demonstrates in-only and in-out SOAP/REST or POX messaging over http/s and
JMS transports, using WS-Addressing, WS-Security and WS-Reliable Messaging
and handling of binary content using MTOM and SwA.</p>

<p>The sample services can be found in the samples/axis2Server/src directory
and can be built and deployed using ant from within each service directory</p>
<pre>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</pre>

<p></p>

<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 9002
respectively. To enable JMS transport, you will need to setup and start a JMS
provider. An ActiveMQ 4.0.1 or later JMS server on the local machine is
supported by default, and can be easily enabled by uncommenting the JMS
transport from the repository/conf/axis2.xml</p>

<p></p>

<h3>Sample services</h3>

<h4>1. SimpleStockQuoteService</h4>

<p>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.</p>

<h4>2. SecureStockQuoteService </h4>

<p>This service is a clone of the SimpleStockQuoteService, but has
WS-Security enabled and an attached security policy for signing and
encryption of messages.</p>

<h4>3. MTOMSwASampleService</h4>

<p>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.</p>

<p></p>

<h3>Starting Sample Synapse Configurations</h3>

<p>To start Synapse with the sample default configuration, execute the
synapse.bat or synapse.sh script found in the /bin directory. This starts up
an instance of Synapse using the Synapse and Axis2 configuration files
located in the repository/conf directory. The repository/conf/samples
directory contains the sample configurations available as
synapse_sample_&lt;n&gt;.xml files. To start a specific sample configuration
of Synapse, use the '-sample &lt;n&gt;' switch as follows:</p>
<pre>synapse.bat -sample &lt;n&gt;
synapse.sh -sample &lt;n&gt;</pre>

<p></p>

<h2>Setting up the JMS Listener</h2>

<p></p>

<p>The samples used in this guide assumes the existence of a local ActiveMQ
(4.1.0 or higher) installation properly installed and started up. You also
need to copy the following client JAR files into the Synapse 'lib' folder to
support ActiveMQ. These files are found in the 'lib' directory of the
ActiveMQ installation.</p>
<ul>
  <li>activeio-core-3.0.0-incubator.jar</li>
  <li>activemq-core-4.1.0-incubator.jar</li>
  <li>geronimo-j2ee-management_1.0_spec-1.0.jar</li>
</ul>

<p>To enable the JMS transport, you need to uncomment the JMS transport
listener configuration. If you are using a JMS provider other than ActiveMQ
this configuration should be updated to reflect your environment. Once
uncommented, the default configuration should be as follows. To enable JMS
for synapse, the repository/conf/axis2.xml must be updated, while to enable
JMS support for the sample Axis2 server the
samples/axis2Server/repository/conf/axis2.xml file must be updated.</p>
<pre>    &lt;!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)--&gt;
    &lt;transportReceiver name="jms" class="org.apache.synapse.transport.jms.JMSListener"&gt;
        &lt;parameter name="myTopicConnectionFactory" locked="false"&gt;
                &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
                &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
                &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;TopicConnectionFactory&lt;/parameter&gt;
        &lt;/parameter&gt;

        &lt;parameter name="myQueueConnectionFactory" locked="false"&gt;
                &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
                &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
                &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;QueueConnectionFactory&lt;/parameter&gt;
        &lt;/parameter&gt;

        &lt;parameter name="default" locked="false"&gt;
                &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
                &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
                &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;QueueConnectionFactory&lt;/parameter&gt;
        &lt;/parameter&gt;
    &lt;/transportReceiver&gt;</pre>

<p></p>

<h2 id="mailsender">Setting up Mail Transport Sender</h2>

<p>To enable the mail transport for samples, you need to uncomment the mail transport
sender configuration in the repository/conf/axis2.xml. Uncomment the
MailTransportSender sample configuration and make sure it points to a valid
SMTP configuration for any actual scenarios.</p>
<pre>    &lt;transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender"&gt;
        &lt;parameter name="mail.smtp.host"&gt;smtp.gmail.com&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.port"&gt;587&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.starttls.enable"&gt;true&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.auth"&gt;true&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.user"&gt;synapse.demo.0&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.password"&gt;mailpassword&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.from"&gt;synapse.demo.0@gmail.com&lt;/parameter&gt;
    &lt;/transportSender&gt;</pre>

<p></p>

<h2 id="script">Configuring Synapse for Script Mediator Support</h2>

<p></p>

<p>The Synapse Script Mediator is a Synapse extension, and thus all
prerequisites are not bundled by default with the Synapse distribution.
Before you use some script mediators you may need to manually add the
required jar files to the Synapse lib directory, and optionally perform other
installation tasks as may be required by the individual scripting language.
This is explained in the following sections.</p>

<h4>JavaScript Support</h4>

<p>The JavaScript/E4X support is enabled by default and comes ready-to-use
with the Synapse distribution.</p>

<h4>Ruby Support</h4>

<p>For Ruby support you need to download the 'jruby-complete.jar' from the
Maven repository for JRuby, and copy it into the 'lib' folder of Synapse .
The JRuby JAR can be downloaded from <a
href="http://repo1.maven.org/maven2/org/jruby/jruby-complete/">here</a>.</p>

<p></p>

<h2 id="derby">Setting up Derby database server</h2>

<p>You can download Apache Derby distribution from <a
href="http://db.apache.org/derby/">http://db.apache.org/derby/</a></p>
<ol>
  <li>Set up and start the Derby network server</li>
  <li>Create and open a connection to the database using the Derby client
    driver 
    <p>CONNECT
    'jdbc:derby://localhost:1527/synapsedb;user=synapse;password=synapse;create=true';</p>
  </li>
  <li>Create a table using the following statement 
    <p>create table company(name varchar(10), id varchar(10), price
    double);</p>
  </li>
  <li>Inserts some data using following statements 
    <p>insert into company values ('IBM','c1',0.0);</p>
    <p>insert into company values ('SUN','c2',0.0);</p>
    <p>insert into company values ('MSFT','c3',0.0);</p>
  </li>
</ol>

<p>When using Derby, you need to add derby.jar, derbyclient.jar and
derbynet.jar to the classpath. This can be done by putting the above three
jars into the Synapse lib directory. For testing these samples Derby 10.3.2.1
binary distribution was used.</p>

<p>You can use any other database product instead of Derby. Then you have to
change the database connection details accordingly. Also you have to copy the
required database driver jars to the Synapse classpath.</p>

<p></p>
</body>
</html>