Remote debugging in Red Hat JBoss Fuse

Posted: September 1st, 2014 | Author: | Filed under: Technology | Tags: , , , | 2 Comments »

Debugging FuseTesting is one of the primary components of the software development process. It ensures a particular piece of functionality matches a desired expectation. Testing can occur in several forms ranging from unit testing, integration testing, and regression testing to name a few. When developing applications for the JBoss Fuse platform, each of these methodologies can be applied. The JUnit framework can be used to perform unit testing where direct support is made possible from key Fuse components such as Blueprint and Apache Camel. Pax Exam can be used to perform in container testing and validate functionality against a Karaf environment, the underlying container behind Fuse. While each of these methods provides some assurance against the expected functionality of a particular piece of software, many times a developer may want or even need additional assurance by running and testing their software in an actual application container. Fortunately, Fuse provides methods for interacting with the container in a remote fashion. Remote application debugging is not a new concept. Support is available from some of the most popular integrated development environments including NetBeans, IntelliJ and Eclipse. Since JBoss Developer Studio, an Eclipse variant, is the supported development environment for Fuse, we will focus on how to perform remote application debugging using Eclipse.

Starting Fuse in Debug mode

Prior to being able to connect to Fuse from a remote application, Fuse must be configured to accept remote application connections by placing it in debug mode.

Two methods are available to place Fuse into debug mode:

  1. Start the Fuse container with the debug option set
  2. Set the KARAF_DEBUG environment variable to true

The simplest method for starting Fuse in debug mode is to start Fuse with the debug option set. To do so, browse to the <FUSE_HOME>/bin folder and start the Fuse container as follows:

Linux or Mac:

./fuse debug

Windows:

fuse.bat debug

During container initialization, Fuse will also check for the presence of the KARAF_DEBUG environmental variable. If the variable has been defined and is set to true, Fuse will start in debug mode. Environmental variables can be defined on the terminal or command line as follows:

Linux or Mac:

export KARAF_DEBUG=true

Windows:

set KARAF_HOME=true

From the same terminal session, the Fuse container can be started without any additional parameters as described earlier. The one shortcoming to this method is that once the terminal session ends, the environment variable is lost and Fuse will no longer be placed into debug mode the next time it is started. To have Fuse consistently start in debug mode, the KARAF_DEBUG environment variable should be set permanently according to your particular operating system.

Remote access in the  Fuse container is made possible through the use of the Java Debug Wire Protocol (jdwp). If Fuse has been set into debug mode, it will by default expose port 5005 for remote access which can be verified by observing the following in the server logs during startup.

Listening for transport dt_socket at address: 5005

If the KARAF_DEBUG environment variable has been set, the full set of debug options will be printed:

karaf: Enabling Java debug options: -Xdebug -Xnoagent -Djava.compiler=NONE 
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005
Listening for transport dt_socket at address: 5005

These parameters can be customized by setting the JAVA_DEBUG_OPTS environmental variable. A full discussion the Java Debug Wire Protocol and the options that can be set is found here.

Debugging from JBoss Developer Studio

Once Fuse has been placed into debug mode and capable for accepting remote connections, an application can be debugged within JBoss Developer Studio against the running Fuse container. Open JBoss Developer Studio to a workspace of your choosing. Determine any areas in which you wish to debug and set breakpoints that will suspend the running application when the line of code is hit during the execution of the application. With the appropriate breakpoints set, select the project you wish to debug in the project view and select Run -> Debug as -> Remote Java Application from the menu bar. If your Fuse container is running and has been placed into debug mode, JDBS will prompt with the following menu:

JBoss Developer Studio Remote Debug

You may choose to customize the debug configurations by selecting the configure button, otherwise select Debug which will connect JDBS to Fuse. When the application running in Fuse hits one of the breakpoints previously set, the application will suspend at that point and JDBS will either prompt to switch into the debug perspective or switch automatically based on the configurations set in the JDBS workspace. With the application suspended, you are able to perform any debugging tasks you desire. A full overview on debugging in Eclipse is beyond the scope of this discussion and additional reference material can be found at the following links:

With only a few configuration steps, application can be tested and validated on a running remote Fuse instance. Remote application debugging is yet another method a developer has for creating reliable, robust applications.