How to deploy WSO2 ESB-3.X on Apache Tomcat

WSO2 DOES NOT ENCOURAGE INSTALLING WSO2 ESB ON TOP OF OTHER APPLICATION SERVERS. WSO2 HAS DECIDED TO DROP SUPPORT FOR WEBAPP DEPLOYMENT MODE OF THE WSO2 PLATFORM AND PRODUCTS.

I have noticed a lot of different articles, blog posts with instructions on deploying WSO2 ESB on Apache tomcat. But I observed that most of them are obsolete and the guidelines are not applicable for the latest ESB versions. Therefore, I thought to put together the steps of setting up WSO2 ESB-3.X versions on Apache Tomcat-6.X

Step 1:

Download WSO2 ESB-3.X. Extract the downloaded zip and copy repository and resources directories in to a new folder. Say it is esb-repo (i.e:- /home/user/esb-repo)

Step 2:

Lets refer to your tomcat installation directory, CATALINA_HOME. Go to CATALINA_HOME\webapps directory and create a new directory, esb.

Now, copy wso2esb-3.0.0\webapps\ROOT\WEB-INF to CATALINA_HOME\webapps\esb

Also, copy wso2esb-3.0.0\lib\log4.properties file to CATALINA_HOME\webapps\esb\WEB-INF\classes

Step 3:

Next, we need to enable https in tomcat. Therefore, edit CATALINA_HOME\conf\server.xml by adding the following entry.

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

enableLookups="false" disableUploadTimeout="true"

acceptCount="100" scheme="https" secure="true" SSLEnabled="true"

clientAuth="false" sslProtocol="TLS"

keystoreFile = "/home/user/esb-repo/resources/security/wso2carbon.jks"

keystorePass="wso2carbon"/>

Make sure to give the exact location of wso2carbon.jks as highlighted above.

Step 4

We have done the configurations required in tomcat. Now, we must do the necessary configurations in a set of config files shipped with WSO2 ESB. We will update carbon.xml, axis2.xml, registry.xml and user-mgt.xml which can be found at esb-repo/repository/conf directory.

First, open carbon.xml and update the ServerURL element as follows.

<ServerURL>https://localhost:8443/esb/services/</ServerURL>

Note that we have configured tomcat to run on 8443 port.

When we deploy ESB on an application server, it uses the http/https transport provided by the servlet container when communicating with registry. Therefore, we must update the registry HTTP port in carbon.xml. In order to do that, uncomment and update the following element in carbon.xml.

<RegistryHttpPort>8080</RegistryHttpPort>

Thats all we need to update in carbon.xml, save and close the file.

Next, open registry.xml and update DB URL as follows.

<url>jdbc:h2:/home/user/esb-repo/repository/database/WSO2CARBON_DB</url>

Now, open user-mgt.xml and update user management database URL as follows.

<Property name='url'>jdbc:h2:/home/user/esb-repo/repository/database/WSO2CARBON_DB</Property>

Make sure to specify the absolute path of the WSO2CARBON_DB in both of the above elements.

Next, we need to configure a few elements in esb-repo/repository/conf/axis2.xml file.

Locate NIO HTTPS transport listener (HttpCoreNIOSSLListener) element and specify the absolute path of keystore and truststore locations as follows.

<KeyStore>

<Location>/home/user/esb-repo/resources/security/wso2carbon.jks</Location>

<TrustStore>

<Location>/home/user/esb-repo/resources/security/client-truststore.jks</Location>

Similarly update the keystore and trustore paths of NIO HTTPS transport sender (HttpCoreNIOSSLSender)

We should also specify the absolute path of synapse-config directory as follows.

<parameter name='SynapseConfig.ConfigurationFile' locked='false'>/home/charitha/products/esb/esb-repo/repository/conf/synapse-config</parameter>

Step 5

We have almost completed the required configurations. Now, open a new shell and change the directory to CATALINA_HOME/bin.

Define an environment variable called CARBON_HOME and set the path to your esb-repo directory.

In windows; set CARBON_HOME=C:\esbs\esb-repo

In linux; export CARBON_HOME=\home\user\esb-repo

Start tomcat from the same command window/shell.

catalina.sh run

WSO2 ESB will be started successfully. You can access the management console using https:\\localhost:8443\esb\carbon

Thats all! You could follow the above steps and deploy WSO2 ESB-3.X on Tomcat successfully. If you do not like to follow each of the above steps manually, I have written a ruby script to automate the above procedure and install ESB on tomcat. You can download it from here

You just need to specify three directory paths there in esb3.X_tomcat_install_linux.rb and rest of the installation steps will be done automatically by the script.

esb_repo = Any directory in the local file system

CARBON_BIN_HOME= Home directory of ESB binary distribution

CATALINA_HOME= Home directory of the tomcat binary

Message format transformations with WSO2 ESB

With WSO2 ESB, you can easily convert the format of the messages which passes through. There are situations in which you get SOAP requests but the back end server accepts XML. In these situations, you should convert the SOAP request to XML (POX) before forwarding to the endpoint. This post explains how you can change the format of a SOAP request goes through WSO2 ESB.

Pre-requisites:

Download and install WSO2 ESB-3.X

Step 1

I use WSO2 WSAS as the backend, but you could use any server as you preferred. Start WSO2 WSAS and deploy Axis2Service

Step 2

Start WSO2 ESB and add the following configuration. Here, we specify the message format as POX in the endpoint configuration since we need to convert SOAP message to XML when forwarding it to the endpoint.

<sequence xmlns="http://ws.apache.org/ns/synapse" name="main">

<in>

<send>

<endpoint name="axis2service-epr">

<address uri="http://localhost:9763/services/Axis2Service" format="pox" />

</endpoint>

</send>

<</in>

<out>

<send />

</out>

</sequence>

Step 3

Send a SOAP1.1 message using a tool (SOAPUI, Jmeter, AB etc). If you look at the message transmission between ESB and the endpoint, you will notice the following messages

Request SOAP message:

POST / HTTP/1.1

SOAPAction: urn:echoString

Content-Length: 307

Content-Type: text/xml; charset=UTF-8

Host: 127.0.0.1:8281

Connection: Keep-Alive

User-Agent: Jakarta-HttpComponents-Bench/1.1

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.carbon.wso2.org">

<soapenv:Body>

<ser:echoString>

<ser:s>test</ser:s>

</ser:echoString>

</soapenv:Body> </soapenv:Envelope>

Message delivered to the endpoint:

POST /services/Axis2Service HTTP/1.1

Content-Type: application/xml; charset=UTF-8

SOAPAction: urn:echoString

Transfer-Encoding: chunked

Host: 127.0.0.1:9765

Connection: Keep-Alive

User-Agent: Synapse-HttpComponents-NIO

86

<ser:echoString xmlns:ser="http://service.carbon.wso2.org">

<ser:s>test</ser:s> </ser:echoString>0

Similarly, you can convert the message to SOAP1.2 or HTTP GET just by specifying the endpoint format.

How to use POST_TO_URI property in WSO2 ESB

Until recently I had some doubts about using POST_TO_URI property within WSO2 ESB configuration. Finally, I think I understood the true purpose of it and used it correctly.

According to WSO2 ESB parameters catelog, POST_TO_URI property makes the outgoing URL of the ESB a complete URL and it is important when sending the messages through a proxy server.
Lets see how this property can be used in message mediation when a HTTP proxy server is used.

Step 1

As I explained in a previous post, you are supposed to configure WSO2 ESB to forward messages through a HTTP proxy server.

Step 2

Now, add the following sequence (or any message pass through sequence). (I used a service called "Axis2Sesrvice" which is deployed on WSO2 WSAS as the endpoint and I used Apache server as the proxy)

<sequence xmlns="http://ws.apache.org/ns/synapse" name="main">
<in>
<send>
<endpoint name="endpoint_urn_uuid_1286CEB97BC8A170468445150995919829308689">
<address uri="http://localhost:9764/services/Axis2Service/" />
</endpoint>
</send>
</in>
<out>
<send />
</out>
</sequence>

Step 3

Send a message to ESB using a client. You will notice that the message transmission is failed. If you look at the apache server log, you will notice something similar to the below.

127.0.0.1 - - [19/Jul/2010:14:19:30 +0530] "POST /services/Axis2Service/ HTTP/1.1" 404 220

Here, you can see that, POST message does not contain the full service URL hence the proxy server is unable to forward the message to the endpoint.

Step 4

Now update the above sequence with including POST_TO_URI property as follows.

<sequence xmlns="http://ws.apache.org/ns/synapse" name="main">
<in>
<property name="POST_TO_URI" value="true" scope="axis2" type="STRING" />
<send>
<endpoint name="endpoint_urn_uuid_1286CEB97BC8A170468445150995919829308689">
<address uri="http://localhost:9764/services/Axis2Service/" />
</endpoint>
</send>
</in>
<out>
<send />
</out>
</sequence>

Send a message again. This time, the message transmission will be successful. You will find the following entry in apache log. This proves that the message is correctly forwarded to the endpoint through the proxy server.

127.0.0.1 - - [19/Jul/2010:14:57:25 +0530] "POST http://localhost:9764/services/Axis2Service/ HTTP/1.1" 200 278

How to configure WSO2 ESB to route messages through a proxy server

When using WSO2 ESB, there are situations in which you need to talk to an endpoint which sits behind a proxy. In such cases, you should configure the ESB transport sender to forward the messages to the proxy server.
In order to do so, you just need to add the following two parameters as child elements of <transportSender name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSender">

<parameter name="http.proxyHost" locked="false">localhost</parameter>
<parameter name="http.proxyPort" locked="false">8090</parameter>

Note:- Change the proxy port and host according to your environment

WSO2 Stratos - Introducing WSO2 middleware Platform as a Service (PaaS)

Yesterday we released our newest integrated cloud middleware platform, WSO2 Stratos. It is now online and ready for use!

For the past few years, WSO2 has been doing many releases based on revolutionary Carbon platform, which helped to consistently improve the platform with introducing latest state-of-art technologies. The initial releases of Carbon product platform intended to improve the features of the individual products. For example, a lot of core features were introduced to WSO2 ESB, WSAS, Governance Registry etc.. Then we focused on ease of integration and more component based model. We introduced Equinox based provisioning model to build your SOA platform by picking and choosing the components as and when you need.
Then, the core product platform has been enhanced to support multi-tenancy. With the multi-tenant supported architecture at hand, our brilliant development team was able to introduce the first ever comprehensive middleware PaaS. Why is this so important?
Now, WSO2 Carbon middleware platform is available on Cloud. Anybody can try out it online by accessing http://cloud.wso2.com
Not only that, the code is 100% opensource! As far as I know, this is the first ever opensource cloud PaaS offering.

Without digging in to more details, lets try WSO2 Stratos out.

Step 1

As most of you are familiar with Google Apps, without any guidance you will be able to start using WSO2 Stratos. However, I will start from the scratch. Access http://cloud.wso2.com. This will bring up WSO2 Stratos Manager, which is the is the point of entry for all WSO2 Cloud Services such as Application Server, Business Activity Monitor, Gadget Server, Governance, Identity and Mashup Server. Click on "Register" in order to create an account for you (your organization).



This will direct you to "Select a domain for your organization" page. Specify the domain for your organization and check its availability by clicking on "Check Availability". Select "Next" to sign up your organization.



Enter the required information in "sign up your organization" page. If your registration is successful, you will see a confirmation message. With this, you just created the administration account for your organization. You will receive an email to validate Email instructions specified by you. Click on the link given in the email to access the Stratos Manager login page.
Now, you can log in to the Stratos Manager, by giving the admin credentials you have just specified during the registration process.

Step 2

After log in to Stratos Manager, you will see the cloud services list offered by WSO2 Cloud service platform.



In addition to the cloud services, you can configure a new theme for your account or you can manage new user accounts (add new users, grant necessary permissions to them etc..) through the Stratos Manager.

Suppose, you need to use cloud application server out of the seven cloud services enabled by default. Click on "Cloud Application Server" link. This will bring up "WSO2 Stratos Application Server" login page as follows.



Log in to app server by providing the same admin credentials given above. (You may question why a separate login is required. We have not provided Single Sign On support between Stratos Manager and Cloud services in the alpha1 version. This will be available soon)
The Cloud application server Home page will be shown as follows after you log in to the application server.



If you are already familiar with WSO2 WSAS, this will not make you feel strange. You could either deploy services, secure them, monitor and do a lot of tasks. In addition to that, WSO2 Cloud Application Server, is now provides with web application deployment support. You could use this as your servlet container!

Similarly, you can try out the rest of the cloud services.

How to specify a custom scope for WS-Discovery target service

As I explained in a previous blog post, WS-Discovery support is included in the latest WSO2 carbon release (3.0.0).
WSO2 WSAS can be considered as a target service hosting provider. A default scope is assigned to all the target services discovered by a Discovery Proxy.
If a discovery client looks for a service based on the service type, or some scopes, the client sends probe message to the DiscoveryProxy. Then the proxy responds back to the client with the appropriate service metadata.
Suppose we need to specify a scope for the services deployed on WSAS (target services). How can we do that?

You can specify the service scope(s), by adding a parameter in the services.xml of the Axis2 Service archive (*.aar) as follows.

<parameter name="wsDiscoveryParams">
<Scopes>http://wso2.org/engineering</Scopes>
</parameter>

Then, you can probe the services either through WS-Discovery Control Panel in WSO2 ESB management console as shown here or using WS-Discovery Client API as follows.

DiscoveryClient client = new DiscoveryClient(cfgCtx, discoveryProxyURL);
TargetService[] services = client.probe(types, scopes, matchingCriteria);

Hierarchical service deployment support in WSO2 WSAS-3.2.0

WSO2 WSAS-3.2.0 is the latest version of WSO2 Web Services Application Server which consists of some new features as well as a lot of bug fixes. Hierarchical service deployment is one of the new features included in the latest WSAS.
Hierarchical service deployment model allows you to deploy two (or more) different versions of the same service in a very easy manner.
Lets see how multiple versions of the same services can be deployed on WSAS-3.2.0

Pre-requisites:
Download WSO2 WSAS-3.2.0 from here

Step 1

Start WSO2 WSAS by running wso2server.sh{bat} from WSAS_HOME/bin
Access management console using https://localhost:9443/carbon and log in with the default credentials(admin/admin)

Select Axis2 Service from the left navigation menu.



You will notice there is an input text box, Service Hierarchy. Here you can specify a service path. eg:- /marketing/test
Browse a service archive (eg:- Axis2Service.aar) in your local file system and click on Upload.
The service will be deployed successfully, go to the service list page and you will the service is listed there as follows. The service name is prefixed with the hierarchy path you have given when deploying the service (marketing/test/Axis2Service)



Step 2

Now, we are going to deploy a different version of the same Axis2Service. Access the Manage --> Services --> Add --> Axis2 Service page and specify a new service hierarchy (eg:- /sales/test)
Browse the same service archive which have deployed in the previous step (Axis2Service.aar) and click on upload.

Now, you will notice a different version of the same service, sales/test/Axis2Service listed in the service management page.

Likewise, you can deploy many versions of the same service and make use them in your SOA infrastructure. Hierarchical service deployment facility can be used in Spring, Jax-WS and Jar services as well.