| <?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 demonstrates some of the |
| basic features and capabilities of Synapse. A set of sample clients and |
| services are provided in addition to the sample configurations, and |
| scripts are provided to execute the sample scenarions as explained below. |
| </p> |
| <h4> |
| Pre-requisites |
| </h4> |
| <p> |
| You will need a Java development kit / JRE version 1.4 or later and Apache |
| Ant 1.5 or later at a minimum to try out the samples. Ant can be |
| downloaded from http://ant.apache.org. The JMS examples could be executed |
| against an ActiveMQ installation by default (or another JMS provider with |
| configuration) and any https examples would require a JDK version 1.5 or |
| later. |
| </p> |
| <p/> |
| <p> |
| Note*: The samples and the documentation assumes that you are running |
| Synapse in DEBUG mode. You could 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> |
| <p/> |
| <p> |
| The above diagram depicts the interactions between the clients, Synapse |
| and services at a high 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 could 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 could 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 could 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 would 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 would |
| transform this custom request into the standard stock quote request |
| format and send it to the service. Upon receipt of the response, it |
| would 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 could operate in the 'smart client' mode, where the addressing |
| EPR could specify the ultimate receiver, while the transport URL set to |
| Synapse would ensure that any necessary mediation takes place before the |
| message is delivered to the ultimate reciver. |
| </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 could ensure |
| that the message would reach Synapse for mediation. The client could |
| 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 could be enforced on the request. The policy could 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 could specify 'text', 'binary' or 'pox' to specify |
| the type of message payload. |
| </p> |
| <p/> |
| <p> |
| The plain text payload for a 'text' message could be specified through the |
| 'payload' property. For binary messages, the 'payload' property would |
| contain the path to the binary file. For POX messages, the 'payload' |
| property would 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' could specify 'mtom' or |
| 'swa' respectively for the above mentioned optimizations. Optionally the |
| path to a custom file could be specified through the 'opt_file' property, |
| and the destination address could 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 could be built and deployed using ant from within each service |
| directory |
| </p> |
| <pre xml:space="preserve">user@host:/tmp/synapse-1.0/samples/axis2Server/src/SimpleStockQuoteService$ ant |
| Buildfile: build.xml |
| ... |
| build-service: |
| .... |
| [jar] Building jar: /tmp/synapse-1.0/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 could be easily enabled by |
| uncommenting the JMS transport from the repository/conf/axis2.xml |
| </p> |
| <p/> |
| <p> |
| Sample services |
| </p> |
| <h3> |
| 1. SimpleStockQuoteService |
| </h3> |
| <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> |
| <h3> |
| 2. SecureStockQuoteService |
| </h3> |
| <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> |
| <h3> |
| 3. MTOMSwASampleService |
| </h3> |
| <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> |
| Starting sample Synapse configurations |
| </p> |
| <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 JMS |
| </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> |
| <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/> |
| <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.axis2.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="script"> |
| Configuring Synapse for Script Mediator support |
| </h2> |
| <p/> |
| <p> |
| The Synapse Script Mediator is a Synapse extension, and thus all |
| pre-requisites 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 detailed 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/> |
| </body> |
| </html> |