Author: hiranya
Date: Fri Dec 31 09:41:07 2010
New Revision: 1054076
URL: http://svn.apache.org/viewvc?rev=1054076&view=rev
Log:
Samples setup guide
Added:
synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/samples/setup/index.xml
Modified:
synapse/trunk/scratch/hiranya/website/src/site/site.xml
Modified: synapse/trunk/scratch/hiranya/website/src/site/site.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/scratch/hiranya/website/src/site/site.xml?rev=1054076&r1=1054075&r2=1054076&view=diff
==============================================================================
--- synapse/trunk/scratch/hiranya/website/src/site/site.xml (original)
+++ synapse/trunk/scratch/hiranya/website/src/site/site.xml Fri Dec 31 09:41:07
2010
@@ -34,6 +34,7 @@
</menu>
<menu name="Documentation">
<item name="Quick Start Guide" href="userguide/quick_start.html"/>
+ <item name="Samples Setup Guide"
href="userguide/samples/setup/index.html"/>
<item name="Samples Catalog" href="userguide/samples.html"/>
</menu>
<menu name="Developer Resources">
Added:
synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/samples/setup/index.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/samples/setup/index.xml?rev=1054076&view=auto
==============================================================================
---
synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/samples/setup/index.xml
(added)
+++
synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/samples/setup/index.xml
Fri Dec 31 09:41:07 2010
@@ -0,0 +1,351 @@
+<?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>Java Development Kit version 1.5 or higher (1.6
recommended)</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 'Setting Up Additional
Resources' 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">u...@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 'Setting
Up Additional Resources'
+ 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
+ through 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"><m:getQuote
xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getQuote></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"><m0:checkPriceRequest
xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:Code>symbol</m0:Code>
+</m0:checkPriceRequest></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"><m:getFullQuote
xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getFullQuote></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"><m:placeOrder
xmlns:m="http://services.samples">
+ <m:order>
+ <m:price>3.141593E0</m:price>
+ <m:quantity>4</m:quantity>
+ <m:symbol>IBM</m:symbol>
+ </m:order>
+</m:placeOrder></div></td>
+ <td>
+ Places an order for stocks using a one way request.
+ </td>
+ </tr>
+ <tr>
+ <td>marketactivity</td>
+ <td><div class="xmlConf"><m:getMarketActivity
xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ ...
+ <m:symbol>MSFT</m:symbol>
+ </m:request>
+</m:getMarketActivity></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>
+ </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 Resources">
+
+ </section>
+ </body>
+</document>
