Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples.xml
------------------------------------------------------------------------------
svn:executable = *
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples_setup.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples_setup.xml?rev=1302321&view=auto
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples_setup.xml
(added)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples_setup.xml
Mon Mar 19 08:41:05 2012
@@ -0,0 +1,519 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+ <title>Apache Synapse Samples</title>
+ <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 <n></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><m:getQuote xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getQuote></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><m0:checkPriceRequest
xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:Code>symbol</m0:Code>
+</m0:checkPriceRequest></pre>
+ </li>
+ <li>fullquote - get quote reports for the stock over a number of days (i.e.
+ last 100 days of the year).
+ <pre><m:getFullQuote xmlns:m="http://services.samples/xsd">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getFullQuote></pre>
+ </li>
+ <li>placeorder - place an order for stocks using a one way request
+ <pre><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>marketactivity - get a market activity report for the day (i.e. quotes
+ for multiple symbols)
+ <pre><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>
+</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=<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>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>e.g: ant stockquote -Dprxurl=<synapse>
[-Daddurl=<addressingEPR>]</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_<n>.xml files. To start a specific sample configuration
+of Synapse, use the '-sample <n>' switch as follows:</p>
+<pre>synapse.bat -sample <n>
+synapse.sh -sample <n></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> <!--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></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> <transportSender name="mailto"
class="org.apache.synapse.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
+ <parameter name="mail.smtp.port">587</parameter>
+ <parameter
name="mail.smtp.starttls.enable">true</parameter>
+ <parameter name="mail.smtp.auth">true</parameter>
+ <parameter name="mail.smtp.user">synapse.demo.0</parameter>
+ <parameter
name="mail.smtp.password">mailpassword</parameter>
+ <parameter
name="mail.smtp.from">[email protected]</parameter>
+ </transportSender></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>
\ No newline at end of file
Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/samples_setup.xml
------------------------------------------------------------------------------
svn:executable = *
