Debugging an integration solution developed with a typical ESB is pretty hard, most of them do not support step through debugging at all, it was like JavaScript earlier days, where you used to put alerts and debug. UltraESB on the other hand provides seamless step through debugging just as how you debug today’s JavaScript code within the browser itself or your simple Hello World Java application within the IDE.
Standalone IDE debugging
Debugging the solution as an standalone application within the IDE is pretty easy and is mostly used with developer testing, where the developer finds and issue in the testing phase which is not obvious to fix, and e/she want to see what is happening internally.
To be able to step through debug while testing the solution requires the UltraESB project to be started in debug mode within the IDE.
|
Note
Please make sure to stop the UltraESB if it is running in the run panel, otherwise you will get a bind exception for the ports when you try to debug, as it tries to start the UltraESB transports on the same ports.
|
In order to start the UltraESB with the solution that you developed in debug mode, you should use the Debug icon instead of the Run icon on the top tool-bar.
-
Note that the Debug icon on the right side of the Run icon on the top tool-bar, which we use to start the UltraESB in debug mode.
-
Note the new addition of the Debug tab into the bottom panel which is going to be automatically active, when you start the server in debug mode.
Now the UltraESB is running in the debug mode, and before sending the sample message we should put the breakpoints into the code where we want to debug. For that matter you can click on the left bar of the source editor as shown below.
This case we want to debug the execute method of the sequence class SimpleJavaMediation1.java so lets put the breakpoint at the first line of the execute method.
The breakpoint is now set and we are ready to debug a single message flow.
|
Breakpoints for startup
If the mediation sequence initialization (init method of the sequence class) or some UltraESB starup related point debugging, you should put the break points before starting the UltraESB in debug mode
|
Send a message using the Toolbox client to debug the message inside the sequence. The message will be paused at our breakpoint and the breakpoint will get highlighted.
Debugging an issue within the IDE is quite easy, and the following items explains all what you have to know about the IDE features in debugging.
-
Note the highlighted breakpoint where the message execution is paused by the debugger
-
The Variables pane in the debug panel shows you the states and the values of all the relevant variables in the context.
-
Watches pane allows you to watch the value of a certain variable or an expression throughout the debug session, how it changes, etc..
-
The execution call stack or the path which the thread came to this point is shown in the Frame pane, where you can see the states of the variables on that context.
-
The debug actions tool-bar facilitates different mandatory actions, which we will discuss shortly in more detail
-
Debug panel tool-bar facilitates many other debug operations and controls
-
The Console tab when switched from Debugger tab, shows the runtime output.
While you can see the complete context in the Variables pane, sometimes it is necessary to see the values/results of an evaluated expression in this context to understand/point out certain logics. In which case the Evaluate Expression tool works like a charm.
Right click on the editor and select the "Evaluate Expression" menu item from the context menu to get the Evaluate Expression tool.
The Evaluate Expression tool will appear on selecting this menu item and type the expression that you want to see the result as follows.
The debug actions tool-bar gives a good set of controls to support step through debugging with certain shortcut keys.
Icon |
Shortcut Key |
Action |
|
Alt+F10 |
Shows the execution points |
|
F8 |
Step over to the next line |
|
F7 |
Step into the next immediate call |
|
Alt+Shift+F7 |
Force step into the next immediate call |
|
Shift+F8 |
Step out to the immediate caller |
|
 |
Drop frame (Reverse step) |
|
Alt+F9 |
Run to cursor |
While this action tool-bar is of utmost help, the debug panel tool-bar is also facilitating many required features
Icon |
Shortcut Key |
Action |
|
F9 |
Resume program |
|
Ctrl+F12 |
Stop debugging |
|
 |
Pause program |
|
Ctrl+F5 |
Re-debug program (after stopping) |
|
Ctrl+Shift+F8 |
View breakpoints |
|
 |
Mute breakpoints |
All the above controls of the IDE and the seamless integration to use these IDE debugging features help UltraESB users to develop there solutions based on the UltraESB in a flash.
Remote debugging
Remote debugging only differs from the standalone debugging, in the way UltraESB is being started and the way the IDE is being connected to the server.
Remote debugging is important and useful in environment specific issues, where the same issue might not occur in the developers development environment. These issues are mostly being discovered in the black box testing on the integration environment. In these cases the UltraESB is started as usually with parsing few special flags to the JVM, for the IDE to be able to remotely debug the UltraESB server running on the integration environment.
UltraESB supports two approaches in starting an UltraESB instance.
Standalone startup script
When running the UltraESB with standalone startup script, the ultraesb.sh or ultraesb.bat files found in the bin directory of the UltraESB installation directory.
To be able to remote debug the server started with the startup script you should pass in the "-xdebug" flag to the script as follows.
$ cd /opt/ultraesb-2.6.1/bin
$ ./ultraesb.sh -xdebug
When you start the UltraESB with passing this option, you will see on the console that the UltraESB server is waiting for a remote debug connection to start as follows.
Starting AdroitLogic UltraESB ...
Using JAVA_HOME : /opt/jdk1.7.0_80
Using ULTRA_HOME: /home/rajind/builds/ultraesb-2.6.1
Listening for transport dt_socket at address: 8000
Once you connect the IDE remote debugger to the host running the UltraESB server over port 8000, which is the default remote debugging port, you will be able to see the server starting up.
To enable remote debugging when running as a daemon with wrapper, edit the wrapper.conf file located in the conf directory of the UltraESB installation directory and add the following additional java arguments to the next numbered additional arguments.
wrapper.java.additional.12="-Xdebug"
wrapper.java.additional.12.stripquotes=TRUE
wrapper.java.additional.13="-Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=y"
wrapper.java.additional.13.stripquotes=TRUE
Then we can start the UltraESB with the ultraesb-daemon.sh script found in the bin directory of the UltraESB installation but most probably when you run you will get an output as below.
No passwd entry for user 'ultraesb'
That is because before running a small change has to be made in ultraesb-deamon.sh.
Let’s open up the ultraesb-deamon.sh on a text editor. At the top there is an entry as USER=ultraesb. Now if you are running this under a user called ultraesb this is fine but if you are running
under another user say "asankha" change this entry to USER=asankha. Now you can run it without any problem.
$ cd /opt/ultraesb-2.6.1/bin
$ ./ultraesb-daemon.sh console
You will be able to see the daemon script is blocking the startup until the remote debugger is connected.
Running AdroitLogic - UltraESB...
--> Wrapper Started as Console
------------------------------------------------------------------------
The JVM is being launched with a debugger enabled and could possibly be
suspended. To avoid unwanted shutdowns, timeouts will be disabled,
removing the ability to detect and restart frozen JVMs.
------------------------------------------------------------------------
Launching a JVM...
Listening for transport dt_socket at address: 8000
Once the IDE remote debugger is connected the server will resume the startup.
In-order to connect the IDE to remote debugging, a remote debugging configuration needs to be created. For that matter click on the UltraESB runtime configuration and once you click on that you will see a drop-down menu as shown below.
There you will see at the bottom, a configuration as "UltraESB (Remote Debug)". You can simply use that as it has been already configured for you, but to understand it better let’s look at the configuration.
Click on the "Edit Configurations" to see the configuration editing window. There you can see a configuration under the "remote" section as shown below.
-
Name to identify the configuration, here we have used "UltraESB-Remote"
-
Host name at which the UltraESB server is running, in this configuration we have used "localhost" assuming UltraESB server is running on the same machine
-
Port has been set to "8000" which is the remote debug listening port specified in the UltraESB server running remotely.
-
Module in this configuration is <whole project>. You can change the module or keep it as <whole project> if you have more than one module in your solution project to debug
Now when you click "OK" this "UltraESB (Remote Debug)" will be selected and you will notice that the Debug icon () enabled, while Run icon is disabled (as this configuration is only for remote debugging)
Click on the Debug button to attach to the remote UltraESB server.
|
Enable port 8000
If you are running the UltraESB server on a hardened system behind a firewall, you might want to unblock the port 8000 such that the IDE debugger can attach to the UltraESB.
|
Put a breakpoint as in the standalone case and send a message to the remote UltraESB server, where you will be able to debug that message flow from within your IDE with all the debug options in standalone mode applied exactly the same to the remote debugging session too.
Advance remote debug options
You can change the port from 8000 to any port available to use, by editing the ultraesb.sh/bat and replacing the 8000 in the following string. Same way you could change the port that you specify for the wrapper.conf
XDEBUG="-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,address=8000"
You could change the behaviour of the debugger to not to suspend the startup by changing the above line to read as follows. Note the addition of suspend attribute. Same way with wrapper you can change the suspend value to "n" to not to suspend the server startup
XDEBUG="-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n"