ESB Samples Setup

This page describes the prerequisites and instructions to start the ESB with sample configurations, deploy the sample back-end services, and set up any listeners, transports, etc. required by the samples. Once you have set up the samples, you can run them using the sample clients.

Prerequisites

1. Install required software as described in Installation Prerequisites.
   
   • For all samples, you must install the correct version of the Java Development Kit/JRE and Apache Ant.
   • For JMS samples, install ActiveMQ or another JMS provider.
2. In the <ESB_HOME>/bin directory, run the ant command to build the build.xml file using Apache Ant. For example:
3. The samples and the documentation assume 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=INFO to 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:

wso2esb-samples.bat -sn <n>
./wso2esb-samples.sh -sn <n>

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:

wso2esb-samples.sh -sn 0

The <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.bat or 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 <ESB_HOME>/repository/conf directory.

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,

user@host:/tmp/wso2esb-2.0/samples/axis2Server/src/SimpleStockQuoteService$ ant
Buildfile: build.xml
 ...
build-service:
   ....
      [jar] Building jar: /tmp/wso2esb-2.0/samples/axis2Server/repository/services/SimpleStockQuoteService.aar

BUILD SUCCESSFUL
Total time: 3 seconds

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,

C:/wso2/wso2esb/samples/axis2Server>axis2server.bat

./axis2server.sh

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.

./axis2server.sh -http 9001 -https 9005 -name MyServer1
./axis2server.sh -http 9002 -https 9006 -name MyServer2
./axis2server.sh -http 9003 -https 9007 -name MyServer3

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 <ESB_HOME>/repository/conf/axis2/axis2.xml.

Sample Services Explained

1. SimpleStockQuoteService

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.

2. SecureStockQuoteService

This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled and an attached security policy for signing and encrypting messages.

3. MTOMSwASampleService

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 <ESB_HOME>/samples/axis2Server/repository/conf/axis2.xml file must be updated.

Also you need to copy relevant JMS client libraries to WSO2 ESB. For Apache ActiveMQ, copy activemq-core-5.7.0.jar, geronimo-j2ee-management_1.1_spec-1.0.1.jar, and geronimo-jms_1.1_spec-1.1.1.jar from <ActiveMQ_HOME>/lib to <ESB_HOME>/repository/components/lib.

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

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 the <ESB_HOME>/ 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 <ESB_HOME>/repository/conf/axis2/axis2.xml file.

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: http://www.quickfixj.org/downloads.

Simply uncomment the FIX transport sender and FIX transport receiver configurations in <ESB_HOME>/ 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.

The 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 fix-synapse.cfg.

[default]
FileStorePath=repository/logs/fix/store
ConnectionType=acceptor
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ValidOrderTypes=1,2,F
SenderCompID=SYNAPSE
TargetCompID=BANZAI
UseDataDictionary=Y
DefaultMarketPrice=12.30

[session]
BeginString=FIX.4.0
SocketAcceptPort=9876

Put the following entries in a file called synapse-sender.cfg.

[default]
FileStorePath=repository/logs/fix/data
SocketConnectHost=localhost
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5
SenderCompID=SYNAPSE
TargetCompID=EXEC
ConnectionType=initiator

 [session]
BeginString=FIX.4.0
SocketConnectPort=19876

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 <ESB_HOME>/repository/samples/resources/fix folder to <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 executor.cfg.

[default]
FileStorePath=examples/target/data/executor
ConnectionType=acceptor
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ValidOrderTypes=1,2,F
SenderCompID=EXEC
TargetCompID=SYNAPSE
UseDataDictionary=Y
DefaultMarketPrice=12.30

[session]
BeginString=FIX.4.0
SocketAcceptPort=19876

Locate and edit the FIX configuration file of Banzai to be as follows. This file is usually named banzai.cfg.

[default]
FileStorePath=examples/target/data/banzai
ConnectionType=initiator
SenderCompID=BANZAI
TargetCompID=SYNAPSE
SocketConnectHost=localhost
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5

[session]
BeginString=FIX.4.0
SocketConnectPort=9876

The 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 (http://www.quickfixj.org/quickfixj/usermanual/1.5.0/usage/examples.html) section in the Quickfix/J documentation. For more information on configuring Quickfix/J applications, see the Configuring Quickfix/J (http://www.quickfixj.org/quickfixj/usermanual/1.5.0/usage/configuration.html) 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 <ESB_HOME>/repository/components/lib directory to support AMQP. These files are found in the lib directory of the QPid installation.

• qpid-client-1.0-incubating-M2.jar
• qpid-common-1.0-incubating-M2.jar
• geronimo-jms_1.1_spec-1.0.jar
• slf4j-api-1.4.0.jar **
• slf4j-log4j12-1.4.0.jar **

To enable the AMQP over JMS transport, uncomment the JMS transport listener configuration. To enable AMQP over JMS for ESB,  <ESB_HOME>/repository/conf/axis2/axis2.xml must be updated, while to enable JMS support for the sample Axis2 server the <ESB_HOME>/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 \-->
<transportReceiver name="jms">
</transportReceiver>

<transportSender name="jms">
</transportReceiver>

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 <ESB_HOME>/repository/samples/resources/fix directory.

java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
# register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.qpidConnectionfactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
# Register an AMQP destination in JNDI
# destination.[jniName] = [BindingURL]
destination.directQueue = direct://amq.direct//QpidStockQuoteService?routingkey='QpidStockQuoteService'
destination.replyQueue = direct://amq.direct//replyQueue?routingkey='replyQueue'

Locate and edit the AMQP connection settings file for WSO2 ESB. This file is usually named conn.properties and can be found in the <ESB_HOME>/repository/samples/resources/fix directory.

#initial context factory
\#java.naming.factory.initial =org.apache.qpid.jndi.PropertiesFileInitialContextFactory
# register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.qpidConnectionfactory=amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
# Register an AMQP destination in JNDI
# destination.[jndiName] = [BindingURL]
destination.directQueue=direct://amq.direct//QpidStockQuoteService

Configure WSO2 ESB for TCP Transport

To enable the TCP transport for samples, open the <ESB_HOME>/repository/conf/axis2/axis2.xml file in a text editor and add the following transport receiver configuration and sender configuration.

<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportListener">
    <parameter name="transport.tcp.port">6060</parameter>
</transportReceiver>

<transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/>

If you wish to use the sample Axis2 client to send TCP messages, you have to uncomment the TCP transport sender configuration in the <ESB_HOME>/samples/axis2Client/client_repo/conf/axis2.xml file.

Configure WSO2 ESB for UDP Transport

To enable the UDP transport for samples, open the file <ESB_HOME>/repository/conf/axis2/axis2.xml in a text editor and add the following transport configurations.

<transportReceiver name="udp" class="org.apache.axis2.transport.udp.UDPListener"/>
<transportSender name="udp" class="org.apache.axis2.transport.udp.UDPSender"/>

If you want to use the sample Axis2 client to send UDP messages, add the UDP transport sender configuration in the <ESB_HOME>/ samples/axis2Client/client_repo/conf/axis2.xml file as well.

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.

JavaScript Support

The JavaScript/E4X support is enabled by default and comes ready-to-use with the WSO2 ESB distribution.

Ruby Support

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 <ESB_HOME>/repository/components/dropins directory.

Setting up the databases

To run the samples that involve database integration, you need to setup the databases, sample tables and reusable data sources as required by the samples. Most samples require a remote Derby database, whereas a few samples require a MySQL database.

Setting up with Apache Derby

For instructions on installing and configuring the remote Derby database, see Setting up the remote Derby database.

When the database is installed and configured, you can create the sample tables and insert sample data into the tables.

To create a new table in the database

• Execute the following statement.

  CREATE table company(name varchar(10) primary key, id varchar(10), price double);

To insert sample data into the table

• Execute the following statement.

  INSERT into company values ('IBM','c1',0.0);
  INSERT into company values ('SUN','c2',0.0);
  INSERT into company values ('MSFT','c3',0.0);

Setting up with MySQL 

For instructions on installing and configuring the MySQL database, see Setting up the MySQL database.

When the database is installed and configured, you can create the sample tables, insert sample data into the tables and create the two stored procedures. 

To create a new table in the database

• Execute the following statement.

  CREATE table company(name varchar(10) primary key, id varchar(10), price double);

To insert sample data into the table

• Execute the following statements.

  INSERT into company values ('IBM','c1',0.0);
  INSERT into company values ('SUN','c2',0.0);
  INSERT into company values ('MSFT','c3',0.0);

To create the stored procedures

• Execute the following statements.

  CREATE PROCEDURE getCompany(compName VARCHAR(10)) SELECT name, id, price FROM company WHERE name = compName;
  CREATE PROCEDURE updateCompany(compPrice DOUBLE,compName VARCHAR(10)) UPDATE company SET price = compPrice WHERE name = compName;

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 BasicDataSource and 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/lookupdb, 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

datasources.properties configuration

\###############################################################################
# DataSources Configuration
\###############################################################################
synapse.datasources=lookupds,reportds
synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory
synapse.datasources.providerPort=2199
# If following property is present , then assumes that there is an external JNDI provider and will not start a RMI registry
\#synapse.datasources.providerUrl=rmi://localhost:2199

synapse.datasources.lookupds.registry=Memory
synapse.datasources.lookupds.type=BasicDataSource
synapse.datasources.lookupds.driverClassName=org.apache.derby.jdbc.ClientDriver
synapse.datasources.lookupds.url=jdbc:derby://localhost:1527/lookupdb;create=false
# Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider
synapse.datasources.lookupds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler
synapse.datasources.lookupds.username=esb
# Depending on the password provider used, you may have to use an encrypted password here\!
synapse.datasources.lookupds.password=esb
synapse.datasources.lookupds.dsName=lookupdb
synapse.datasources.lookupds.maxActive=100
synapse.datasources.lookupds.maxIdle=20
synapse.datasources.lookupds.maxWait=10000

synapse.datasources.reportds.registry=JNDI
synapse.datasources.reportds.type=PerUserPoolDataSource
synapse.datasources.reportds.cpdsadapter.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
synapse.datasources.reportds.cpdsadapter.className=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
synapse.datasources.reportds.cpdsadapter.name=cpds
synapse.datasources.reportds.dsName=reportdb
synapse.datasources.reportds.driverClassName=org.apache.derby.jdbc.ClientDriver
synapse.datasources.reportds.url=jdbc:derby://localhost:1527/reportdb;create=false
# Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider
synapse.datasources.reportds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler
synapse.datasources.reportds.username=esb
# Depending on the password provider used, you may have to use an encrypted password here\!
synapse.datasources.reportds.password=esb
synapse.datasources.reportds.maxActive=100
synapse.datasources.reportds.maxIdle=20
synapse.datasources.reportds.maxWait=10000

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:

• org.apache.synapse.commons.security.secret.SecretCallbackHandler.

For run this sample, you just need to uncomment secret-conf.properties, cipher-text.properties and datasources.properties. Those files are in conf directory.