This page gives generic setup instructions and prerequisites to start the ESB with sample configurations, deploy services, and run clients.
1. All ESB samples need:
- Java Development Kit / JRE version 1.6.* or 1.7.*
- Apache Ant 1.7.0 or later
For JMS related samples:
- ActiveMQ or another JMS provider with configuration.
JDK, Ant and ActiveMQ setup instructions are given in section Installation Prerequisites.
2. Once Apache Ant is set up, go to <ESB_HOME>/bin directory and run the
build.xml file using Apache Ant. You can do this by typing "ant" without quotes on a console in this directory. For example,
3. The samples and the documentation assumes that you are running the ESB 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=DEBUG in <ESB_HOME>/repository/conf/log4j.properties file.
Understanding the Samples
To explain different usecases, the ESB samples use several sample clients, ESB configurations and sample back-end services. The diagram below depicts the interaction between these sample clients, the ESB and services at a high level. The clients are able to send SOAP/REST or POX messages over transports such as HTTP/HTTPS or JMS with WS-Addressing, WS-Security, or WS-Reliable messaging. They can send binary optimized content using MTOM, SwA, binary or plain text JMS messages. After mediation through the ESB, the requests are passed over to sample services.
Starting Sample ESB Configurations
To start the WSO2 ESB with a selected sample configuration, run either
wso2esb-samples.sh (for Linux) or
wso2esb-samples.bat (for Windows) as follows:
Here, <n> denotes the number assigned to the sample. For example, to start the ESB with 'Sample 0: Introduction to ESB' configuration, run the following command:
<ESB_HOME>/repository/samples directory contains the sample configurations of ESB available as
synapse_sample_<n>.xml files. Again <n> denotes the number of the sample you are running. For example, the synapse configuration for 'Sample 0: Introduction to ESB' is 'synapse_sample_0.xml'.
If you execute the
wso2server.sh script found in the
/bin directory, it starts up an instance of the ESB using the Synapse and Axis2 configuration files located in the
Starting Sample Back-End Services
The back-end sample services come with a pre-configured Axis2 server, and demonstrates in-only and in-out SOAP/REST or POX messaging over HTTP/HTTPS and JMS transports using WS-Addressing, WS-Security, and WS-Reliable Messaging. They also handle binary content using MTOM and SwA.
1. Each back-end sample service can be found in a separate folder in
<ESB_HOME>/samples/axis2Server/src directory. They can be built and deployed using Ant from each service directory. You can do this by typing "ant" without quotes on a console from a selected sample directory. For example,
2. Next, start the Axis2 server. Go to
<ESB_HOME>/samples/axis2Server directory and execute either
axis2server.sh (for Linux) or
axis2server.bat(for Windows) script. For example,
This starts the Axis2 server with the HTTP transport listener on port 9000 and HTTPS on 9002 respectively.
To start multiple instances of the Axis2 server in different ports, run the commands as shown in the example below. It starts three Axis2 server instances in HTTP ports 9001, 9002 and 9003 respectively. Give unique names to each server.
3. If you want to enable JMS transport, you need to set up and start a JMS provider. An ActiveMQ 5.2.0 JMS server on the local machine is supported by default, and can be easily enabled by un-commenting the JMS transport from
Sample Services Explained
This service has four operations:
getQuote(in-out) - Generates a sample stock quote for a given symbol.
getFullQuote(in-out) - Generates a history of stock quotes for the symbol for a number of days.
getMarketActivity(in-out) - Returns stock quotes for a list of given symbols.
placeOrder(in-only) - Accepts 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 encrypting messages.
This service has three operations:
uploadFileUsingMTOM(in-out) - Accepts a binary image from the SOAP request as MTOM, and returns this image back again as the response.
uploadFileUsingSwA(in-out) - Accepts a binary image from the SOAP request as SwA, and returns this image back again as the response.
oneWayUploadUsingMTOM(in-only) - Saves the request message to the disk.
This service also demonstrates the use of MTOM and SwA.
Setting up the JMS Listener
The samples used in this guide assumes the existence of a local ActiveMQ 5.1.0 or higher (http://activemq.apache.org) installation, which is properly installed and started.
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 the ESB, the
<ESB_HOME>/repository/conf/axis2/axis2.xml must be updated. To enable JMS support for the sample Axis2 server, the
Also you need to copy relevant JMS client libraries to WSO2 ESB. For Apache ActiveMQ, copy
Setting up Mail Transport Sender and Receiver
To enable the mail transport sender for samples, you need to uncomment the mail transport sender configuration in
repository/conf/axis2/axis2.xml file and make sure it points to a valid SMTP configuration for any actual scenarios.
To enable the mail transport receiver for samples, you need to uncomment the mail transport receiver configuration in the
You need to provide correct parameters for a valid mail account at service level.
Configuring WSO2 ESB for the FIX Transport
Setting up the FIX Transport
To run the FIX samples used in this guide you need a local Quickfix/J (http://www.quickfixj.org) installation. Download Quickfix/J from: .
Simply uncomment the FIX transport sender and FIX transport receiver configurations in
repository/conf/axis2/axis2.xml. Alternatively, if the FIX transport management bundle is in use you can enable the FIX transport listener and the sender from the WSO2 ESB management console. Login to the console and navigate to "Transports" on management menu. Scroll down to locate the sections related to the FIX transport. Simply click on the "Enable" links to enable the FIX listener and the sender.
Configuring the ESB for FIX Samples
In order to configure WSO2 ESB to run the FIX samples given in this guide, you need to create some FIX configuration files as specified below.
You can find the config files in
FileStorePath property in the following two files should point to two directories in your local file system. Once the samples are executed, Synapse will create FIX message stores in these two directories.
Put the following entries in a file called
Put the following entries in a file called
Configuring Sample FIX Applications
If you use a binary distribution of Quickfix/J, the two samples and their configuration files are all packed to a single JAR file called
quickfixj-examples.jar. You have to extract the JAR file, modify the configuration files and pack them to a JAR file again under the same name.
You can pass the new configuration file as a command line parameter too, in that case you do not need to modify the
quickfixj-examples.jar. You can copy the
config files from
<QFJ_HOME>/etc folder. Execute the sample apps from
<QFJ_HOME>/bin, ./banzai.sh/bat ../etc/banzai.cfg executor.sh/bat ../etc/executor.cfg.
Locate and edit the FIX configuration file of Executor to be as follows. This file is usually named
Locate and edit the FIX configuration file of Banzai to be as follows. This file is usually named
FileStorePath property in the above two files should point to two directories in your local file system. The launcher scripts for the sample application can be found in the bin directory of Quickfix/J distribution.
For more information regarding the FIX sample applications, see the Example Applications () section in the Quickfix/J documentation. For more information on configuring Quickfix/J applications, see the Configuring Quickfix/J ( ) section of the Quickfix/J documentation.
Configure WSO2 ESB for AMQP Transport
The samples used in this guide assumes the existence of a local QPid (1.0-M2 or higher) installation properly installed and started up. You also need to copy the following client JAR files into the
lib directory of the QPid installation.
- slf4j-api-1.4.0.jar **
- slf4j-log4j12-1.4.0.jar **
To configure FIX (Quickfix/J 1.3) with AMQP (QPid-1.0-M2) copy the
sl4j-* libraries that come with QPid and ignore the
sl4j-* libraries that come with Quickfix/J.
To enable the AMQP over JMS transport, you need to uncomment the JMS transport listener configuration. To enable AMQP over JMS for ESB,
Locate and edit the AMQP connection settings file for the message consumer. This file is usually named
direct.properties and can be found in the
Locate and edit the AMQP connection settings file for WSO2 ESB. This file is usually named
conn.properties and can be found in the
Configure WSO2 ESB for TCP Transport
To enable the TCP transport for samples, simply open up the
If you wish to use the sample Axis2 client to send TCP messages, you have to uncomment the TCP transport sender configuration in the
Configure WSO2 ESB for UDP Transport
To enable the UDP transport for samples, open the file
If you wish to use the sample Axis2 client to send UDP messages, you have to uncomment the UDP transport sender configuration in the
Configuring the ESB for Script Mediator Support
The Script Mediator is a Synapse extension, and thus all pre-requisites for all BSF supported scripting languages may not be bundled by default with the ESB distribution. Before you use some script mediators, you may need to manually add the required JAR files to the
<ESB_HOME>/repository/components/lib directory, and optionally perform other installation tasks as may be required by the individual scripting language. This is detailed in the following sections.
For Ruby support you need to install the "WSO2 Carbon - JRuby Engine for Mediation" feature. This feature is available in the WSO2 P2 repository. Use the WSO2 Carbon Component Manager UI in the management console to connect to the WSO2 P2 repository and install the above feature. This feature will install a JRuby 1.3 engine in the ESB runtime.
Alternatively, you can also download and install the JRuby engine manually. Download the file named
jruby-complete-1.3.0.wso2v1.jar from the WSO2 P2 repository and copy it into the
Setting up Derby database server
1. Download Apache Derby distribution from http://db.apache.org/derby.
2. Set up and start the Derby network server.
3. Create and open a connection to the database using the Derby client driver.
4. Create a table using the following statement.
5. Inserts some data using following statements.
When using Derby, you need to add
derbynet.jar to the classpath. This can be done by copying the above three JARs into the
<ESB_HOME>/repository/components/extensions directory. For testing these samples Derby10.3.2.1 binary distribution is used.
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 ESB classpath.
Setting up Synapse DataSources
Definition of the reusable database connection pool or datasources can be done using
datasources.properties file. It is possible to configure any number of datasources. Currently this only supports two types of datasources and those are based on Apache DBCP datasources. Those types are
PerUserPoolDataSource (based on Apache DBCP). The following configuration includes both definition.
Configuration is similar to the
log4j appender configuration.
It requires two databases, follow the above steps to create the two databases
jdbc:derby://localhost:1527/reportdb using the user name and password as
esb. Fill in the data for those two databases as per described in the above section
To secure data sources password, you should use the mechanism for
securing secret Information. If that mechanism is used, then passwords that have been specified are considered as aliases and those are used for picking actual passwords. To get password securely, you should set the password provider for each data source. The password provider should be an implementation of the following:
For run this sample, you just need to uncomment
datasources.properties. Those files are in conf directory.
The sample clients can be executed from the
<ESB_HOME>/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:
Stock Quote Client
This is a simple SOAP client that could send stock quote requests, and receive 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:
- quote - Sends a quote request for a single stock as follows. The response contains the last sales price for the stock which would be displayed.
- customquote - Sends a quote request in a custom format. The ESB 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.
- fullquote - Gets quote reports for the stock over a number of days (for example, last 100 days of the year).
- placeorder - Places an order for stocks using a one way request.
- marketactivity - Gets a market activity report for the day (for example, quotes for multiple symbols).
Smart Client Mode:
addurl property sets the WS-Addressing EPR, and the
trpurl sets a transport URL for a message. Thus by specifying both properties, the client can operate in the
smart client mode, where the addressing EPR could specify the ultimate receiver, while the transport URL set to the ESB ensures that any necessary mediation takes place before the message is delivered to the ultimate receiver. For example:
Gateway / Dumb Client Mode:
By specifying only a transport URL, the client operates in the
dumb client mode, where it sends the message to the ESB and depends on the ESB rules for proper mediation and routing of the message to the ultimate destination. For example:
Proxy Client Mode:
In this mode, the client uses the
prxurl as an HTTP proxy to send the request. Thus by setting the
prxurl to the ESB, the client could ensure that the message would reach the ESB for mediation. The client could optionally set a WS-Addressing EPR if required. For example:
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 specifies details such as timestamps, signatures, and encryption.
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 could 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 would 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. For example:
The JMS client assumes the existence of a default ActiveMQ (5.2.0) installation on the local machine.
MTOM / SwA Client
The MTOM / SwA client can 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
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. For example: