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 2011/12/28 10:23:11 UTC
svn commit: r1225148 [7/15] - in /synapse/branches/2.1/src/site: ./
xdoc/1_0/ xdoc/1_1/ xdoc/1_1_1/ xdoc/1_2/
Propchange: synapse/branches/2.1/src/site/xdoc/1_1/samples.xml
------------------------------------------------------------------------------
svn:executable = *
Added: synapse/branches/2.1/src/site/xdoc/1_1/samples_setup.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_1/samples_setup.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_1/samples_setup.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_1/samples_setup.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,631 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <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" xml:space="preserve">
+ .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>
+ 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>
+ 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/>
+ <tbody>
+ <tr>
+ <td>
+ Client
+ </td>
+ <td>
+ Synapse
+ </td>
+ <td>
+ Service
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td>
+ ant stockquote
+ </td>
+ <td>
+ ./synapse.sh -sample <n>
+ </td>
+ <td>
+ SimpleStockQuoteService
+ </td>
+ </tr>
+ <tr>
+ <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/>
+ <h2>
+ Using the Sample Clients
+ </h2>
+ <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>
+ 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 xml:space="preserve">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>
+ </li>
+ <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 xml:space="preserve"><m:getQuote xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getQuote></pre>
+ </li>
+ <li>
+ </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 xml:space="preserve"><m0:checkPriceRequest xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:Code>symbol</m0:Code>
+</m0:checkPriceRequest></pre>
+ </li>
+ <li>
+ </li>
+ <li>
+ fullquote - get quote reports for the stock over a number of days (i.e.
+ last 100 days of the year).
+<pre xml:space="preserve"><m:getFullQuote xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getFullQuote></pre>
+ </li>
+ <li>
+ </li>
+ <li>
+ placeorder - place an order for stocks using a one way request
+<pre xml:space="preserve"><m:placeOrder xmlns:m="http://services.samples/xsd">
+ <m:order>
+ <m:price>3.141593E0</m:price>
+ <m:quantity>4</m:quantity>
+ <m:symbol>IBM</m:symbol>
+ </m:order>
+</m:placeOrder></pre>
+ </li>
+ <li>
+ </li>
+ <li>
+ marketactivity - get a market activity report for the day (i.e. quotes
+ for multiple symbols)
+<pre xml:space="preserve"><m:getMarketActivity xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ ...
+ <m:symbol>MSFT</m:symbol>
+ </m:request>
+</m:getMarketActivity></pre>
+ </li>
+ <li>
+ </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 xml:space="preserve">e.g: ant stockquote -Daddurl=<addressingEPR> -Dtrpurl=<synapse></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 xml:space="preserve">e.g: ant stockquote -Dtrpurl=<synapse></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 xml:space="preserve">e.g: ant stockquote -Dprxurl=<synapse> [-Daddurl=<addressingEPR>]</pre>
+
+ <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/>
+ <h3>
+ 2. Generic JMS Client
+ </h3>
+ <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>
+ 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 xml:space="preserve">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/>
+ <h3>
+ 3. MTOM / SwA Client
+ </h3>
+ <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 xml:space="preserve">e.g. ant optimizeclient -Dopt_mode=[mtom | swa]</pre>
+
+ <p/>
+ <h2>
+ Starting the Sample Services
+ </h2>
+ <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 xml:space="preserve">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>
+ 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/>
+ <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/>
+ <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_<n>.xml
+ files. To start a specific sample configuration of Synapse, use the
+ '-sample <n>' switch as follows:
+ </p>
+<pre xml:space="preserve">synapse.bat -sample <n>
+synapse.sh -sample <n></pre>
+ <p/>
+ <h2>
+ Setting up the JMS Listener
+ </h2>
+ <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>
+ </li>
+ <li>
+ activeio-core-3.0.0-incubator.jar
+ </li>
+ <li>
+ </li>
+ <li>
+ activemq-core-4.1.0-incubator.jar
+ </li>
+ <li>
+ </li>
+ <li>
+ geronimo-j2ee-management_1.0_spec-1.0.jar
+ </li>
+ <li>
+ </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 xml:space="preserve"> <!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)-->
+ <transportReceiver name="jms" class="org.apache.synapse.transport.jms.JMSListener">
+ <parameter name="myTopicConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter>
+ </parameter>
+
+ <parameter name="myQueueConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+
+ <parameter name="default" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+ </transportReceiver></pre>
+ <p/>
+ <h2 id="mailsender">
+ Setting up Mail Transport Sender
+ </h2>
+ <p>
+ To enable the mail transport, you need to uncomment the mail transport
+ sender configuration in the repository/conf/axis2.xml. Change the
+ mail.smtp.host parameter value to a working SMTP host.
+ </p>
+<pre xml:space="preserve"> <!-- ================================================= -->
+ <!-- Mail Transport Sender -->
+ <!--Only need to uncomment the sender. Configuration is achieved with every client.
+ At any instant mail host should be given. Sample configuration has been given.
+ http://people.apache.org/~pzf/SMTPBase64Binding-0.2.html-->
+ <!-- ================================================= -->
+ <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host">localhost</parameter>
+ </transportSender></pre>
+ <p/>
+ <h2 id="script">
+ Configuring Synapse for Script Mediator Support
+ </h2>
+ <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/>
+ <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>
+ </li>
+ <li>
+ Set up and start the Derby network server
+ </li>
+ <li>
+ </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>
+ </li>
+ <li>
+ Create a table using the following statement
+ <p>
+ create table company(name varchar(10), id varchar(10), price double);
+ </p>
+ </li>
+ <li>
+ </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>
+ <li>
+ </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.1.1.0 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/>
+ </body>
+</html>
\ No newline at end of file
Propchange: synapse/branches/2.1/src/site/xdoc/1_1/samples_setup.xml
------------------------------------------------------------------------------
svn:executable = *