Jd
A Graphical Debugger for Java

Derek Lieber
derek@watson.ibm.com
Java Tools Group
IBM T.J. Watson Research Center
Hawthorne, NY, USA

What is Jd?

Jd is a multi-paneled graphical debugger that lets you view the threads, call stacks, local variables, classes, and source files of a remotely executing Java program. It is written in Java, using the java.awt package to generate the graphics and the sun.tools.debug package to run the remote virtual machine.

Here's a screen shot.

Screenshot

What can Jd do?

Jd presents its information in panels, each of which holds a "snapshot" (an image of the state of the program at a particular instant in time) of some aspect of the remotely executing program.

Panels

The panels are organized as follows:

Classes Displays the classes that are currently accessible to your program, organized as a tree. Click on a tree node to expand or collapse that level of the tree. Click on a classname to display the source for that class in the Source panel.
Threads Displays the threads that are currently running or waiting to execute. Click on one of those threads and you'll see the frames of its current call stack in the Callers panel.
Callers Displays the stackframes of the currently selected thread. Click on one of those frames and you'll see its local variables in the Locals panel, its class in the Classes panel and its source code in the Source panel.
Locals Displays the local variables of the currently selected stackframe (if the class was compiled with "-g"). Click on one of those variables and you'll see its fields in the Inspector panel,
Inspector Displays the currently selected local variable. If the variable is an object or array, you can click on it to reveal its fields or elements, respectively. Successive clicks on the fields/elements will hide or reveal further levels of detail
Console Displays your program's standard input, output, and error streams. Type here when your program wants to read from the keyboard.
Source Displays the source code for a stackframe selected from the Callers panel or for a class selected from the Classes panel. Click on a source line to set or remove a breakpoint on that line. When the breakpoint is encountered, all (non-system) threads in the virtual machine are halted. You can then inspect the state of your program by clicking on the various panels. Hit the Run button (see Buttons, below) to let your program run some more.

You can search any panel for a text string, or goto a particular line number, by right-clicking the mouse on the panel to bring up a "search/goto" menu. Click on a menu entry and enter a string or line number into the dialog window that appears.

Title Bars

Click on a panel's title bar to enlarge it to the full size of the main window. Click again to reduce it back to its original size.

Splitters

The horizontal and vertical lines between panels are splitter controls. Drag them with the mouse to change the relative sizes of their neighboring panels.

Buttons

Control buttons are grouped at the bottom of the window, as follows:

Control all threads

Stop All Threads Stops execution of every thread in your program so you can examine their states and set or remove breakpoints. A stopped thread can still be single stepped.
Release All Threads Allows every thread in your program to run until one of them hits a breakpoint.
Refresh Updates the window panels to reflect the instantaneous state of the remote virtual machine, even if the program is not currently stopped.

Control currently selected thread

Step Thread Over Allows the currently selected thread to advance one source line in the current method, stepping over method calls(s) on that line, if any. Other threads continue to run, but any breakpoints they might encounter are ignored.
Step Thread In Works like Step but follows execution down into any method called by the current source line. Other threads continue to run, but any breakpoints they might encounter are ignored.
Step Thread Out Lets the currently selected thread run until it returns to the caller of the current method. Other threads continue to run, but any breakpoints they might encounter are ignored.
Release Thread Allows the currently selected thread to execute until it hits a breakpoint. Other threads continue to run, but any breakpoints they might encounter are ignored.

Miscellaneous

Edit Spawns an editor on the currently selected source file. You can specify a particular editor by defining a system property on the java command line used to invoke jd: 
        java "-Deditor=emacs +%L %F" ...
The name of the current source file will be substituted for %F and the current line number will be substituted for %L. If no editor is specified, "vi" will be used on AIX systems and "notepad" will be used on Windows systems. Note that on Windows systems, you must double the % signs if you embed the command line in a .bat file.

Menus

Finally, at the top of the main window is a menubar with two menus: a Session menu and a Views menu.

The Session menu is organized as follows:

Edit Source Path Allows you to specify the filesystem directories, .zip files, and .jar files to be searched when displaying the source code for a java class.
Edit Class Path Allows you to specify the filesystem directories, .zip files, and .jar files to be searched when loading the bytecodes for a java class.
Restart Kills the remote virtual machine and starts a new one. Do this after you've recompiled your program, for example.
Exit Kills the remote virtual machine and terminates the debugging session.

The Views menu allows you to hide/show any of the subpanels appearing in the main window.

What platforms will Jd run on?

Jd is written in pure Java and should run on any platform that supports that standard java libraries and the sun.tools.debug library, however it has only been tested on Windows NT and Windows 95, using Sun's 1.1.4 JDK.

Note that JDK releases prior to 1.1.4 contain a number of bugs that prevent jd from working correctly. To do anything useful you'll need the latest version of the JDK.

Where can I get Jd?

Internal IBM users can click here to obtain a copy of the distribution file, jdpkg.zip. Source code is included, if you want to play with it.

External users can obtain jd from IBM's public java tools web site . Follow the "IBM Technology Preview" link and then look for the link to "Jikes". No source code is included in this version, sorry.

The current version of the jd package is 1.8. If you' like to be informed of updates, send me email and I'll put you on our distribution list.

How do I install Jd?

  1. Unpackage the distribution file, jdpkg.zip. You can do this either by using the jar program that comes with Sun's JDK: 
    jar xvf jdpkg.zip
    or by using a public domain version of unzip: 
    unzip jdpkg.zip
    Either method will yield these files: 
    Readme.txt
jd.bat
jd.sh
jd.zip
jd.html
  2. Edit jd.bat (for Windows) or jd.sh (for Unix) and set the environment variables to match the place where you put jd.zip

  3. Finally, for Unix systems, do the following: 
    mv jd.sh jd
chmod +x jd
  4. Do not unzip jd.zip (unless you're interested in the source code). It's executed directly by the jd batch file / shell script.

How do I run Jd?

First, compile your program using javac -g. The -g option will cause the compiler to produce extra information that allows the debugger to display your method's local variables. You can run the debugger in one of two ways:
  1. Type "jd".
    When the debugger comes up, select the class containing your main() method from the Classes list.
    Then hit the Release All Threads button.

  2. Type "jd" followed by whatever parameters you would normally pass when invoking your java program.
    For example: jd Test arg1 arg2 arg3
    When the debugger comes up, hit the Release All Threads button.

Questions and Problems

If you have questions or problems, here are some possible solutions.

Change History

Version 1.8 (Oct 24 1997)
Added workaround for api bug when printing class information for java.lang.Object.
Fixed screen flash when popup dialogs disappear.
Added "goto linenumber" menu entry.
Special cased display of java.lang.Throwable.backtrace to deal with non-java data.
Special cased display of java.lang.String to deal with embedded newlines and excessive length.
Added blinking indicator to show when program is running.
When thread(s) are released, update threads panel to show green lights.
Deal with illegal line numbers (<0) when setting breakpoints.
Version 1.7 (Oct 02 1997)
First release to alphaworks.
Version 1.6c (Sep 30 1997)
Now you can string-search a panel by right clicking on its text area.
Now you can enlarge/reduce a panel by clicking on its title bar.
Changed scrollbars so they're only displayed while mouse is within panel.
Added performance enhancements:
Replaced uses of AWT Scrollbar's, Button's, Label's, and TextArea's with hand-written lightweight equivalents.
Replaced repaint()/update() with explicit redraw() calls.
Added author and program info to "About" menu.
Version 1.6 (Sep 15 1997)
Made use of new "step out" functionality that appeared in JDK 1.1.4
Changed implementation to match new "resume" and "continue" behavior that appeared in JDK 1.1.4
Hard coded a release dependancy check to 1.1.4 level.
Version 1.5a (Aug 25 1997)
Improved handling of connection errors during startup.
Changed button images.
Display "hourglass" cursor while busy.
Partitioned control buttons into groups: "control all threads" and "control single thread".
When stepping a single thread, we ignore breakpoints in all other threads.
Version 1.5 (Aug 19 1997)
Added a console window to handle program's input, output, and error streams.
Added flyover help.
Changed breakpoint behavior: upon breakpoint arrival, suspend all other threads so that current one can be stepped without interference from others.
Made various improvements to value printing (esp. arrays).
Fixed source file reader's handling of zip archives (it wasn't reading the complete file)
Version 1.4b (Aug 13 1997)
Fix bug in sun.tools.debug.RemoteDebugger.close() that caused hangs when "close" button hit
Fix bug in sun.tools.debug.RemoteDebugger.objectFinalize() that caused hangs during garbage collection
Include fixes to sun code as part of jd's .zip file
Note: jd now ONLY works for jdk 1.1.2 and above (since we're shipping patched remote debugger classes)
Version 1.4a (Aug 06 1997)
Fixed bug in classpath editing (failed to pass new path to new remote vm)
After changing source path, refresh windows so previously "not found" file now gets shown
When restarting, automatically bring up most recent "startup" class as initial selection
Version 1.4 (Aug 01 1997)
Added ability to start debugger in "browse" mode, ie. without specifying a "main" class to run.
Added ability to select "main" class to run from class lister.
Added ability to edit classpath and sourcepath without restarting debugger.
Made class lister less greedy. It won't scan a filesystem until it needs to.
Version 1.3 (Jul 14 1997)
Added ability to breakpoint inner classes, nested classes, and multiple classes per source file.
Simplified thread control logic, removed display of system threads.
Include class qualifier as part of field names displayed in "inspector" window.
Added toolbar with iconic control buttons and flyover help.
Version 1.2 (Jul 01 1997)
Added ability to expand/collapse levels of detail displayed in "inspector" window.
Added some images and icons
Version 1.1 (Jun 20 1997)
Added menubar with "session" and "view" controls.
Added "edit" button.
Preserve layout information across sessions using .jdproperties file.
More robust "restart" behavior when remote process terminates unexpectedly.
Version 1.0 (Jun 13 1997)
Added ability to select classes in which to set breakpoints before they're loaded by vm.
Added ability to remember breakpoints across restarts.
Added tree view decomposition of class path.
Added -classpath and -sourcepath arguments.
Version 0.9 (Jun 05 1997)
Added "value inspector" panel.
Added "restart" button.
Improved formatting of displayed values.
Improved display handling of "currently selected local variable" during stepping.
Gave better names to some of the control buttons.
Changed name of this program from "jevex" to "jd".
Version 0.8 (May 21 1997)
Made changes to accomodate new AWT event model.
Version 0.7 (Apr 02 1997)
Made changes to accomodate new scrollbar behavior that appeared in JDK 1.1.1
Added zip file support
Version 0.61 (May 13 1996)
Fixed some of the scrolling and layout problems that appeared with JDK 1.0.2
Version 0.6 (May 09 1996)
Made changes to accomodate JDK 1.0.2
Added array display handling. Added cursor shape changers to split panel controls.
Version 0.5 (April 03 1996)
Added automatic scrollbars.
Version 0.4 (April 02 1996)
Added split panel controls.
Documented installation procedure for Unix systems
Version 0.3 (March 21 1996)
Improved screen appearance.
Added support for passing "java" command line arguments to remote debugger.
Worked on "local variables" display.
Version 0.0 (March 1996)
Initial release.
Written: Mar 1996
Last revision: 24 Oct 1997 [DL]
Licensed Materials - Property of IBM
(c) Copyright IBM Corp. 1997 All Rights Reserved.
US Government Users Restricted Rights - Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.