Integrated Java Debugger

jGRASP has an integrated debugger for Java. When the debug command is run, if it responds with a transport address (a line like  "Listening for transport X at address: Y." ), jGRASP will start the debugger. The default  "jdk (integrated debugger) - generic"  compiler environment will debug an application or applet with Sun's JDK 1.3. JDK 1.2 with the JPDA for 1.2 might also work, but will probably be quite buggy.

To use the integrated debugger, jGRASP must be running under the JDK (not a JRE). If you are having some problem with this (you get a "tools.jar file not on classpath" message when attempting to debug), putting the JDK bin directory at the beginning of the PATH should fix this. For a detailed description of how the jGRASP startup programs find/choose java, see Running jGRASP.

Also, you must be running (debugging) your programs under the JDK. The default Java compiler environment uses the classic VM, which is not included in the JRE (you could try copying the compiler environment and modifying it to use HotSpot, but we don't recommend it, as the HotSpot/debugger combination is slow and buggy). If you have the JDK bin directory at the beginning of your PATH and use the default Java compiler environment in jGRASP, there should be no problem. If you can't set things up that way, you will need to copy, modify (add to PATH environment variable), and use a Java compiler environment - see Settings and Compiler Environment Dialog.

Do not use the integrated debugger on a dual-processor Windows NT system, as this will most likely lock up jGRASP and the target process, frequently if not always.

Using the integrated debugger may lock up jGRASP occasionally. If this happens consistently (every time or every time for some particular target program), or if there are stack dumps from jGRASP, let us know.

Many additional features are planned for the debugger. See Future Plans for details.


 
 

Debug Window


 
 

Toolbar

Step Over - steps the selected thread within the current method or code block. The thread must be suspended to step. In normal step mode, this will execute approximately one line of source code in the current method. If "byte code size steps" is selected, approximately one byte code instruction will be executed. While the thread is stepping, "(stepping)" is displayed in its description in the threads window. Multiple threads can be stepped at the same time. Hitting "Suspend" will kill the step. When the step is completed, if the stepping thread or no thread is selected, the current source line will be selected; if another thread is selected, no action will be taken.

Step In - like step over, but will enter any method calls.

Step Out - like step over, but will step out of the current method or code block.

Step to Cursor - runs to the cursor for the active CSD window within the virtual desktop. All breakpoints are ignored during this operation, but watchpoints are not.

Suspend - suspends the selected thread, or all threads within the selected group.

Resume - start the selected thread, or all threads within the selected group.

Byte Code Steps - when on, use the smallest step size possible Otherwise, the step size is approximately one source line.

Suspend New Threads - if on, any new threads that start will immediately be suspended. If on when the debugging process is started, all startup threads are suspended as soon as is possible.


 
 

Threads Window

Shows the state of each thread, organized within the thread group tree. Suspended threads are shown in red, running threads in green. This window in updated dynamically, so you can see the state of running threads change. The thread description is as follows:

name <x, y> [state] (debugger action/state) monitors


 

name -  name given to the thread. You should name any threads you start, to make them easier to track.

<x, y> -  shows jGRASP's current suspend count for the thread (x), and the actual count.(y). This is for our debugging purposes only, it should not be of interest to the user unless jGRASP is not working correctly. The actual suspend count may be one higher than jGRASP's suspend count temporarily, but they should be the same most of time. jGRASP's suspend count should always be 0 or 1.

[state] - shows the current suspend state: running, waiting, waiting on monitor, sleeping, not started, zombie, or unknown.

(debugger action/state) -  shows what the debugger is currently doing with respect to the thread: at breakpoint, suspended, running to cursor, or stepping. If none of these are true (the thread is running normally), nothing is shown.

monitors -  shows the monitors owned by the thread, by id number. This is the same id number shown for objects in the variables window. If the thread is waiting on a monitor, this monitor is shown in [braces].


 

For a simple, non-gui application, there will be your "main" thread, any threads that your code creates, and several system support threads (Signal Dispatcher, Reference Handler, Finalizer). For applets or gui applications, there will be numerous event queue, gui, and system threads.


 
 

Call Stack Window

Shows the current call stack for the selected thread, if the thread is suspended. When the thread is resumed, this window is disabled. Each frame of the stack shows the method, filename and line number if available, and program counter. The program counter is the current byte code index within the method. Selecting a frame will select the source line, if the corresponding file can be found, and show the associated variables in the variables window. Source files are located using the "Sources" entry of the global settings.


 
 

Variables Window

Shows the available variables for the current frame of the call stack. Composite objects can be expanded to see the fields or array elements. The target code must be compiled in debug mode, or not much information will be available here.

this or static -  shows fields for the current object if within an instance method or code block, or static fields available within the current static context.

Arguments -  shows arguments to the current method if within a method.

Locals -  shows the current local variables.

Objects are shown as squares, primitive types as triangles. All non-fields are colored blue. Field icons are color coded based on the declared type of the object containing them (the actual type may be a subclass or interface implementation). The coding is:

red -  field is declared in a superclass of the declared type of the containing object or an interface implemented by a superclass.

green -  field is declared in the declared type of the containing object.

cyan -  field is declared in an interface implemented by the declared type of the containing object.

yellow -  field is declared in a subclass of the declared type of the containing object or an interface implemented by a subclass.

Static fields are shown in italic type.

When a field is selected, the type in which it was declared is shown at the bottom of the variables window.

For arrays, at most ten elements are shown at once. To change the elements that are shown, select the object then click on it (but don't double click). A slider bar will appear, on which you can select the first element shown.

Any masked fields are shown with a grey bar over the icon.

Watches: Fields can be watched for access or modification if the target JVM supports it. To create a watchpoint, select a field and then right click. A popup menu will allow you to set a modification or access watchpoint, or to remove them if they are set. Fields that are being watched are shown with a black square in the center of the icon.


 
 

Breakpoints

Breakpoints can be set in the CSD windows using the  "View" / "Breakpoints"  menu, or the context menu. Only breakpoints in CSD windows are active (when a CSD window is closed, the breakpoints will go away, when one is opened, the breakpoints will become active. Breakpoints can be added or removed while the debugger is running.

While the debugger is running, invalid breakpoints (breakpoints set on lines that do not contain executable code) are shown crossed out. If the class files for a particular source file can not be found, the breakpoints are shown with a slash through them. In order for this mechanism to work, the source file and associated class files must be located in the same directory.