When the debugger pauses your program, you can look at the current values of the program data items. Modifying data values during a debugging session provides a way to test hypothetical bug fixes during a program run. If you find that a modification fixes a program error, you can exit the debugging session, fix your program code accordingly, and recompile to make the fix take effect.
For a tutorial on debugging, see the tutorial called "Compiling, running and debugging."
Additional information and tips are available for these specific debugging topics:
JDataStore
component, see the "Troubleshooting" chapter of the JDataStore Programmer's Guide. (JBuilder Professional and Enterprise)
Without a debugger, runtime errors can be difficult to locate, because the compiler doesn't tell you anything about them. Often, the only clues you have to work with are the results of the run, such as the screen appearance, and the error message generated by the runtime error.
Although you can find runtime errors by searching through your program source code, the debugger can help you quickly track down these types of errors. Using the debugger, you can run to a specific program location. From there, you can begin executing your program one statement at a time, watching the behavior of your program with each step. When you execute the statement that causes your program to fail, you have pinpointed the error. From there, you can fix the source code, recompile the program, and resume testing your program.
If your program throws a runtime exception, it will print a stack trace in the Console output, input, and errors view. You can double-click a line of the stack trace to go to the line of code in the source file listed in the trace.
In the following example, a character string ("eeee") was entered into an input field instead of a number. A NumberFormatException
was thrown. The source for FloatingDecimal.java
is displayed in the editor; this is the class where the exception was thrown.
Logic errors are often the most difficult type of errors to find because they can show up in places you might not expect. To be sure your program works as designed, you need to thoroughly test all of its aspects. Only by scrutinizing each portion of the user interface and output of your program can you be sure that its behavior corresponds to its design. As with runtime errors, the debugger helps you locate logic errors by letting you monitor the values of your program variables and data objects as your program executes.
One good debugging method involves breaking your program down into different sections that you can systematically debug. By closely monitoring the statements in each program section, you can verify that each area is performing as designed. If you find a programming error, you can correct the problem in your source code, recompile the program, and then resume testing.
By default, JBuilder includes symbolic debug information when you compile. To be sure that this option is set for the current project,
To set this option for all new projects, choose Project|Default Project Properties and select the Include Debug Info option on the Build page. (Setting the default project properties does not affect existing projects.)
You can still debug if you leave the Include Debug Info option off. Without the debugging information, the this object is still available for debugging.
When you generate symbolic debug information, the compiler stores this information in the associated .class file. This can make the .class file substantially larger than compiling without debugging information. You may want to turn this option off before deployment.
To make compiling before debugging automatic, choose the Compile Before Debugging option on the Run page of the Project Properties dialog box. This option automatically compiles your project before running it under the debugger's control. If this option is not selected, JBuilder will not compile your program before debugging, so that your source files and class files can be out of sync. If this option is off, use the Project|Make command first.
Once you've compiled your project with debug information, you can start the debugger with one of the following menu options.
Command | Shortcut | Description |
---|---|---|
Run|Debug Project | Shift + F9 or ![]() |
Starts the program in the debugger, suspending execution at a breakpoint or at the first line of code where user input is required, which ever comes first. |
Run|Step Over | F8 | Suspends execution at the first line of executable code. |
Run|Step Into | F7 | Suspends execution at the first line of executable code. |
If you haven't yet selected the main class for your program, the Run page of the Project Properties dialog box will be displayed before the debugging session begins. For applications, choose the class that contains the main()
method. For applets, choose the class that contains the init()
method or the applet's HTML file.
To debug a particular class in your project, and not the entire project, choose the file in the navigation pane, right-click and choose Debug.
Each time you start the debugger, you are starting a debugging session. For more information, see "Debugging sessions."
When you run your program under the control of the debugger, it behaves as it normally would - your program creates windows, accepts user input, calculates values and displays output. The debugger can pause your program, allowing you to use the debugger views to examine the current state of the program. By viewing the values of variables, the methods on the call stack, and the program output, you can ensure that the area of code you're examining is performing as it was designed to.
As you run your program under the debugger's control, you can watch the behavior of your application in the windows it creates. Position the windows so you can see both the debugger and your application window as you debug. To keep windows from flickering as the focus alternates between the debugger views and those of your application, arrange the windows so they don't overlap.
When you're in the debugger, your program is in one of two possible states: running or suspended.
To resume program execution, choose the Resume Program icon on the debugger toolbar. When the debugging session is over, this icon becomes the Restart Program icon
and restarts the session.
To end the current debugging session and release the program from memory, choose the Reset Program icon .
You can also exit the application to close the debugging session. To remove the debugging session tab, right-click the tab and choose Remove.
Watches, breakpoints and classes with tracing disabled are stored per individual project. All breakpoints and watches apply to all processes in a project. Breakpoints can be selectively disabled for a runtime configuration.
When you use commands on the Run menu other than Run Project, Debug Project and Configurations, you are continuing in the selected debugging session. When you use icons on the debugger toolbar, you are also continuing in the selected session.
To end the current debugging session and release the program from memory, choose the Reset Program icon .
You can also exit the program by right-clicking the debugging session tab and choosing Remove Tab. Although you will be prompted to stop the process before the tab is removed, it's a good idea to use Run|Reset Program first.
The debugger views allow you to look inside your program and see what is going on. You use debugger views to examine and change data values, trace backward and forward through your program, examine the internal processing of a method and the call to that method, and follow an individual thread in your program.
Debugger views are displayed at the bottom of the AppBrowser. To select a view, choose its tab on the left side of the debugger. Views (except the Console output, input, and errors view) can also be displayed as floating windows. Floating windows allow you to see multiple debugger views at the same time, rather than having to switch back and forth between them. (Floating windows are a feature of JBuilder Professional and Enterprise.)
Debugger views also have right-click menus. Commands on these menus often duplicate those on the Run or View menus, and allow you to easily control the debugger.
Additionally, each debugger view displays a variety of glyphs to indicate the state of the selected item. For example, a breakpoint can be disabled, verified, unverified, or invalid - each state is indicated visually by a small glyph in the left margin of the view.
The debugger views, glyphs, and right-click menus are described below.
This view displays output from the program and errors in the program. It also allows you to enter any input that the program requires. The image displayed on the icon changes if there is any output from the program or if any error messages are displayed.
Runtime exceptions are displayed in this view.
Glyph | Description |
---|---|
![]() |
Output messages have been written to the view. |
![]() |
Error messages have been written to the view. |
![]() |
No output in the view. |
Command | Description |
---|---|
Clear All | Clears all messages in the view. |
Copy Content | Copies the contents of the view to the Clipboard. |
This is a feature of JBuilder Professional and Enterprise.
This view displays an alphabetically ordered list of classes and packages not to step into. This information is available before you begin debugging from the Run|View Classes With Tracing Disabled command.
By default, when you begin a debugging session, tracing into all classes displayed in the view is disabled. This prevents the debugger from tracing into the libraries that are provided with JBuilder, as well as the JDK classes, allowing you to concentrate on your code, rather than on code that has already been debugged.
For information about controlling what classes are traced into, see "Controlling which classes to trace into."
Glyph | Description |
---|---|
![]() |
Tracing is disabled for the selected class or package. |
![]() |
Tracing is enabled for the selected class or package. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Add Class or Package | Displays the Disable Tracing dialog box, where you choose the class or package to add to the view. This prevents the debugger from tracing into that class or package. This command is available when you right-click an empty area of the view. |
Remove All | Removes all classes and packages from the view. All packages and classes, including those JBuilder and JDK, will be traced into. This command is available when you right-click an empty area of the view. |
Step Into Class/Package | Allows the selected class or package to be traced into. If you select a package, all classes in that package will be stepped into. |
Remove Class/Package | Removes the selected class or package from the view. This allows the selected class or package to be traced into. |
This view shows all the breakpoints set in the file and their current state. This information is also available before you begin debugging with the View|Breakpoints command.
For more information about breakpoints, see "Using breakpoints."
Glyph | Description |
---|---|
![]() |
An unverified breakpoint. |
![]() |
A verified breakpoint. |
![]() |
An invalid breakpoint. |
![]() |
A disabled breakpoint. |
![]() |
A field breakpoint. A field is a Java variable that is defined in a Java object. |
![]() |
A breakpoint that has been disabled for a configuration. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Add Line Breakpoint | Displays the Add Line Breakpoint dailog box, where you add a line breakpoint. |
Add Exception Breakpoint | Displays the Add Exception Breakpoint dailog box, where you add an exception breakpoint. (JBuilder Professional and Enterprise) |
Add Class Breakpoint | Displays the Add Class Breakpoint dailog box, where you add a class breakpoint. (JBuilder Professional and Enterprise) |
Add Method Breakpoint | Displays the Add Method Breakpoint dailog box, where you add a method breakpoint. (JBuilder Professional and Enterprise) |
Add Cross-Breakpoint Breakpoint | Displays the Add Cross-Breakpoint dailog box, where you add a cross-process breakpoint. (JBuilder Enterprise) |
Go To Breakpoint | Goes to the selected breakpoint in the source code. This is useful if several files are open in the editor and you want to quickly locate the breakpointed line of code. This command is available when a breakpoint is selected. |
Enable Breakpoint | Enables the selected breakpoint. |
Disable For Configuration | Disables the selected breakpoint for the selected configuration. This command is only available if you have configured one or more runtime configurations. By default, every breakpoint is applied to all defined configurations. This command is available when a breakpoint is selected. (JBuilder Professional and Enterprise) |
Remove Breakpoint | Removes the selected breakpoint. |
Breakpoint Properties | Displays the Breakpoint Properties dialog box, where you set properties for the selected breakpoint. |
Disable All | Disables all breakpoints. |
Enable All | Enables all breakpoints. |
Remove All | Removes all breakpoints. |
Break On Read | Forces the debugger to stop when the selected field breakpoint is about to be read. A field is a Java variable that is defined in a Java object. This command is available when a field is selected. (JBuilder Professional and Enterprise) |
Break On Write | Forces the debugger to stop when the selected field breakpoint is about to be written to. A field is a Java variable that is defined in a Java object. This command is available when a field is selected. (JBuilder Professional and Enterprise) |
This view displays the current status of all thread groups in your program. Each thread group expands to show its threads and contains a stack frame trace representing the current method call sequence. Each stack frame expands to show available data elements that are in scope. Glyphs visually indicate the type of data element. (Static data is not displayed in this view, but is displayed in the Loaded classes and static data view.) Items that are dimmed are inherited.
The default display of this view is split into two panes. The left side of the view can expand to show stack frames. The right side displays the content of the item selected on the left, allowing the right side to show anything from a thread group to a variable. For example, if a thread is selected in the left view, the right side of the view will show the stack frames for that thread. Alternatively, if a stack frame is selected in the left view, the right view will show the variables available in that view. (This is a feature of JBuilder Professional and Enterprise.)
For more information about threads, see "Managing threads."
Glyph | Description |
---|---|
![]() |
The current stepping thread. |
![]() |
A thread group. |
![]() |
A blocked thread. |
![]() |
A suspended thread. |
![]() |
A dead thread. |
![]() |
A class. |
![]() |
An interface. |
![]() |
An object. |
![]() |
A null object. |
![]() |
A method call. |
![]() |
An array. |
![]() |
A primitive. |
![]() |
An error. |
![]() |
An informational message. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Show Current Thread Only | Displays call stacks and data for the current thread only. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Split Threads And Data View | Splits the display into a two-paned view. Left side of the view expands to show stack frames; right side shows the content of the item selected on the left. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Keep Thread Suspended | This thread will not be resumed when Run|Resume Program is selected. Allows you to watch behavior of selected threads. This command is available when a thread is selected. (JBuilder Enterprise) |
Cut | Removes an object variable and puts it in the clipboard. This command is available when an object is selected. (JBuilder Professional and Enterprise) |
Copy | Copies an object variable to the clipboard. This command is available when an object is selected. (JBuilder Professional and Enterprise) |
Paste | Pastes an object variable into another object. When the Paste command is used, both the cut or copied variable and the pasted variable point to the same object. This command is available when an object is selected. (JBuilder Professional and Enterprise) |
Create Local Variable Watch | Displays the Add Watch dialog box, where you create a watch on the selected local variable. The watch is added to the Data watches view. This command is available when a variable or variable array is selected. |
Create Array Watch | Displays the Add Watch dialog box, where you create a watch on the selected array. The watch is added to the Data watches view. This command is available when an array is selected. |
Adjust Display Range | Displays the Adjust Range dialog box, where you can reduce the number of array items that are displayed in the view. This command is available when an array is selected. |
Show/Hide Null Values | Toggles the display of a null values in an array. This command is useful when debugging a hash-map object. It is available when an array of type Object is selected. (JBuilder Professional and Enterprise) |
Create 'This' Watch | Displays the Add Watch dialog box, where you create a watch on the selected this object. The watch is added to the Data watches view. This command is available when a this object is selected. |
Create Object Watch | Displays the Add Watch dialog box, where you create a watch on the selected object. The watch is added to the Data watches view. This command is available when an object is selected. An object watches watches the selected Java object. It expands to show data members for the current instantiation. |
Change Value | Displays the Change Value dialog box, where you can directly edit the value of a String or any primitive data type, including numbers and Booleans. This command is available when a primitive data type is selected. (JBuilder Professional and Enterprise) |
Create Field Watch | Displays the Add Watch dialog box, where you create a watch on the selected field. A field is a Java variable that is defined in a Java object. The watch is added to the Data watches view. This command is available when a field is selected. |
Create Field Breakpoint | Displays the Add Field Breakpoint dialog box, where you create breakpoint on the selected field. A field is a Java variable that is defined in a Java object. To activate the breakpoint, go to the Data and code breakpoints view and right-click the breakpoint. Choose Break On Read to force the debugger to stop when the field is about to be read, or Break On Write to stop when the field is about to be written to. This command is available when a field is selected. (JBuilder Professional and Enterprise) |
Show Hex/Decimal Value | Changes the display base of a numeric or character variable. This command is available when a numeric or character variable is selected. Selecting this command for an array will change the base of its elements. |
This view displays the current values of data members that you want to track. You can expand some types of watch expressions to show data elements that are in scope. Grayed-out items are inherited.
For more information on data watches, see "Watching expressions."
Glyph | Description |
---|---|
![]() |
A class. |
![]() |
An interface. |
![]() |
An object. |
![]() |
A null object. |
![]() |
An array. |
![]() |
A primitive. |
![]() |
An error. |
![]() |
An informational message. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Add Watch | Displays the Add Watch dialog box, where you can add a watch expression. This command is available when you right-click an empty area of the view. |
Remove All | Removes all watches. This command is available when you right-click an empty area of the view. |
Remove Watch | Removes the selected watch. |
Create Local Variable Watch | Displays the Add Watch dialog box, where you create a watch on the selected local variable. This command is available when a variable or variable array is selected. |
Create Array Watch | Displays the Add Watch dialog box, where you create a watch on the selected array. This command is available when an array is selected. |
Adjust Display Range | Displays the Adjust Range dialog box, where you can reduce the number of array items that are displayed in the view. This command is available when an array is selected. |
Show/Hide Null Values | Toggles the display of a null values in an array. This command is useful when debugging a hash-map object. It is available when an array of type Object is selected. (JBuilder Professional and Enterprise) |
Create 'This' Watch | Displays the Add Watch dialog box, where you create a watch on the selected this object. This command is available when a this object is selected. |
Create Object Watch | Displays the Add Watch dialog box, where you create a watch on the selected object. This command is available when an object is selected. |
Change Value | Displays the Change Value dialog box, where you can directly edit the value of a string or any primitive data type, including numbers and Booleans. This command is available when a primitive data type is selected. (JBuilder Professional and Enterprise) |
Create Field Watch | Displays the Add Watch dialog box, where you create a watch on the selected field. A field is a Java variable that is defined in a Java object. This command is available when a field is selected. |
Create Field Breakpoint | Displays the Add Field Breakpoint dialog box, where you create breakpoint on the selected field. A field is a Java variable that is defined in a Java object. To activate the breakpoint, go to the Data and code breakpoints view and right-click the breakpoint. Choose Break On Read to force the debugger to stop when the field is about to be read, or Break On Write to stop when the field is about to be written to. This command is available when a field is selected. (JBuilder Professional and Enterprise) |
Change Watch Expression | Displays the Change Watch dialog box where you change the watch expression and description. |
Change Watch Description | Displays the Change Watch dialog box where you change the watch expression and description. |
This view displays the classes currently loaded by the program. Expanding a class shows static data, if any, for that class. If a package is displayed in the tree, the number of classes loaded for that package is displayed.
Classes in this view that contain $ followed by a number represent inner classes. Inner classes are created by the compiler for event handlers defined as Anonymous Adapters on the Code Style page of the Project Properties dialog box.
For more information, see "How variables are displayed in the debugger."
Glyph | Description |
---|---|
![]() |
A package. |
![]() |
A class. |
![]() |
An interface. |
![]() |
A locked class. |
![]() |
An object. |
![]() |
A null object. |
![]() |
An array. |
![]() |
A primitive. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
This is a feature of JBuilder Enterprise.
This view shows synchronization monitors used by the threads and their current state, useful for detecting deadlocked situations.
-classic
in the VM Parameters field.
For more information about threads, see "Managing threads."
Glyph | Description |
---|---|
![]() |
Synchronization monitor used by specified thread is not locked. |
![]() |
Synchronization monitor used by specified thread is locked. |
Command | Description |
---|---|
Floating Window | Turns the view into a floating window. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
Restore Default View Order | Restores the default order of the debugger views. This command is available when you right-click an empty area of the view. (JBuilder Professional and Enterprise) |
The toolbar at the bottom of the debugger provides quick access to stop, restart/resume, and pause icons, as well the Smart Step icon, the stepping icons, and the Add Breakpoint, Add Watch, and Show Current Frame icons. The right side of the toolbar, the debugger status bar, displays status messages.
The table below explains in detail the toolbar icons.
Icon | Action | Description |
---|---|---|
![]() |
Reset Program | Ends the current application run and releases it from memory. This is the same as Run|Reset Program. |
![]() ![]() |
Restart/Resume Program | Continues the current debugging session or restarts one that has finished or been reset. This is the same as Run|Resume Program. |
![]() |
Pause Program | Pauses the current debugging session. This is the same as Run|Pause Program. |
![]() |
Smart Step | Controls whether to use the Smart Step settings in the Classes with tracing disabled view and the Smart Step options on the Debug page of the Project Properties dialog box. This is a feature of JBuilder Professional and Enterprise. |
![]() |
Step Over | Steps over the current line of code. This is the same as Run|Step Over. |
![]() |
Step Into | Steps into the current line of code. This is the same as Run|Step Into. |
![]() |
Step Out | Steps out of the current method and returns to its caller. This is the same as Run|Step Out. |
![]() |
Add Breakpoint | Adds a breakpoint to the current debugging session. Click the down-facing arrow to the right of the icon to choose the breakpoint type. This is the same as Run|Add Breakpoint. |
![]() |
Add Watch | Adds a watch to the current debugging session. This is the same as Run|Add Watch. |
![]() |
Show Current Frame | Displays the current thread's call stack and highlights the current execution point in the source. |
Keys | Action |
---|---|
Shift+F9 | Debug project |
Ctrl+F2 | Reset program |
F4 | Run to cursor |
F5 | Toggle breakpoint when in editor |
F7 | Step into |
F8 | Step over |
F9 | Resume program (continues the current debug session) |
Ctrl+right-mouse click in gutter on breakpoint | Displays Breakpoint Properties dialog box |
Ctrl+right-mouse click in editor on expression | Brings up ExpressionInsight window for that expression |
This is a feature of JBuilder Professional and Enterprise.
The ExpressionInsight window allows you to descend into members of the expression. If the expression is an object, the right-click menu displays the same menu commands as those available in the Threads, call stacks and data view when an object is selected.
The ExpressionInsight window is disabled when the debugging session is ended or not suspended.
This is a feature of JBuilder Professional and Enterprise.
Tool tips are disabled when the debugging session is ended or not suspended.