As a demonstration of the Java Debug Interface (JDI), we are providing source code for a simple GUI debugging tool - javadt. It is included as an example and demonstration of JDI. It is not a finished or polished debugger and is missing many features of importance for real debugging work.

Invoking javadt

javadt can be run by executing:

   java gui.GUI <options>.. <class-name>

where <class-name> is the name you would normally place on the java command line. Note: the paths to the JDI Library and to the compiled javadt class files must be on the class path used to invoke gui.GUI. Be sure that the Java 2 SDK's lib/tools.jar file on your class path.

For example, you can invoke the javadt debugger as follows:

   javadt gui.GUI -classpath . Hello

Note: this -classpath option controls the class path for the Hello application. Once the window appears, you can issue the 'run' command to begin execution immediately. It is also possible to give the class name in the 'run' command, in which case it may be omitted when invoking the debugger from the shell.

The classpath may also be set from within the debugger, using the 'classpath' command. Currently, other arguments to the VM must be given on the shell command line when the debugger is initially invoked. The most recently mentioned classpath, VM arguments, main class name, and program arguments are retained as defaults for later 'run' and 'load' commands. (Unfortunately, at present, the debugger will likely crash if you attempt to begin another debugging session with another debuggee process from within the same invocation of the debugger. You should exit to the shell and start a new debugger process.)

Using javadt

The javadt normally displays context related to the "current thread", that is, the thread that most recently encountered a breakpoint, threw an uncaught exception, or was single-stepped by the user. When program execution is suspended on account of one of these events, a current thread exists, and the javadt displays the following information about it:

• A stack backtrace.
• The source code surrounding the line corresponding to the instruction counter for the thread, if the source code is available.

In addition, a tabbed pane allows the user to view one of three additional views:

• A tree of all source files available on the source path.
• A tree of all loaded class files, organized hierarchically by package.
• A tree of all active threads, organized hierarchically by thread group.

By clicking on the name of a source file, the source view can be directed to display it. Likewise, clicking on a thread will make that thread the current thread. These features are normally used while the program is suspended, e.g, at a breakpoint. Upon resumption and encountering another breakpoint, for example, the current thread will be automatically reset and the views will be updated. The views tile the javadt display, and are adjustable in size.

The javadt functionality is rather basic, thus a command-line interaction window is also provided that allows access to functions that are not yet exposed in the javadt. In particular, it is necessary to use the command line in order to set breakpoints and examine variables. The javadt debugger command interpreter implements roughly a subset of the jdb functionality, but adds a few commands of its own. The 'help' command lists the complete set of commands and their function. Shortcuts for a set of the most common commands is provided on a button-bar at the top of the display.

The program to be debugged may be started either as a child of the debugger, or the debugger can be attached to an existing process, provided that its VM is prepared to accept the connection. If the debuggee is started by the debugger as a child, a line-oriented interface to its standard input, output, and error streams is provided in an application interaction pane.

The debugger expects to find the program source code on its sourcepath, set with the 'use' or 'sourcepath' command. If you find that sources are not being displayed because the sourcepath is incorrect, you may change it at that time, and the source view will be immediately updated.

The message "No current thread" is often encountered when stepping through a program. This message does not mean that the thread or the VM has died, merely that a current thread is undefined. This situation can easily occur unexpectedly when the program being stepped is waiting, eg., for input. The VM appears to be stopped, as it would be after the successful completion of a step, but it is considered to be "running", not "interrupted". The prompt in the command interaction pane indicates the state by changing to a thread name and frame number when the VM is interrupted. When it is running, the prompt "Command:" is displayed.

Source for javadt

Full source code for javadt is included in the com/sun/tools/example/debug directory of examples.jar. Note: this directory also includes the source for jdb. Source code of these example applications is included to provide concrete examples for debugger developers. Example code may be used, modified and redistributed by debugger developers providing they adhere to the terms in the copyright notice.

javadt uses the following packages (found in the com/sun/tools/example/debug directory of examples.jar):

gui

User interface code

bdi

Debugger core code

events

Event Set code

expr

Expression processing code

Building javadt

To build the javadt classes from the provided source files in the debuggers directory, you need only to compile them. No special options are required, aside from those which set your classpath to include the JDI Library. However, if want to modify the expression parser in the file Expr.jj, you will need the JavaCC parser generator.