Resolution for 'java.lang.OutOfMemoryError: PermGen space'

When running my application on Tomcat, 
I came across 'java.lang.OutOfMemoryError: PermGen space' and in-order 
to resolve it, all I had to do was set the following parameter as a 
JAVA_OPTS param on the command window which I was running Tomcat on.


$ export JAVA_OPTS="-XX:MaxPermSize=256m"

How to run JConsole with JTop

If you need to run JConsole with JTop, all you have to use
is the following command and it will appear as a new tab on
JConsole.

$ jconsole -pluginpath JDK_HOME/demo/management/JTop/JTop.jar

How to resolve error referring to the text "ap_cache_cacheable_hdrs_out" when starting Apache HTTP Server

I came across a need to enable the following links for the Apache HTTP Server, in order to enable response caching. Go to /etc/apache2 folder and give the following commands.

ln -s ../mods-available/file_cache.load file_cache.load
ln -s ../mods-available/mem_cache.conf mem_cache.conf
ln -s ../mods-available/mem_cache.load mem_cache.load

Once the above links were created, I tried to restart the server and it threw the following error

* Starting web server apache2
apache2: Syntax error on line 204 of /etc/apache2/apache2.conf: Syntax error on line 2 of /etc/apache2/mods-enabled/mem_cache.load: Cannot load /usr/lib/apache2/modules/mod_mem_cache.so into server: /usr/lib/apache2/modules/mod_mem_cache.so: undefined symbol: ap_cache_cacheable_hdrs_out [fail]

To resolve this all I had to do was, add the following line to the apach2.conf file before # Include module configuration: section
LoadModule cache_module /usr/lib/apache2/modules/mod_cache.so

How to generate HTTP 1.0 requests

While verifying some scenarios with WSO2 ESB I had the need to send HTTP 1.0 POST messages. Then came cURL to the rescue. I just had to use the option -0 or --http1.0 when sending the request like shown below.

$ curl -s "http://localhost:8280/services/Axis2Service" -d @soap11_echoString.xml -H "Content-Type:text/xml; charset=UTF-8" -H "SOAPAction: urn:echoString" -0

Or

$ curl -s "http://localhost:8280/services/Axis2Service" -d @soap11_echoString.xml -H "Content-Type:text/xml; charset=UTF-8" -H "SOAPAction: urn:echoString" --http1.0

When viewed through TCPMon, you will see how it sends a HTTP 1.0 message

POST /services/Axis2Service HTTP/1.0
User-Agent: curl/7.18.2 (x86_64-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.10
Host: 127.0.0.1:7001
Accept: */*
Content-Type:text/xml; charset=UTF-8
SOAPAction: urn:echoString
Content-Length: 273

<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ser:echoString xmlns:ser="http://service.carbon.wso2.org">
<ser:s>Hello!!!</ser:s>
</ser:echoString>
</soap:Body>
</soap:Envelope>

Making the resources of a WSO2 ESB READ-WRITE node available in the READ-ONLY node of a cluster

If you have a cluster of WSO2 ESB nodes and if you need to make the resources of the READ_WRITE node available on the READ-ONLY nodes all you have to do is set up a property in the carbon.xml. For the WSO2 ESB instances to be in a cluster, you need to have a WSO2 Governance Registry instance as well since in 3.0.x family, the resource that are created in WSO2 ESB are saved to a configuration/governance registry. In order to witness this, following steps should be followed.

Step 1 - Setting up the governance and configuration registry instances

a) Download the latest WSO2 Governance Registry distribution from here.

b) Extract the downloaded WSO2 Governance Registry distribution to two separate directories.
E.g.: - Extract the distribution to a folder named config-reg and gov-reg

c) Change the http/https ports (of the mgt-transports.xml) of these two instances so that it is possible for you to start the two registry instances on the same machine.

E.g. :- Assume that the ports were configured as below
Governance registry
- HTTP port - 9763
- HTTPS port - 9443
Configuration registry
- HTTP port - 9764
- HTTPS port - 9444


d) Change the registry.xml files of the governance and configuration registries as follows to connect to an external database (Let us assume that the two registry instances will be connected to two separate MySQL databases)

i) Add the following dbConfig to the registry.xml of the governance registry instance (gov-reg)

<dbconfig name="gov_registry">
<url>jdbc:mysql://localhost:3306/reg_gov_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>


ii) Add the following two dbConfig configurations to the registry.xml of the configuration registry instance (config-reg)

<dbconfig name="config_registry">
<url>jdbc:mysql://10.100.1.153:3306/reg_config_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>

<dbconfig name="gov_registry">
<url>jdbc:mysql://localhost:3306/reg_gov_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>


iii) In addition to the above add the following configuration to the registry.xml of the configuration registry (config-reg). This configuration will be used to mount the governance registry instance to this particular configuration registry instance.

<remoteinstance url="">:9443/gov/registry">
<id>gov_reg</id>
<dbconfig>gov_registry</dbconfig>
<readonly>false</readonly>
<registryroot>/</registryroot>
</remoteinstance>

<mount path="/_system/governance" overwrite="true">
<instanceid>gov_reg</instanceid>
<targetpath>/_system/governance</targetpath>
</mount>

e) Once the above configration are done, start the governance registry instance and the configuration registry instances

Step 2 - Setting up the WSO2 ESB READ-WRITE instance

a) Download the latest WSO2 ESB instance from here and extract it to a folder of your choice.
E.g. - Extract the distribution to a folder named esb-rw

b) Change the ports of the WSO2 ESB instance

E.g. :- Assume that the ports were configured as below
- HTTP port - 9761
- HTTPS port - 9441


c) Leave the default dbConfig section as it is and add the following to the registry.xml file.

<dbconfig name="config_registry">
<url>jdbc:mysql://localhost:3306/reg_config_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>

<dbconfig name="gov_registry">
<url>jdbc:mysql://localhost:3306/reg_gov_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>


d) Additionally, add the following configuration to the registry.xml inorder to mount the governance and configuration registries to the WSO2 ESB READ-WRITE instance

<remoteinstance url="https://localhost:9444/config/registry">
<id>config_reg</id>
<dbconfig>config_registry</dbconfig>
<readonly>false</readonly>
<registryroot>/</registryroot>
</remoteinstance>

<mount path="/_system/governance" overwrite="true">
<instanceid>gov_reg</instanceid>
<targetpath>/_system/governance</targetpath>
</mount>

<mount path="/_system/config" overwrite="true">
<instanceid>config_reg</instanceid>
<targetpath>/_system/nodes</targetpath>
</mount>

<remoteinstance url="https://localhost:9443/gov/registry">
<id>gov_reg</id>
<dbconfig>gov_registry</dbconfig>
<readonly>false</readonly>
<registryroot>/</registryroot>
</remoteinstance>


e) Next, enable clustering by uncommenting the following section of the axis2.xml

<clustering class="org.apache.axis2.clustering.tribes.TribesClusteringAgent" enable="true">
:
:
</clustering>


Step 3 - Setting up the WSO2 ESB READ-ONLY instance

a) Extract the downloaded WSO2 ESB instance to another folder of your choice.
E.g. - Extract the distribution to a folder named esb-ro

b) Change the ports of the WSO2 ESB instance

E.g. :- Assume that the ports were configured as below
- HTTP port - 9762
- HTTPS port - 9443

c) Leave the default dbConfig section as it is and add the following to the registry.xml file.

<dbconfig name="config_registry">
<url>jdbc:mysql://localhost:3306/reg_config_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>

<dbconfig name="gov_registry">
<url>jdbc:mysql://localhost:3306/reg_gov_db</url>
<username>wso2</username>
<password>wso2</password>
<drivername>com.mysql.jdbc.Driver</drivername>
<maxactive>50</maxactive>
<maxwait>60000</maxwait>
<minidle>5</minidle>
</dbconfig>


d) Additionally, add the following configuration to the registry.xml inorder to mount the governance and configuration registries to the WSO2 ESB READ-WRITE instance

<remoteinstance url="https://localhost:9444/config/registry">
<id>config_reg</id>
<dbconfig>config_registry</dbconfig>
<readonly>true</readonly>
<registryroot>/</registryroot>
</remoteinstance>

<mount path="/_system/governance" overwrite="true">
<instanceid>gov_reg</instanceid>
<targetpath>/_system/governance</targetpath>
</mount>

<mount path="/_system/config" overwrite="true">
<instanceid>config_reg</instanceid>
<targetpath>/_system/nodes</targetpath>
</mount>

<remoteinstance url="https://localhost:9443/gov/registry">
<id>gov_reg</id>
<dbconfig>gov_registry</dbconfig>
<readonly>true</readonly>
<registryroot>/</registryroot>
</remoteinstance>


e) Next, enable clustering by uncommenting the following section of the axis2.xml (This is required ONLY in a state-full setup)

<clustering class="org.apache.axis2.clustering.tribes.TribesClusteringAgent" enable="true">
:
:
</clustering>


f) Inorder for the resources that are in the READ-WRITE instance to be available in the READ-ONLY node, the following configuration should be added to the carbon.xml

<mediationconfig>
<loadfromregistry>true</loadfromregistry>
</mediationconfig>


Step 4 - Creating resources in the READ-WRITE instance

Once the configuration are properly done, start the READ-WRITE WSO2 ESB instance.

user@user-laptop:~/opt/esbrw/wso2esb-3.0.0/bin $ sh ./wso2server.sh


Now create some resources (Sequences, Endpoints, Proxy Services,etc) by logging into the Management Console

Step 5 - Witnessing the resources of the READ-WRITE instance in the READ-ONLY node

Finally, start the READ-ONLY instance and you will see the resources that were created through the READ-WRITE available through the READ-ONLY node

user@user-laptop:~/opt/esbr0/wso2esb-3.0.0/bin $ sh ./wso2server.sh

How to specify system-properties when WSO2 ESB started if deployed on top of an application server

When starting the WSO2 ESB server, we can specify different system-properties such as -DuseSynapseXML, -Dsetup, -Dcarbon.registry.root. But if you have deployed your WSO2 ESB instance on top of an Application server like JBoss or Tomcat, you will wonder how you can specify such options. To make this possible, all you have to do is follow the below steps.

Step 1 - Open a terminal window

Step 2 - Set the system-property which you want to set as a JAVA_OPTS variable
E.g.:- For linux - export JAVA_OPTS="-DuseSynapseXML"
For Windows - set JAVA_OPTS="-DuseSynapseXML"

Step 3 - Now start the Application server the usual way and you will notice that WSO2 ESB is started with the option which you set.
E.g.:- If you specified the system-property -DuseSynapseXML, notice that the server loads the synapse.xml located at the file system and not from the registry

Signing in to WSO2 ESB 3.0.x using users in an LDap User Store

Assume that you have a list of users in an LDap server and you need to access WSO2 ESB using one of the users in the LDap user store and not with the default admin username and password. All you have to do is do a simple change in a configuration file of your ESB instance. I have listed the steps which one needs to follow.

Pre-Requisites

An LDAP server should be up and running with users.

Step 1

Download the latest WSO2 ESB version from here and extract to a location of your choice.
(E.g.:- /opt/products/wso2esb-3.0.0). From this point onwards I will refer to this location as ESB_HOME.

Step 2

Next go to ESB_HOME/repository/conf and open up the user-mgt.xml.

a) First notice that the section with the tag <userstoremanager> is uncommented where the class is org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager. Comment out this section.
Then locate the section with the tag <userstoremanager> where the class is specified as org.wso2.carbon.user.core.ldap.LDAPUserStoreManager and uncomment it. This section will contain the configuration which is used to our LDap user store.


<UserStoreManager class="org.wso2.carbon.user.core.ldap.LDAPUserStoreManager">
<property name="ConnectionURL">ldap://localhost:10389</property>
<property name="ConnectionName">uid=admin,ou=system</property>
<property name="ConnectionPassword">secret</property>
<property name="UserSearchBase">ou=system</property>
<property name="UserNameListFilter">(objectClass=person)</property>
<property name="UserNameAttribute">uid</property>
<property name="ReadLDAPGroups">false</property>
<property name="GroupSearchBase">ou=system</property>
<property name="GroupSearchFilter">(objectClass=groupOfNames)</property>
<property name="GroupNameAttribute">cn</property>
<property name="MembershipAttribute">member</property>
</userstoremanager>

Note that you have to remember the ConnectionURL, ConnectionName and the ConnectionPassword values of your LDAP user store while setting it up.

b) Next go to the top of the user-mgt.xml and change the <username> and <password> tag values to a user which you already have in you LDAP user store.

c) Also change the <readonly> property value to true as shown below

<usermanager>
<realm>
<configuration>
<adminrole>admin</adminrole>
<adminuser>
<username>evanthika</username>
<password>evanthika</password>
</adminuser>
<everyonerolename>everyone</everyonerolename>
<readonly>true</readonly>
:
:
:
</realm>
</usermanager>


Step 3

Now you are all set to go. Go to the ESB_HOME/bin folder and start the WSO2 ESB server by giving the command

$ sh ./wso2server.sh

Step 4

Once the server is started access the Management Console through the URL https://localhost:9443/carbon and you should be able to login using the username/password which you specified in the user-mgt.xml file (evanthika/evanthika).

Quick guide to installing WSO2 ESB 2.1.x on IBM Websphere

This is a quick guide on how to install Carbon based WSO2 ESB on IBM WebsphereV6.1

Step 1 - Adding the keystore

Create a new profile through the 'Profile Management Tool' and then start the IBM Websphere server. Follow the steps given under 'Adding the keystore' of http://wso2.org/library/2735 and add the wso2carbon.jks keystore

Next, go to SSL certificate and key management > SSL configurations and click on 'NodeDefaultSSLSettings'. Select created keystore (E.g.:- wso2carbon) from the combo boxes 'Trust store name' and 'Keystore Name' and then click on the button 'Get certificate aliases'.
Click on 'Apply' and then save the changes done.

Step 2 - Preparing WSO2 ESB

Download the WSO2 ESB distribution and extract to a specific location. (E.g.:- C:\esb\wso2esb-2.1.2).
From this folder copy the folders,

- conf
- database
- resources
- repository


to a separate folder. (E.g.:- C:\esb\esb_repo). We will refer to this as the CARBON_HOME from this point onwards.

For Carbon 3.0.x family, you need to copy only the two folders resources and repository.

Step 3 - 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 correct WebContentRoot

E.g.:- /esb
Also change the ServerURL value in the same file as below.

https://localhost:9444/esb/services/
b) Next open the axis2.xml which is located inside the CARBON_HOME\conf and specify the correct paths for the two .jks files wso2carbon.jks and client-truststore.jks specified in the axis2.xml

c) 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:\esb\esb_repo\WSO2CARBON_DB;create=true

f) 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:\esb\esb_repo\conf\synapse.xml

Step 4 - Deploying the esb.war

a) Go to the webapps\ROOT folder of the WSO2 ESB which you extracted and create a war file using the command

jar -cvf esb.war *

b) Then as specified under 'Adding WSO2 WSAS to IBM WebSphere Application Server' of http://wso2.org/library/2735, install the war file.


Step 5 - Starting the IBM Websphere server

Now stop the startServer.bat and set the CARBON_HOME to the folder which you copied the folders conf, database, resources etc.

Next start the server and access the management console using
https://localhost:9444/esb/carbon