Debugging Java programs

Debugging is the process of locating and fixing errors in your program. JBuilder's integrated debugger lets you debug within the JBuilder environment. Many debugger features are accessed through the Run menu. You can also use the right-click menus, both in the editor and in the debugger, to access debugger features.

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:


Types of errors

The debugger can help find runtime errors and logic errors. If you find or suspect a program runtime or logic error, you can begin a debugging session by running your program under the control of the debugger.

Runtime errors

If your program successfully compiles, but gives runtime exceptions or hangs when you run it, you've encountered a runtime error. Your program contains valid statements, but the statements cause errors when they're executed. For example, your program might be trying to open a nonexistent file, or it might be trying to divide a number by zero.

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.

Runtime error in debugger

Logic errors

Logic errors are errors in design and implementation of your program. Your program statements are valid (they do something), but the actions they perform are not the actions you had in mind when you wrote the code. For example, logic errors can occur when variables contain incorrect values, when graphic images don't look right, or when the output of your program is incorrect.

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.


Overview of the debugging process

After program design, program development consists of cycles of program coding and debugging. Only after you thoroughly test your program should you distribute it. To ensure that you test all aspects of your program, it's best to have a thorough test and debug plan.

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.

Note: You can debug with any JDK that supports the JPDA debugging API. Usually, you will debug with the version of the JDK that JBuilder ships with.

Compiling the project with symbolic debug information

Before you can begin a debugging session, you need to compile your project with symbolic debug information. Symbolic debug information enables the debugger to make connections between your program's source code and the Java bytecode that is generated by the compiler.

By default, JBuilder includes symbolic debug information when you compile. To be sure that this option is set for the current project,

  1. Select Project|Project Properties to open the Project Properties dialog box.
  2. On the Build page, make sure the Include Debug Info option is checked.

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.

Note: You won't be able to view variable information in the Java API classes because they were not compiled with debug information. You can, however, trace into these classes. To learn how to trace into classes, see "Controlling which classes to trace into."

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.

Starting the debugger

Once you've compiled your project with debug information, you can start the debugger with one of the following menu options.

Menu commands to start debugger

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

Note: To select a debugging configuration for a session, click the down-facing arrow to the right of the Debug Project icon on the main toolbar before you begin. For more information about debugging configurations, see "Creating debugger configurations."

Running under the debugger's control

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.

Pausing program execution

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.

Ending a debugging 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.


The debugger user interface

If the project or class compiles successfully, the debugger is displayed at the bottom of the AppBrowser.

The debugger user interface

Debugging sessions

The debugger allows you to debug multiple processes in multiple debugging sessions. Processes can be in the same JBuilder project, or in different ones. This allows for debugging both a client and a server process at the same time, in the same JBuilder instance.

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.

Debugger views

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.


  Console output, input, and errors view

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.

Glyphs in the Console output, input, and errors view

Glyph Description
Output messages have been written to the view.
Error messages have been written to the view.
No output in the view.

Right-click menu in the Console output, input, and errors view

Command Description
Clear All Clears all messages in the view.
Copy Content Copies the contents of the view to the Clipboard.


  Classes with tracing disabled view

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

Glyphs in the Classes with tracing disabled view

Glyph Description
Tracing is disabled for the selected class or package.
Tracing is enabled for the selected class or package.

Right-click menu in the Classes with tracing disabled view

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.


  Data and code breakpoints view

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

Glyphs in the Data and code breakpoints view

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.

Right-click menu in the Data and code breakpoints view

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)


  Threads, call stacks, and data view

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

Glyphs in the Threads, call stacks, and data view

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.

Right-click menu in the Threads, call stacks, and data view

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.


  Data watches view

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

Glyphs in the Data watches view

Glyph Description
A class.
An interface.
An object.
A null object.
An array.
A primitive.
An error.
An informational message.

Right-click menu in the Data watches view

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.


  Loaded classes and static data view

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

Glyphs in the Loaded classes and static data view

Glyph Description
A package.
A class.
An interface.
A locked class.
An object.
A null object.
An array.
A primitive.

Right-click menu in the Loaded classes and static data view

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)


  Synchronization monitors view

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.

Note: Some VMs don't provide this information. In this case, this view is unavailable. For example, the HotSpot VM doesn't support this feature. To see this view in JBuilder,

For more information about threads, see "Managing threads."

Glyphs in the Synchronization monitors view

Glyph Description
Synchronization monitor used by specified thread is not locked.
Synchronization monitor used by specified thread is locked.

Right-click menu in the Synchronization monitors view

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)


Debugger toolbar

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.

Debugger toolbar

The table below explains in detail the toolbar icons.

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.

Debugger shortcut keys

You can use the following shortcut keys for easy access to debugger functions.

Debugger shortcut keys

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

ExpressionInsight

This is a feature of JBuilder Professional and Enterprise.
When the debugger is suspended, you can access ExpressionInsight - a small, pop-up window that shows, in tree form, the contents of the selected expression. To display the ExpressionInsight window,

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.

ExpressionInsight window

The ExpressionInsight window is disabled when the debugging session is ended or not suspended.

Tool tips

This is a feature of JBuilder Professional and Enterprise.
When the debugger is suspended, you can place the mouse cursor over any variable in the editor to display its value. The value is displayed in a small pop-up window called a tool tip. If you select text, you'll see the value of the selected text.

Tool tip window

Tool tips are disabled when the debugging session is ended or not suspended.