Setting Up the ESB Samples

This section describes the prerequisites and instructions on how to start WSO2 Enterprise Integrator with the service bus sample configurations, how to start the Axis2 server and deploy the sample back-end services to the Axis2 server, as well as how to set up any listeners and transports that are required by the service bus samples.

Note that WSO2 EI is shipped with the following changes to what is mentioned in this documentation:

<PRODUCT_HOME>/repository/samples/ directory that includes all Integration profile samples is changed to <EI_HOME>/samples/service-bus/.
<PRODUCT_HOME>/repository/samples/resources/ directory that includes all artifacts related to the Integration profile samples is changed to <EI_HOME>/samples/service-bus/resources/.

Once you have set up the service bus samples, you can run them using the sample clients.

Prerequisites

Ensure that you have the following in your environment:
- Oracle JDK 1.7.*/1.8.*.
- JAVA_HOME environment variable is set to <JDK_HOME>.
- Apache Ant 1.7.0 or above.
- ActiveMQ or any other JMS provider to run the JMS samples.
Open a command prompt (or a shell in Linux) and go to the bin directory of the distribution. Then run the ant command to build the build.xml file.
Run WSO2 Enterprise Integrator in the DEBUG mode. To switch from the default INFO log messages to DEBUG log messages, edit the <EI_HOME>/conf/log4j.properties file and change the line log4j.category.org.apache.synapse=INFO to log4j.category.org.apache.synapse=DEBUG.

Understanding the service bus samples

The service bus samples use several sample clients, configurations and sample back-end services in order to explain different use cases. The diagram below depicts the interaction between the sample clients, WSO2 Enterprise Integrator and the 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, or WS-Security. They can send binary optimized content using MTOM, SwA, binary or plain text JMS messages. After mediation through WSO2 Enterprise Integrator, the requests are passed over to sample services.

Deploying sample back-end services

The sample back-end services come with a pre-configured Axis2 server. These sample services demonstrate in-only and in-out SOAP/REST or POX messaging over HTTP/HTTPS and JMS transports, using WS-Addressing and WS-Security. The samples handle binary content using MTOM and SwA.

Each back-end sample service can be found in a separate folder in the <EI_HOME>/samples/axis2Server/src directory. You need to compile, build and deploy each back-end service to the Axis2 server.

To build and deploy a back-end service

Open a command prompt (or a shell in Linux) and go to the required sample folder in the <EI_HOME>/samples/axis2Server/src directory.

Run ant from the selected sample directory.

For example, to build and deploy SimpleStockQuoteService, run the ant command from the <EI_HOME>/samples/axis2Server/src/SimpleStockQuoteService directory, as follows:

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

BUILD SUCCESSFUL
Total time: 1 second

Next, you need to start the Axis2 server.

Sample back-end services explained

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 a 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.
SecureStockQuoteService
This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled as well as an attached security policy for signing and encrypting messages.
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.

Starting the Axis2 server

For the samples, a standalone Apache Axis2 Web services engine is used as the back-end server, which is bundled with the WSO2 Enterprise Integrator distribution by default.

Once each back-end service is deployed to the Axis2 server, you need to start the Axis2 server before executing the sample client.

To start the Axis2 server

Open a command prompt (or a shell in Linux) and go to the <EI_HOME>/samples/axis2Server directory.
Execute one of the following commands
- On Windows: axis2server.bat
- On Linux/Solaris: ./axis2server.sh

This starts the Axis2 server with the HTTP transport listener on port 9000 and HTTPS on port 9002 respectively.

If you want to start multiple instances of the Axis2 server on different ports, run the following commands. 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

Running the commands as specified above will start three instances of the Axis2 server on HTTP ports 9001, 9002 and 9003 respectively.

Configuring WSO2 Enterprise Integrator to use the JMS transport

If you need to run the JMS samples, configure the JMS transport of WSO2 Enterprise Integrator with ActiveMQ 5.5.0 or higher.

To enable the JMS transport of WSO2 Enterprise Integrator, edit the <EI_HOME>/conf/axis2/axis2.xml file and uncomment the JMS transport listener configuration as follows:

<!--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 name="transport.jms.ConnectionFactoryType" locked="false">topic</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 name="transport.jms.ConnectionFactoryType" locked="false">queue</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 name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter>
       </parameter>
   </transportReceiver>

Note

If you are using a JMS provider other than ActiveMQ, this configuration should be updated to reflect your environment.

To enable JMS support for the sample Axis2 server, edit the <EI_HOME>/samples/axis2Server/repository/conf/axis2.xml file and uncomment the JMS transport listener configuration.

Configuring WSO2 Enterprise Integrator to use the mail transport

To enable the mail transport sender for the samples

Edit the <EI_HOME>/conf/axis2/axis2.xml file and uncomment the mail transport sender configuration. Also, be sure that it points to a valid SMTP configuration for an actual scenario.

<transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender">
    <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
    <parameter name="mail.smtp.port">587</parameter>
    <parameter name="mail.smtp.starttls.enable">true</parameter>
    <parameter name="mail.smtp.auth">true</parameter>
    <parameter name="mail.smtp.user">synapse.demo.0</parameter>
    <parameter name="mail.smtp.password">mailpassword</parameter>
    <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
</transportSender>

To enable the mail transport receiver for the samples

Edit the <EI_HOME>/conf/axis2/axis2.xml file and uncomment the mail transport receiver configuration.

<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.MailTransportListener">
</transportReceiver>

You need to provide correct parameters for a valid mail account at the service level.

Configuring WSO2 Enterprise Integrator to use the NHTTP transport

WSO2 Enterprise Integrator uses the HTTP PassThrough Transport (PTT) as the default HTTP transport. Therefore, the default axis2.xml file in <EI_HOME>/conf/axis2 is PassThrough Transport enabled.

To run some of the samples, you need to configure WSO2 Enterprise Integrator to use the NHTTP transport as the default transport.

To enable the NHTTP transport

Rename the axis2.xml file in the <EI_HOME>/conf/axis2 directory to default_axis2.xml.
Rename the axis2_nhttp.xml file in the <EI_HOME>/conf/axis2 directory to axis2.xml.
Restart WSO2 Enterprise Integrator.

Configuring WSO2 Enterprise Integrator to use the FIX transport

To run the FIX samples, you need to have a local Quickfix/J installation.

For information on downloading the latest version of Quickfix/J, go to Quickfix/J Downloads.
For instructions on installing QuickFIX, go to Quickfix/J User Manual.

To enable the FIX transport sender and receiver

Edit the <EI_HOME>/conf/axis2/axis2.xml file and uncomment the FIX transport sender and FIX transport receiver configurations.

Configuring WSO2 Enterprise Integrator for FIX samples

In order to configure WSO2 Enterprise Integrator to run the FIX samples, you need to create the FIX configuration files.

You can find the config files in <EI_HOME>/samples/service-bus/resources/fix folder.

To create the FIX configuration files

Add the following entries in a file named fix-synapse.cfg

[default]
FileStorePath=repository/logs/fix/store
FileLogPath=repository/logs/fix/log
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

Add the following entries in a file named synapse-sender.cfg

[default]
FileStorePath=repository/logs/fix/data
FileLogPath=repository/logs/fix/log
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

The FileStorePath property in the fix-synapse.cfg file and synapse-sender.cfg file should point to two different directories in your local file system. Once the samples are executed, Synapse will create FIX message stores in these two directories.

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.

To configure sample FIX applications

Either modify the quickfixj-examples.jar file or pass the new configuration file as a command line parameter.
To modify the quickfixj-examples.jar file:
- Extract the JAR file, modify the configuration files and pack them to a JAR file with the same name again.
To pass the new configuration file as a command line parameter:
- Copy the config files from the <EI_HOME>/samples/service-bus/resources/fix directory to the <QFJ_HOME>/etc directory. Then 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 two files above should point to two different directories in your local file system. The launcher scripts for the sample application can be found in the bin directory of the Quickfix/J distribution.

For more information regarding the FIX sample applications, see http://www.quickfixj.org/quickfixj/usermanual/1.5.0/usage/examples.html

For more information on configuring Quickfix/J applications, see http://www.quickfixj.org/quickfixj/usermanual/1.5.0/usage/configuration.html

Configuring WSO2 Enterprise Integrator to use the AMQP transport

To configure WSO2 Enterprise Integrator to use the AMQP transport, you need to have QPid version 1.0-M2 or above installed and started. You also need to copy the following client JAR files into the <EI_HOME>/lib directory to support AMQP. These files can be 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 transport over the JMS transport

Uncomment the JMS transport listener configuration.
To enable AMQP over JMS for WSO2 Enterprise Integrator:
- Edit the <EI_HOME>/conf/axis2/axis2.xml file and uncomment the JMS transport listener configuration.
To enable JMS support for the sample Axis2 server:
- Edit the <EI_HOME>/samples/axis2Server/repository/conf/axis2.xml file and uncomment the JMS transport listener configuration.

Locate and edit the AMQP connection settings file for the message consumer. This file is named direct.properties and can be found in the <EI_HOME>/samples/service-bus/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 Enterprise Integrator. This file is named conn.properties and can be found in the <EI_HOME>/samples/service-bus/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

Configuring WSO2 Enterprise Integrator to use the TCP transport

To enable the TCP transport for samples

Edit the <EI_HOME>/conf/axis2/axis2.xml file and add the transport receiver configuration as well as the sender configuration as follows:

<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 want to use the sample Axis2 client to send TCP messages, you have to uncomment the TCP transport sender configuration in the <EI_HOME>/samples/axis2Client/client_repo/conf/axis2.xml file.

Configuring WSO2 Enterprise Integrator to use the UDP transport

To enable the UDP transport for samples

Edit the <EI_HOME>/conf/axis2/axis2.xml file and add the transport configuration as follows:

<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, edit the <EI_HOME>/ samples/axis2Client/client_repo/conf/axis2.xml file and add the UDP transport sender configuration.

Configuring WSO2 Enterprise Integrator for script mediator support

The Script mediator is a Synapse extension. Therefore, pre-requisites for all BSF supported scripting languages may not be bundled by default with the WSO2 Enterprise Integrator distribution. Before you use some of the script mediators, you need to manually add the required JAR files to the <EI_HOME>/dropins directory, and optionally perform other installation tasks as required by the individual scripting language. The following section describes this in detail.

JavaScript support

The JavaScript/E4X support is enabled by default in the WSO2 Enterprise Integrator distribution, and ready for use.

Groovy support

Download the groovy-all-2.4.4.jar file and copy it to the <EI_HOME>/dropins directory.

Ruby support

Install the JRuby engine for mediation. This is available in the WSO2 P2 repository as a feature (WSO2 Carbon - JRuby Engine for Mediation). See the instructions on how to install features in WSO2 EI.

Alternatively, you can download and install the JRuby engine manually: Download the jruby-complete-1.3.0.wso2v1.jar file from the WSO2 P2 repository and copy it to the <EI_HOME>/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

Download Apache Derby.
Install Apache Derby on your computer.

For instructions on installing Apache Derby, see the Apache Derby documentation.
Go to the <DERBY_HOME>/bin/ directory and run the Derby network server start script. Usually it is named startNetworkServer.

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

Download and install MySQL on your computer.

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 a reusable database connection pool or datasources can be done using the datasources.properties file. It is possible to configure any number of datasources. Currently only two types of datasources are supported and those are based on the Apache DBCP datasources. The two types are BasicDataSource and PerUserPoolDataSource (based on Apache DBCP). The following configuration includes both definitions.

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

The configuration is similar to the log4j appender configuration.

It requires two databases, follow the steps in the section above to create the two databases jdbc:derby://localhost:1527/lookupdb and jdbc:derby://localhost:1527/reportdb using the user name and password as esb. Fill in the data for the two databases as described in the section above.

To secure data sources password, you should use the mechanism for securing secret Information. If that mechanism is used, the 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.

WSO2 Enterprise Integrator 6.5.0

Setting Up the ESB Samples

Prerequisites

Understanding the service bus samples

Deploying sample back-end services

Sample back-end services explained

`SimpleStockQuoteService`

`SecureStockQuoteService`

`MTOMSwASampleService`

Starting the Axis2 server

Configuring WSO2 Enterprise Integrator to use the JMS transport

Configuring WSO2 Enterprise Integrator to use the mail transport

Configuring WSO2 Enterprise Integrator to use the NHTTP transport

Configuring WSO2 Enterprise Integrator to use the FIX transport

Configuring WSO2 Enterprise Integrator for FIX samples

Configuring sample FIX applications

Configuring WSO2 Enterprise Integrator to use the AMQP transport

Configuring WSO2 Enterprise Integrator to use the TCP transport

Configuring WSO2 Enterprise Integrator to use the UDP transport

Configuring WSO2 Enterprise Integrator for script mediator support

JavaScript support

Groovy support

Ruby support

Setting up the databases

Setting up with Apache Derby

Setting up with MySQL

Setting up Synapse DataSources