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.
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.
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.
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.
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:
This is a simple SOAP client that could send stock quote requests, and receive and display the last sale price for a stock symbol.
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]
The client is able to operate in the following modes, and send the payloads listed below as SOAP messages:
<m:getQuote xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getQuote><m0:checkPriceRequest xmlns:m0="http://www.apache-synapse.org/test"> <m0:Code>symbol</m0:Code> </m0:checkPriceRequest>
<m:getFullQuote xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getFullQuote><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><m:getMarketActivity xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
...
<m:symbol>MSFT</m:symbol>
</m:request>
</m:getMarketActivity>Note : See samples/axis2Client/src/samples/common/StockQuoteHandler.java for sample responses expected by the clients.
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.
e.g: ant stockquote -Daddurl=<addressingEPR> -Dtrpurl=<synapse>
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.
e.g: ant stockquote -Dtrpurl=<synapse>
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.
e.g: ant stockquote -Dprxurl=<synapse> [-Daddurl=<addressingEPR>]
Specifying a policy
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.
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.
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.
e.g:
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.gifNote: The JMS client assumes the existence of a default ActiveMQ (4.1.0 or above) installation on the local machine.
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.
e.g. ant optimizeclient -Dopt_mode=[mtom | swa]
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.
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
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 secondsTo 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
Sample services
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.
This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled and an attached security policy for signing and encryption of messages.
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.
Starting sample Synapse configurations
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:
synapse.bat -sample <n> synapse.sh -sample <n>
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.
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.
<!--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>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.
The JavaScript/E4X support is enabled by default and comes ready-to-use with the Synapse distribution.
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 here.