Many Java developers will be familiar with Eclipse's excellent support for debugging, with a little configuration, developers can easily debug a running XNAT instance.
It is very important to understand that due to the current build and deployment mechanism of XNAT, launching XNAT from within Eclipse is impractical. Rather, we connect the debugger to an existing Tomcat-based deployment of XNAT using the Java Platform Debugger Architecture, JPDA. JPDA, as we use it, consists of 2 parts. The first is a JPDA-instrumented version of your Java process (in our case, Tomcat running XNAT). As part of this process, JPDA listens to connections on a specified TCP port. The second part is a debugging client (in our case, Eclipse) that connects to this TCP port and issues breakpoints and stepping commands.
Before setting up debugging, first integrate XNAT with Eclipse.
Instrument Tomcat with JPDA
Method A: Modify Tomcat's Startup
We will modify our Tomcat startup script to pass the JPDA parameter and environment variables, leaving JPDA running whenever we start Tomcat. From our experience, leaving JPDA running on a development machine has no noticeable performance impact (just make sure your JPDA port is properly firewalled).
On Linux/Mac modify your $TOMCAT_HOME/bin/startup.sh from
to (feel free to change the port number):
On Windows, modify your $TOMCAT_HOME/bin/startup.bat from
You can now start Tomcat via startup.sh or startup.bat.
Method B: Single Use Environment Variables
If you do not want to modify Tomcat's startup script, you can set theJPDA_ADDRESS, JPDA_TRANSPORT
as environmental variables on the command line, then launch Tomcat via:
Connect Tomcat to JPDA
Create a new Debug Configuration
Select New launch configuration
Configure the Launch Configuration
Set the Port to the JPDA_ADDRESS you set in startup file and make sure that xnat is selected as the project to debug.
Set a Breakpoint & Debug
You can set breakpoints anywhere in the code. Navigate the website, when the breakpoint is hit, you will be prompted to enter the Debug Perspective.
The Debug Perspective allows stepping through the source as well as examining the state of variables.
Debugging Applets with JPDA
You can also use JPDA to debug applets running in the browser. To enable JPDA, go to the Java Control Panel > Java > Java Runtime Settings > View > User > Runtime Parameters
And add the options to enable debugging:
You can set the address to any free port (we are using 8000 in this example) If you've already got Tomcat listening for debugger connections on 8000, though, you'll want to use something different (8001 is fine).
After filling in the parameters, ,make sure you click the "Apply" button before clicking "OK", otherwise your changes might not be saved.
If you need to debug the applet startup, classloading, etc, set suspend to y. When you access an applet page, the browser will appear to freeze as the JVM immediately gets suspended waiting for a debugger to connect.
Related Best Practices:
- Encrypt Stored Passwords
- Using Mercurial for Version Control
- XNAT Developer Tools