WSO2TORIAL: Working with MAIN sequences in the WSO2 ESB

In this episode of our WSO2 tutorial: The WSO2 ESB has two sequences that are already defined / available when you install the product, the FAULT and MAIN sequence. In this blog we are going to look at the MAIN sequence and will cover the fault sequence in another blog. 

Both are found in the [ESB HOME] /repository/deployment/server/ synapse-configs/default/sequences directory.

The main sequence

The main sequence is used for any calls to the ESB where there is no defined service to match the call. With a defined service we mean for instance a axis2 service like localhost:8280/services/echo. This is a web service bundled with WSO2 ESB that does nothing more than simply echoing a string you send it to.

Calling this service with the right soap message (taken from the wsdl that accompanies the echo service) it will simply respond with an echo of the message.

Let’s say that we make a mistake and we do not call the existing echo service but add an extra ‘o’ to the URL making it : localhost:8280/services/echoo. Unless we defined a service with such a name the ESB cannot find what you want to call and will route the call to something that is called the main sequence.

This main sequence will do nothing other that give a 202-accepted, log the incoming message to the console (unless it is one of the samples) as you can see in the actual text of the main sequence. The first 18 lines of comments are omitted from this screenshot.

So your call will end up nowhere since there is actually no place it could go.

One of the best practices of using the ESB is to change the main sequence a little bit so it will actually record all calls that end up in the main sequence.

In this blog we record some simple data about the call and store it. We can use a database, in this case we use MySQL, to record relevant data.

You can elaborate on this example for your own environment adding more information or perhaps putting the message on a message queue.

In this simple case we insert a record into a MySQL table that records:

• Service called
• Date / time of the call
• Message format

Although they are available they are not defined yet in the way that would make sense. In this article we will discuss the sequences’ purpose and possible definition.

Setting up the database

First you need to install MySQL community edition. You can use any other database with a JDBC connector but for this blog we use MySQL. For information about the installation of MySQL, please follow the instructions on the MySQL site.

After installing MySQL you need to copy the MySQL-connector-java-5.1.36-bin.jar (the java-driver to make the connection) to the directory [ESB_HOME]/repository/components/lib.

1. Start the command line version of MySQL as root with the following command:mysql –u root -p
2. Enter the following commands to create the database and table;
   1. Create database mainseqcalls;
   2. use mainseqcalls;
   3. create table calls (callto varchar(50), date varchar (50), messageformat varchar (50) );

 Now you have the required database and tables to store data in. We chose a default length of 50 characters for each of the fields.  If the url (the part beginning with services/ ….) is bigger than 50 characters it will give an error. You can set the field names to your liking, either exactly matching the field’s maximum size or leave it as is. In that case however the record will not be inserted if the URL is too long. The length of a URL is often determined by the browser used, but in general about 2000 characters seems to be the maximum.

Changing the main sequence

We now need to change the main sequence to store the records in the table. The first part is logging to the console the fact that there is no proxy with the name we just called. The value is taken from the ‘To’ property.

<log level="custom">

   <property xmlns_ns="http://org.apache.synapse/xsd" name="There is no proxy called:" expression="get-property('To')"></property>

   <property xmlns_ns="http://org.apache.synapse/xsd" name="Please check the URL - " value="This call is logged in the database"></property>

</log>

The second part is calling the dbreport mediator. We define the database, driver, username and password in the connection part. You can also use a (carbon) datasource for this, however, for simplicity we’re using a plain username and password here.

<dbreport >

   <connection>

      <pool>

            <driver>com.mysql.jdbc.Driver</driver>

           <url>jdbc:mysql://localhost:3306/mainseqcalls</url>

           <user>root</user>

           <password>root</password>

       </pool>

   </connection>

With a simple insert statement we enter the three values into the ‘calls’ table as shown below.

   <statement>

      <sql>insert into calls values (?,?,?)</sql>

            <parameter expression="get-property('To')" type="VARCHAR"/>

           <parameter expression="get-property('SYSTEM_DATE')" type="VARCHAR"/>

           <parameter expression="get-property('MESSAGE_FORMAT')" type="VARCHAR"/>

      </statement>

   </dbreport>

The main sequence is now changed and when we start up the WSO2 ESB again will load the main sequence. It is also possible to do that while the WSO2 ESB is running. Changes will be detected and hot deployed.

We start a browser and try to access: http://localhost:8280/services/echodienietbestaat

The calls database shows a new record that has been added.

This simple example shows how you can change the MAIN sequence in order to record wrong calls to services.

WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required.