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, HotSpot VM) - generic"  compiler environment will debug an application or applet with most 1.3 or higher JDKs.

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.

Do not use the integrated debugger with jdk 1.3 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 with older jdks. 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.


 
 

Debug Window and Workbench


 
 

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.

Auto Step - when on, stepping or resuming will automatically repeat, for an animation effect. A delay window controls the time spent in the stopped state, after a step or at a breakpoint or watchpoint.

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. Dues to bugs in Java, this value may be incorrect. If the thread is in a native sleep on Java 1.4, the state is usually shown as "running".

(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. A source file can be located if the class is in a file that is in an open CSD window or is in the current project; or if the file package root is the working directory for the debug operation (which it commonly is), or is one of the "Sources" entries of the active project.


 
 

Variables Window

Shows the available variables for the current frame of the call stack. 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.

Values are displayed as described in Display of Values

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


 
 

Eval Window

Shows the value, in the current debugger context, of limited Java expressions entered by the user. These expressions are a subclass of Java expressions with the following limitations:

No assignment expressions (= += etc.).

No anonymous class creation.

No increment or decrement (++ --).

The package java.lang is available (for classes that have been loaded), but the imports for the source file of the current debugger context (if the source file is available) are not. So to access java.awt.Color.red, for example, you must use the full package/class name (and the class "java.awt.Color" must have been loaded in the target VM).

Evaluation is currently incomplete and not completely compliant with the Java language specification. Most notably, inner/outer class resolution for fields/methods, and class.this are not implemented.

Values are displayed as described in Display of Values. Operations can be performed on values using a context menu. These are described in Operations on Values.


 
 

Workbench

A place to put objects so that they can be conveniently monitored or operated on. Objects on the workbench will not be garbage collected until they are removed from the workbench.

Values are displayed as described in Display of Values. Operations can be performed on values using a context menu. These are described in Operations on Values.


 
 

Display of Values

Values are displayed in a tree, where the field values of each Object or the elements of each array are its children in the tree.

Operations can be performed on values using a context menu. These are described in Operations on Values.

Ctrl-C or dragging will copy a string representation of the value if it is a primitive or String, othewise it will copy the name of the item in the current scope, including any necessary casting.

For Object values, a unique id is displayed. Any Objects with the same id are the same Object.

Note that another thread may change values while you are viewing them. To update the displayed values when debugging a multi-threaded program, collapse then expand the parent node.

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:

orange -  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.

gray -  declared type is an interface and field is declared in the class of the value, but not in the interface.

Static fields are shown underlined.

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. To jump directly to an element, use "Goto Array Element" on the context menu.

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

Fields that are inaccessible in the selected call stack frame are shown with a red outline.

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. A "Watch All" will set a watchpoint on all fields of the same signature as the selected field (including those in subclasses and superclasses of the field's object type). A simple "Watch" will set a watchpoint only for the selected field's object. Fields that are being watched for modification are shown with a black triangle pointing up in the center of the icon, those with an access watch are shown with the triangle pointing down, while those with both will have a black square. Setting a lot of watches can slow down debugging.


 
 

Operations on Values

Depending on context and type of value, any of the following operations may be available (these will be described in more detail in a future release):

Goto Array Element - for an opened array with more than ten elements, chose an index to view.

Add to Workbench - for non-null Objects, put Object on workbench.

Invoke Method - invoke an instance or static method on an Object, or a static method on the type of the value if not a non-null Object.

Create New Instance - create a new instance of the class of the value.

Create Array Of - create an array of the type of the value.

Change Value - for fields, change the value of the field.

View by Name - bring up a viewer showing the value for the name of the selected item. For example, if you view a String named "str" in the current scope, and it is assigned to a new String, you will see the new string. When "str" goes out-of-scope, you will no longer see the value, unless a different "str" is valid in the new scope, in which case you will see the value of the new "str".

View Value - bring up a viewer for the value object. This object will be tracked indefinitely, and is protected from garbage collection while it is being viewed.

Copy Name - copy the name of the selected item, with any necessary casts, to the clipboard. You could use this name in the current scope to access the object, assuming it is accessible.

Copy Value - for primitive objects and Strings, copy a string representation of the value to the clipboard.

Watch for Modification - for fields, stop the debugger when the field is next modified.

Watch for Access - for fields, stop the debugger when the field is next accessed.

Watch All for Modification - for fields, stop the debugger when a field with this signature is next modified.

Watch All for Access - for fields, stop the debugger when a field with this signature is next accessed.


 
 

Breakpoints

Breakpoints can be set in the CSD windows using the  "View" / "Breakpoints"  menu, the context menu, or by moving the mouse over the "breakpoint zone" (the mouse cursor will change to a breakpoint) and left-clicking. Only breakpoints in open 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, and the debugger will stop at the next valid line. 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.