Deploying WSO2 ESB 2.0 on Apache Tomcat

As you all know WSO2 ESB can be deployed on different application servers such as IBM WebSphere, BEA WebLogic Server, JBoss and Apache Tomcat. I have written a blog previously on how one can deploy WSO2 ESB on Apache Tomcat. Unfortunately this does not work with the new Carbon based WSO2 ESB. Therefore for anyone who is interested on deploying WSO2 ESB on Apache Tomcat the following guide will be useful.

Step 1 - Downloading and installing Apache Tomcat

You can download the latest version of Apache Tomcat from here (I will be using Apache Tomcat 5.5.20 to demonstrate this scenario).
Extract the downloaded distribution to a specific location and define the environment variables properly. (Assume you extracted the downloaded Tomcat into the folder C:\apache-tomcat-5.5.20)

E.g.: -
CATALINA_HOME=C:\apache-tomcat-5.5.20

Next you will need to enable HTTPS on Apache Tomcat since WSO2 ESB runs over HTTPS. To do this, access the server.xml file located at %CATALINA_HOME%/conf and uncomment the following.

<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"/>

Then you will need to provide the keystore file location along with it's password as below.

<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile = "C:\Carbon\ESB\tomcat\wso2esb-SNAPSHOT\resources\security\wso2carbon.jks"
keystorePass="wso2carbon">

Step 2 - Downloading and installing WSO2 ESB

Download the latest WSO2 ESB distribution from here and extract to a specific location. (E.g.:- C:\Carbon\ESB\tomcat\wso2esb-SNAPSHOT). From this folder copy the folders,

- conf
- database
- resources
- repository

to a separate folder. (E.g.:- C:\Carbon\ESB\tomcat\esb_home)

Step 3 - Setting environmental variables

You will have to set an environment variable with the name CARBON_HOME pointing it to the directory which you copied the above files to.
E.g.:-
CARBON_HOME=C:\Carbon\ESB\tomcat\esb_home

Step 4 - Copying required files to Apache Tomcat

Now create a folder inside the webapps folder of Tomcat.
E.g.:-
C:\apache-tomcat-5.5.20\webapps\esb

Next, you need to copy the WEB-INF folder, which is in the folder which you extracted the downloaded ESB distribution. Then copy it into the esb folder which you created above.
E.g.:-
Copy
C:\Carbon\ESB\tomcat\wso2esb-SNAPSHOT\webapps\ROOT\WEB-INF
to
C:\WSO2\Installations\apache-tomcat-5.5.20\webapps\esb

Step 5 - Changing necessary files of the WSO2 ESB distribution

a) Open the carbon.xml file which is in the CARBON_HOME\conf folder and specify the following URL as the ServerURL
E.g.:-
https://localhost:8443/esb/services/

b) Next open the axis2.xml which is located inside the CARBON_HOME\conf and change the http port from 8280 to 8080 (the default http port of Tomcat) and the https port from 8243 to 8443.

c) In addition to the above, you need to specify the correct paths for the two .jks files wso2carbon.jks and client-truststore.jks specified in the axis2.xml and also the wso2carbon.jks file specified in the carbon.xml file.

d) Then you need to specify the absolute paths of the WSO2CARBON_DB of the two files registry.xml and user-mgt.xml
E.g.:- Change
jdbc:derby:database/WSO2CARBON_DB;create=true
to
jdbc:derby:C:\Carbon\ESB\tomcat\esb_home\WSO2CARBON_DB;create=true

e) Next you will have to specify the absolute path of the synapse.xml which is in the axis2.xml file located at CARBON_HOME\conf

E.g.:-
Change
conf/synapse.xml
to
C:\Carbon\ESB\tomcat\esb_home\conf\synapse.xml
Step 6 - Starting the Apache Tomcat Server

Now you can start the Apache Tomcat server by giving the following command.
catalina.bat run

Step 7 - Login to the WSO2 ESB Administration Console

Now you should be able to login to the WSO2 ESB Administration Console as, https://localhost:8443/esb/carbon

How to relocate an SVN location

To switch the svn location which you were working, to a new location you can use the following command

svn switch --relocate [old_location] [new_location]

How to invoke a Proxy Service created on WSO2 ESB deployed on IBM Websphere

When you deploy WSO2 ESB on IBM Webphere you will not be able to invoke the created Proxy services or sequences the general way you do it. This requires a new parameter to be given and the ports too should be correctly specified.

Assume that the web context root given when deploying WSO2 ESB is 'esb'. Also if the specified HTTP port of IBM Websphere is 9080, you can invoke a Proxy service which you have created on WSO2 ESB as follows.


ant stockquote -Dtrpurl=http://localhost:<HTTPS_port_of_WAS>/
<web_context_root>/soap/<Proxy_name>

E.g.:- ant stockquote -Dtrpurl=http://localhost:9080/esb/soap/SimpleProxy


Performance testing on a Derby database - JMeter to the rescue

One of my friends had a requirement of doing a performance test on a Derby database and she proposed that it would be easier if we do it through Apache JMeter. This was quite new to me and had to do a lot of Google searches but at the end was able to get it working so thought of sharing it with you all. I assume that you all are familiar with Apache JMeter. I will simply explain the steps along with some screen shots.

Step 1

Download and install Apache JMeter on your local machine and start the jmeter.bat file which is located inside the bin folder. Once you start the bat file you it will open up Apache JMeter as shown on the Figure.



Step 2

Now let us add the things which are required to do our task.
First right click on the 'Test Plan' element and add a Thread Group.
The next thing you need to add is a JDBC configuration element. To do this right click on the 'Thread Group' which you added a while ago and select 'Add -> Config Element -> JDBC Connection Configuration'.
Now you need to fill up the information to depending on the database which you have selected. Let us see what values we need to enter to test a Derby database. The following screen shot will give you a clear idea on this.



Step 3
The next step is to add a 'JDBC Request' element to enter you database query. Assume that you have created a database on your Derby database and that you have a table called 'COMPANY'. Let us see how you can query this database.

Right click on the 'Thread Group' and select 'Add -> Sampler -> JDBC Request'.
Since we are going to do select some data from the database, select the the option 'Select Statement' from the combo box 'Query Type:'.



Step 4
Now you need to find a way to view the performance. In order to do this you can add a listener to view the results. Therefore right click on the 'Thread Group' and select 'Add -> Listener -> Graph Results'



Step 5
Before running the test w need one more step to follow. That is to specify the number of threads. To do this click on the 'Thread Group' and specify 1000 as 'Number of Threads (users):' which is under 'Thread Properties'.

Let us try this out now. From the main menu select 'Run -> Start'. If you are executing the test for the first time it would ask you to save the test plan. Save the test plan at any location you prefer. Once the test has executed, you will see the output as shown in the following graph. You can do your test as you prefer by changing the number of threads.

Developing a Research Thesis

The third semester is about to end of my MBA and it's time to spend some time on the MBA research. Selecting a research topic is difficult. Doing literature review and developing on the thesis is even harder. After a chat which I had with Dr. Sanjiva Weerawarana I decided that I should select a topic which would be useful for WSO2, my organization that I work for as well and therefore thought of touching the area of marketing open-source software. I have no clue on where to start and at the moment am browsing through the web and collecting related magazines, articles which I think might be useful for me.

I wish my father was alive because I'm sure I would have had great support from him since he has done similar kinds of stuff and helped a lot of other people who have done their research projects. He did his PhD on radiochemistry and his research paper is available on the web but unfortunately I cannot access is since I have to pay in order to download it.

I could have got some help from my dear old sister who is a medical doctor at the University of Ragama but alas she too is doing her PhD these days and I don't think I will get any help from her either (She too has written some articles on her research).

So I guess I'm alone on this and will have to do it on my own. Well of course we are expected to do it on our own but it would have been great if I had someone who's close to me who would at least would understand my stress at a time like this. I know that there will be a lot of people at office to help me out but it won't be the same. We will see how it goes. My only hope is to be able to complete it by 2009 and graduate with the rest of the batch. :-)

Creating your own Web Service with different session scopes

When creating a Web service you can create Web services of different session scopes. There are four session types in Axis2 such as,
1. SOAP Session Scope
2. Transport Session Scope
3. Request Scope
4. Application Session Scope

I will briefly explain how one can create Web service with each of these different session scopes.

Once you have created your Java class and complied it, you will need to write a services.xml before converting it into an archive file.

In order to create a service with a SOAP session scope all you have to do is add the following to your services.xml

scope="soapsession"

E.g.:- <service name="<service_name>" scope="soapsession">



I will be providing a sample service.xml for your reference.

<service name="Adding" scope="soapsession">
<description>
This service is created to add two numbers.
</description>
<parameter name="ServiceClass" locked="false">com.math.add.Adding</parameter>
<operation name="add">
<messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
</operation>
</service>


Creating your own 'Mediator'

Recently I was asked by Ruwan to verify an issue reported by some customer. In order to test the issue, I had to write a new mediator. Since I'm not much familiar with writing these sort of stuff, I was struggling hard to get it working and in the end Ruwan helped me out to write a simple mediator and also taught me how to test it with WSO2 ESB. I will briefly describe how this can be done easily.

Pre-requisites - You need to download and install the latest version of WSO2 ESB on your local machine. (Assume that you have downloaded the WSO2 ESB instance to C:\wso2esb-1.7. I will be referring to this folder as ESB_HOME from this point onwards)

Step 1 - Create a mediator class

As the initial step I wrote a small java class which extends the method AbstractMediator as below.

package org.wso2.esb.client;

import org.apache.axiom.soap.SOAPFault;
import org.apache.synapse.MessageContext;
import org.apache.synapse.mediators.AbstractMediator;

public class TestMediator extends AbstractMediator{

public boolean mediate(MessageContext synCtx) {
SOAPFault fault = synCtx.getEnvelope().getBody().getFault();
System.out.println(fault.getCode().getText());
System.out.println(fault.getReason().getText());
return false;
}
}



Assume that you have your compiled java class at C:\ESB\mediator\testMediator\org\wso2\esb\client\TestMediator.class

Step 2 - Creating the JAR file

After compiling the class, I created a JAR file using the compiled class.

Open a new command prompt and go to the folder which you have the compiled package (E.g.:- C:\ESB\mediator\testMediator) and type the following command

jar cf testMediator.jar org



Once you type this command it would create the JAR file testMediator.jar at the current location (E.g.:- C:\ESB\mediator\testMediator )

Step 3 - Creating the synapse configuration

In order to test the newly created mediator you can use a simple configuration as below. You can call the mediator which you created using a class mediator ( E.g.:- <class name="org.wso2.esb.client.TestMediator"/> ).


<definitions xmlns="http://ws.apache.org/ns/synapse">
<registry provider="org.wso2.esb.registry.ESBRegistry">
<parameter name="root">file:registry/</parameter>
<parameter name="cachableDuration">15000</parameter>
</registry>
<sequence name="main">
<sequence key="sampleSequence"/>
</sequence>
<sequence name="fault">
<log level="full">
<property name="MESSAGE" value="Executing default "fault" sequence"/>
<property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
<property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
</log>
<drop/>
</sequence>
<sequence name="sampleSequence" onError="soap11_fault">
<in>
<send>
<endpoint>
<address format="soap11" uri="http://localhost:9000/soap/Adding1"/>
</endpoint>
</send>
</in>
<out>
<class name="org.wso2.esb.client.TestMediator"/>
<log level="full"/>
<class name="org.wso2.esb.client.TestMediator"/>
<send/>
</out>
</sequence>
<sequence name="soap11_fault">
<log level="full" separator=","/>
<makefault version="soap11">
<code xmlns:sf11="http://schemas.xmlsoap.org/soap/encoding/" value="sf11:VersionMismatch"/>
<reason value="Exception occurred when transforming the request/response"/>
</makefault>
<log level="full"/>
<header name="To" action="remove"/>
<property name="RESPONSE" value="true"/>
</sequence>
</definitions>




Step 4 - Starting the WSO2 ESB server with the created configuration

Copy this configuration to the ESB_HOME\webapp\WEB-INF\classes\conf and start the WSO2 ESB server. To do this, go to ESB_HOME\bin and run the command wso2-esb.bat

Step 5 - Creating the client to invoke the service

Assume that you have created a service (For you reference I will be attaching the service Adding1.aar which I have created) and deploy it in ESB_HOME\samples\axis2Server\repository\services. Go to the folder ESB_HOME\samples\axis2Server and start the SimpleAxis2Server by executing the executable bat file 'axis2server.bat'.

Now create a client as below and invoke the service deployed through WSO2 ESB.

package org.wso2.esb.client;

import org.apache.axiom.om.OMAbstractFactory;
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMFactory;
import org.apache.axiom.om.OMNamespace;
import org.apache.axis2.AxisFault;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;

public class AxiomClient {
public static void main(String[] args)throws AxisFault{
Options options = new Options();
options.setTo(new EndpointReference("http://localhost:8280/soap"));
options.setAction("urn:add");
ServiceClient sender = new ServiceClient();
sender.setOptions(options);
OMElement result = sender.sendReceive(getPayload());
System.out.println(result);
}

private static OMElement getPayload() {
OMFactory fac = OMAbstractFactory.getOMFactory();
OMNamespace omNs = fac.createOMNamespace("http://service.esb.wso2.org", "ns");
OMElement method = fac.createOMElement("add", omNs);
OMElement value1 = fac.createOMElement("x", omNs);
OMElement value2 = fac.createOMElement("y", omNs);
value1.addChild(fac.createOMText(value1, "10"));
value2.addChild(fac.createOMText(value2, "10"));
method.addChild(value1);
method.addChild(value2);
return method;
}
}



Step 6 - Verifying through viewing the logs

Once you invoke the client, the logs displayed on the WSO2 ESB console will show how the class mediator has been invoked

[HttpClientWorker-1] DEBUG InMediator Start : In mediator
[HttpClientWorker-1] DEBUG InMediator Current message is a response - skipping child mediators
[HttpClientWorker-1] DEBUG InMediator End : In mediator
[HttpClientWorker-1] DEBUG OutMediator Start : Out mediator
[HttpClientWorker-1] DEBUG OutMediator Current message is outgoing - executing child mediators
[HttpClientWorker-1] DEBUG OutMediator Sequence <OutMediator> :: mediate()
[HttpClientWorker-1] DEBUG ClassMediator Start : Class mediator
[HttpClientWorker-1] DEBUG ClassMediator invoking : class org.wso2.esb.client.TestMediator.mediate()
axis2ns8:Client
The service cannot be found for the endpoint reference (EPR) http://localhost:9000/soap/Adding1
[HttpClientWorker-1] DEBUG ClassMediator End : Class mediator
[HttpClientWorker-1] DEBUG OutMediator End : Out mediator



As you can see only the Class mediator is invoked and non of the mediators specified after wards are not invoked. The reason for this is that when creating the mediator, you have set 'return' to false. Therefore when the Class mediator is invoked none of the mediators available after that Class mediator will not be invoked. If you need to invoke the other mediators that are available after the Class mediator, you have to set 'return' to true. Try this out by yourself. Once you execute the client, it should invoke the Class mediator first and the the Log mediator and after that the rest of the mediators specified.