You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2010/12/31 10:41:07 UTC
svn commit: r1054076 - in /synapse/trunk/scratch/hiranya/website/src/site:
site.xml xdoc/userguide/samples/setup/index.xml
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">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 '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>