Also when the ESB is not reacting in a manner you expect and cant find why the ESB is not handling your message or configuration in the way you expect then debugging its sourcecode can give you an insights into the rootcause of the problem and more importantly potentially even the solution to your problem.
Do not be afraid, this is not as difficult as it might sound. Let’s try to debug a standard component of the ESB; the LogMediator. The choice for the log mediator is simplicity, we can create a simple pass through proxy, for instance using the Echo service (echos the message it gets) and put a simple log mediator before the Send Mediator.
Getting started
Let’s first determine the version of the LogMediator which is shipped with the ESB. We need to know this in order to download the applicable version of the sourcecode.
Open up a file explorer and browse to [ESB_HOME]/repository/components/plugins. You can scan this folder for all *.jar files to find the jar which contains the LogMediator. The LogMediator class is located in file synapse-core_X.X.X.wso2vX.jar.
The version part is of most interest, we need this to find the proper version of the LogMediator source code.
For the rest of these instructions we’re assuming the filename was synapse-core_2.1.7.wso2v11.jar.
Lets now find the LogMediator source code. For this we need to go to Github (https://github.com/wso2/)
In the upper right corner, you find a search input field. Fill in LogMediator and press Enter.
In the following screen, click at the left on “Code” and (after clicking) in the Language section, click Java.
Then at the right you see search results. Scroll down the list until you find the following search result (do not pay attention to the date).
Click on LogMediator.java to open the GIT-commit. Click on the Code tab
The next step is to download the source code. Easiest is to download the source code as a zip-file.
Click on the green button at the right and click on “Download ZIP”.
Download the ZIP to a directory that you create. You can do it on the desktop so it is easy to find, but any other location will also work. Open file explorer and go to the download location. Right click the file and unpack the ZIP (this depends on your unzip tool and OS).
Importing it in Developer Studio
The next step is to import the source-code into WSO2 Developer studio. Start Eclipse the way you usually do (e.g. clicking on the icon). In the workspace, Project Explorer, Right-click on a piece of whitespace and select Import as shown below.
WSO2 builds it products using maven as build tool so we want to import an Existing Maven Project.
In the “select an import source” input field, type “maven” and hit Enter. Then select “Existing maven projects”
In the next screen click “Browse” and browse to the unpack-location of the downloaded Github synapse-core repository. Browse through to the modules/core folder and click OK.
A screen as the following should now appear
Click Finish to start the import. You might get some errors on some dependencies, you can ignore them for this blogpost. It just means not everything that is referred to in the source is available. Eclipse allows us to debug the sourcecode even when the sourcecode cannot be fully compiled so lets ignore these compile errors, as we will just debug the LogMediator this should not interfere.
In the workspace a project name “synapse-core” has now been added. It is not only the LogMediator that we’ve downloaded but actually the Synapse Core library. This library contains many other mediators and other related Synapse source code.
Open the “synapse-core” project and open the package org.apache.synapse.mediators.builtin as can be seen below:
Double click on the class LogMediator.
The sourcecode of the LogMediator will appear on the right.
Scroll down to the java method named “mediate”. This is the entrypoint of the mediator’s function and where we can set a breakpoint.
In the left grey area, double click in the grey area to the left of the linenumber of line 83. A blue ball will appear (See image above). This is a breakpoint and the debugger will stop at this code-line when the LogMediator class is executed. The LogMediator will be executed when a message is passing through a proxy where the LogMediator is present in the mediation-flow.
Starting the server in Debug Mode
The ESB needs to be started in the so called debug mode. This is done with a special parameter:
wso2server.sh –debug 8000 or wso2server.bat –debug 8000
The 8000 is the portnumber on which the ESB will listen for a debugger-client and the .sh is the Linux script whereas the .bat is of course for Windows.
Start the Debugger in Developer Studio
Now we need to enable the java debugger in Eclipse. That is done in the following way:
In the toolbar above the LogMediator source tab, click on the small black arrow to the right of the “bug”-icon.
Click on Debug Configurations in the context-menu that drops down.
In the Debug Configurations window scroll down to “Remote java application”
Next, right click on “Remote Java Application” and select New.
On the right we need to check that the details are filled in as follows:
Especially pay attention to the Connection Properties – Port, we need it later.
Click on “Debug”. The following popup may appear
Click on Proceed. The compile errors wont bother us in the next steps.
If everything went ok, you will now see the debug perspective in Eclipse. If you don’t have the debug perspective open you can open it by going to the Window menu and selecting “Open perspective” and then “Debug”.
The proxy and the LogMediator
Create a simple proxy with a Log Mediator in it, deploy it to the ESB and call that proxy using SoapUI or the TryIt feature in the ESB admin console.
Once a message is sent into the proxy the debugger will automatically stop at the breakpoint we set a couple of steps above.
The debugger in Eclipse will look similarly as the screenshot below.
In the variables section at the right you can see the current variables. When debugging sourcecode these variables contain very valuable information to assess the situation and identifying a problem.
Have a look at these variables so you can determine their state. In a debugging session where you are trying to identify a problematic situation this variables-view will prove to be invaluable to find your problem. Most likely a variable has a wrong value at a point in the execution process causing the ESB to behave differently then expected, Its then up to you as a developer to determine how you can manipulate the ESB to have the correct value at the right spot in the execution process.
Using these buttons in the toolbar to manipulate the debugging. Debugging is all about taking a small step at a time and have each line of code executed when you want it to. This toolbar will allow you to take the execution of the code one step at a time.
You can have the debugger “step into” or “step over” the statement its currently at. Stepping into a statement means that you will see what is happening inside other classes (which are executed on the debugged line of code) or you can step over the line so you stay in the current class and method.
The left green (play) icon allows you to continue processing until the next breakpoint will occur or when none exists it continues without stopping. The proxy service will then normally continue to process the message. For this exercise its not necessary to do more debugging so click on the green arrow in the toolbar at the top to have the proxy continue.
There you have it, you debugged your first piece of WSO2 ESB code. This can also be done on other code pieces like the Carbon Core. If you want to do that, following the same concept but, of course, for the Carbon Core code.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
Thanks to Thijs Volders for his contribution to this blog.
