Debugging iSeries Java Applications Remotely
May 17, 2006 Mike Brown
|
IBM has provided several approaches for debugging Java applications on the iSeries, such as the IBM iSeries System Debugger. However, if you are an experienced Java developer, yet not experienced with the iSeries, you might find these tools and their instructions for use a little intimidating. One alternative might be the Java Debugger (jdb) provided with most Java Development Kits. This is a command line utility that supports breakpoints, stepping through your application and examining objects. Unfortunately, IBM does not provide this tool on the iSeries. I would guess that most Java developers have either not used jdb in a long time or at all. Instead, they are likely experienced in using Integrated Development Environments (IDEs) in developing and debugging Java applications on platforms such as Microsoft Windows and Linux/Unix. While every development tool has advantages and disadvantages, IDEs can be a benefit in debugging applications. In a graphical environment, it is easier for me to see the source code, the call stack, local variables and their values, etc. Don’t you wish you could use a debugger in an IDE similar to Eclipse or NetBeans for debugging applications on the iSeries? As the following shows, you can. Note that this article describes the capabilities of the Java environment on the iSeries running i5/OS V5R3 and Java 1.4. Some changes have been made in the release of Java 1.5, which is supported on V5R4. Java Platform Debugger Architecture While IBM does not support the jdb tool on the iSeries, they do support the Java Platform Debugger Architecture (JPDA) in the iSeries Virtual Machine (VM). The following is Sun’s definition of JPDA: JPDA is a multi-tiered debugging architecture that allows tools developers to easily create debugger applications that run portably across platforms, virtual machine (VM) implementations and SDK versions. The architecture consists of three major components:
IDEs use JDI to communicate with the VM using the JDWP protocol. I’ll discuss the JDWP protocol a little later when describing how to start a Java application on the iSeries to enable remote debugging. Back to the Beginning Recently I have been using Eclipse 3.1 for developing, testing and debugging Java applications. Having a project already configured in an IDE will give you a head start in debugging applications remotely. The main advantage will be that you will already have a project structure defined with the location of the source code known to the IDE. This will enable the IDE to display the source code during the debugging session. In order to get the most out of the debugging session, you will want to make sure that the class files produced by the Java compiler include debugging information. While this is usually the default, it doesn’t hurt to make sure you are including debugging information in the class files. Figure 1 shows the project properties dialog, which is accessed by right-clicking the project name in the Navigator panel and selecting “Properties.” As you can see in the Classfile Generation section, the options for including debugging information in the class files are checked.
I recommend debugging the application locally, if possible, to get familiar with the IDE and its debugger interface. This will be especially helpful if you are new to the IDE. In addition, you will have one or more breakpoints already set in the application. Your application’s source code path will also be configured correctly. Starting Your Application on the iSeries for Debugging As you might expect, you have to do something a little special to set up your application to be debugged remotely. You wouldn’t want some rogue developer connecting to your application in production, would you? IBM’s VM implements the JPDA architecture, but you have to tell it that you intend to use it. This is accomplished by using the -Xrunjdwp VM option. This lets the VM know that you intend to use JPDA to debug your application. The -Xrunjdwp option has some required and optional sub-options that I will discuss below. In addition to using the -Xrunjdwp option, you will want to make sure that the VM will execute your application in the interpret mode. This is accomplished using the -interpret option. This is not a standard option on most VMs, but is provided by IBM to override compiled Java programs and to disable Just In Time (JIT) compilation. As I mentioned above, the -Xrunjdwp option has sub-options that must be specified. These take the form: -Xrunjdwp: The critical sub-options are:
See “JPDA Connection and Invocation Details” in the Resources section below for a discussion on all the connection options that are available. Here is the command to use in QShell to start the VM in preparation for debugging an application whose main method is in the class com.mydomain.props.Main (ignore the line breaks): java -interpret -Xrunjdwp:transport=dt_socket, address=8000,server=y,suspend=y com.mydomain.props.Main The CL command for the same situation is:
JAVA CLASS(com.mydomain.props.Main) INTERPRET(*YES)
PROP((os400.xrun.option 'jdwp:transport=dt_socket,address=8000,
server=y,suspend=y'))
Configure Your IDE Debugger for Remote Debugging Now you have an application running on the iSeries that is listening for a debugger to establish a socket connect and begin the debugging process. So, how do you do that? The following discussion is specific to Eclipse, but other IDEs allow you to configure a remote debugging configuration in a similar fashion. Instructions for doing this in the IDE you use should be found in the tool’s accompanying documentation. From the “Run” menu, select the “Debug . . . ” menu. The dialog that is displayed allows you to define debugging configurations. Select “Remote Java Application” in the Configurations tree view and click the “New” button. Your current project, the one with those carefully chosen breakpoints already defined, will be the default project. Provide a name for this configuration that identifies it as a remote configuration so it can be easily identified in the future.
The “Connection Properties” section of the dialog is where you specify the server and port to use for connecting to the iSeries. The port should match the address sub-option value specified above. Click “Apply” to save the configuration. When you click the “Debug” button, the IDE will establish a socket connection to the iSeries and begin the debugging process. Since we had specified the suspend sub-option above, the VM will stop before loading the main class. You will likely find that the debugger has stopped in the Java ClassLoader. Since you have specified breakpoints already, simply select “Resume” from the “Run” menu to allow the VM to load and execute the main class until the first breakpoint is reached. At this point, you will be able to debug the remote application just as you have done when debugging locally. Slow Network Considerations Debugging applications over a network is obviously going to be slower than debugging applications locally. Eclipse provides a mechanism to adjust the timeout value for communicating with the VM containing the application being debugged. This configuration option is global and not project specific. Select “Preferences” from the “Window” menu to bring up the global preferences dialog. Expand the “Java” node in the tree on the left and select “Debug”. Figure 3 shows the global preferences dialog. Here you will be able to modify the default socket timeout (Debugger timeout) value used in communicating with the remote VM. The value is in milliseconds, so the value below is equivalent to 15 seconds. This should be adequate for slow networks. If you see erratic behavior such as local variables not being displayed correctly, try increasing this value.
WebSphere Development Studio Client for iSeries If you have IBM’s WebSphere Development Studio Client (WDSc) for iSeries, the instructions contained in this article should apply to that tool as well. WDSc is built upon the Eclipse tool described in this article. While there may be some additional menus and choices in WSDc, the base product is still Eclipse. For the curious, you can review the online help for WDSc (see the Resources section). On this website, select “Debugging applications” in the Table of Contents and expand “Java development tools (JDT) debugger.” Under that section you will find information on debugging Java applications including a section entitled “Remote debugging.” Although the section is brief, you will find references to the dialog in Figure 2. Unfortunately, I do not have access to WDSc, so I cannot test this out for myself. However, I feel confident that it should work in the same manner as described above. Now You’re Cooking! If you are already familiar with debugging Java applications in Eclipse or another IDE, setting up for remote debugging is not as hard as you probably thought it was. It was made easy due to Sun’s forethought in specifying the JPDA architecture. This same approach can be used to attach the debugger to almost (I haven’t tried them all) any remote application that has been compiled with debugging options and running on a remote computer, including Linux and Windows platforms. If you are not familiar with debugging in Eclipse, spend some time reading through the help files. There you will learn tricks about setting conditional breakpoints as well as setting breakpoints on caught and un-caught exceptions. Mike Brown is the founder of comIT, a consulting company that provides architecture, project management and development services. Mike’s experience ranges from compiler development to Department of Defense contract work to commercial IT systems. He can be reached at mbrown@comITServices.com. RELATED STORIES AND RESOURCES A Java Developer’s First Deployment on the iSeries IBM’s Toolbox for Java Is Getting Better Every Day The Java-Based iSeries System Debugger Java Performance on the iSeries Debug Java Programs That Run On Your Server Java Platform Debugger Architecture (1.4) |
