| <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 <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">synapse.demo.0@gmail.com</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> |
