| <?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> |
