Introduction
Apache Synapse comes with a collection of working examples that demonstrates the basic features of the Synapse ESB. In addition to the sample configurations, a set of sample client applications and services are provided which can be used to try out each of the examples. Most examples are self contained and can be run without any third party applications or libraries. A set of Ant build files and scripts are provided to make setting up the examples easier. A few examples however require deploying certain external libraries and using third party client applications.
The main objectives of this article are:
- Introduce the concept of Synapse samples
- Describe how to setup the environment for running samples
- Describe how to run the sample client applications and services
- Describe how to deploy third party libraries when required
Prerequisites
Following applications are required to run any sample that comes with Synapse. Please make sure you have them properly installed and configured in your system.
- A Java runtime - JDK or JRE of version 1.6.0_23 or higher
- Apache Ant version 1.6.5 or higher
- A command line interface such as 'Command Prompt' on Windows and the Bash shell on Unix/Linux systems
When installing Java, make sure you setup the 'JAVA_HOME' environment variable properly. Also adding the JAVA_HOME/bin directory to the system path will make running the samples much easier.
In addition to the applications listed above, some samples require setting up few other external resources such as JMS brokers and database engines. You can find the relevant documentation under the 'Setting Up Additional Features' section.
It is also advisable to run Synapse in the debug mode when trying out the example configurations. This will give you important runtime status information that can be used to better understand the functionality of Synapse. To enable the debug mode, open up the lib/log4j.properties file and specify 'DEBUG' logging mode for the 'org.apache.synapse' package.
Understanding the Samples
A Synapse sample scenario is generally comprised of three elements.
- Sample Synapse configuration (an XML configuration file given as the input of Synapse)
- Sample service (an Axis2 based Web Service to which Synapse will send messages)
- Sample client (an Axis2 based service client which is used to send requests to Synapse)
Sample Synapse Configurations
All the sample Synapse configurations are housed under the repository/conf/sample directory. These configuration files are named in the following format.
Here 'n' is a number which uniquely identifies the sample. This number can be passed as an argument to the Synapse startup script in order to start Synapse with a particular sample configuration. For an example to start Synapse with the configuration numbered 100 (ie synapse_sample_100.xml) run one of the following commands in the command line interface.
Windows: synapse.bat -sample 100
Sample Services
All the source of example services can be found in the samples/axis2Server/src directory. You will find the source code for following services in this directory.
| Service | Description |
|---|---|
| SimpleStockQuoteService | 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. |
| SecureStockQuoteService | This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled and an attached security policy for signing and encryption of messages. |
| ReliableStockQuoteService | This service is a clone of the SimpleStockQuoteService, but has WS-ReliableMessaging enabled. |
| MTOMSwASampleService | 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. |
| LoadbalanceFailoverService | A simple web service that can be used to test state less as well as session aware load balancing scenarios. |
You can compile and deploy any of these services into the provided sample Axis2 server by switching to the corresponding directory and invoking 'ant'. For an example to setup the SimpleStockQuoteService, switch to the samples/axis2Server/src/SimpleStockQuoteService directory and run the 'ant' command. You will get an output similar to the following.
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 port 9002 respectively. For some samples it is required to enable additional transport listeners for the sample Axis2 server. The resources listed under 'Setting Up Additional Features' section provides more information on this.
Sample Client Applications
The client applications that come with Synapse are able to send SOAP, REST or POX messages over transports like HTTP/S and JMS. They also support WS-Addressing, WS-Security and WS-ReliableMessaging. Some sample clients can be used to send pure binary or plain text messages. They are also capable of sending optimized binary content using MTOM or SwA. Most sample scenarios involve invoking one of these clients to send messages to Synapse. Synapse will then mediate those requests and forward them to the sample services deployed on Axis2.
The sample clients can be executed from the samples/axis2Client directory using the provided ant script. Simply executing 'ant' displays the available clients and some of the options used to configure them. The sample clients available are further described in the next section.
Sample Axis2 Clients
Stock Quote Client
This is a simple SOAP client that can send stock quote requests, receive generated quotes and display the last sale price for a stock symbol.
The client is able to operate in the following modes, and send the payloads listed below as SOAP messages.
| Mode | Payload | Description |
|---|---|---|
| quote |
<m:getQuote xmlns:m="http://services.samples">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getQuote>
|
Sends a quote request for a single stock symbol. The response contains the last sales price for the stock which will be displayed on console. |
| customquote |
<m0:checkPriceRequest xmlns:m0="http://www.apache-synapse.org/test">
<m0:Code>symbol</m0:Code>
</m0:checkPriceRequest>
|
Sends 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 Axis2 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. |
| fullquote |
<m:getFullQuote xmlns:m="http://services.samples">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getFullQuote>
|
Gets quote reports for a stock symbol over a number of days (i.e. last 100 days of the year). |
| placeorder |
<m:placeOrder xmlns:m="http://services.samples">
<m:order>
<m:price>3.141593E0</m:price>
<m:quantity>4</m:quantity>
<m:symbol>IBM</m:symbol>
</m:order>
</m:placeOrder> |
Places an order for stocks using a one way request. |
| marketactivity |
<m:getMarketActivity xmlns:m="http://services.samples">
<m:request>
<m:symbol>IBM</m:symbol>
...
<m:symbol>MSFT</m:symbol>
</m:request>
</m:getMarketActivity> |
Gets a market activity report for the day (i.e. quotes for multiple symbols) |
To run the stock quote client in a particular mode, pass the name of the mode as a system property as follows.
Behavior of the sample Axis2 client can be further customized by using the 'addurl', 'trpurl' and 'prxurl' parameters. These parameters enable the following modes of operation.
Smart Client Mode
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.
Gateway/Dumb Client Mode
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 rules configured in Synapse for proper mediation and routing of the message to the ultimate destination.
Proxy Client Mode
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.
Generic JMS Client
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.
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 requests.
The JMS client assumes the existence of a default ActiveMQ (v4.1.0 or above) installation on the local machine. Refer JMS setup guide for more details.
MTOM/SwA Client
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.