Using breakpoints
A breakpoint that is set on a line of code pauses the execution at that line. By setting breakpoints in potential problem areas of your source code, you can run your program without pausing until the program's execution reaches a location you want to debug.
When your program execution encounters a breakpoint, the program pauses, and the Debugger displays the line containing the breakpoint in the Source pane. You can then use the Debugger to view the state of your program. Breakpoints are flexible in that they can be set before you begin a program run or at any time that the Debugger has control. Conditional breakpoints do not need to be set on a particular line of code, but can pause the Debugger when a certain condition is met.
Setting breakpoints
To set a breakpoint, do one of the following:
- In the Source pane, click in the left margin next to a line of code.
- In the Source pane, select a line. Then, right-click and select Toggle Breakpoint.
- In the Source pane, select a line. Then, choose Run|Add Breakpoint.
- In the Source pane, select a line. Then, choose View|Breakpoints to open the Breakpoints List window. Right-click and choose Add Breakpoint.
- Choose Run|Add Breakpoint and type the source-code line number in the Line Number box.
When you set a breakpoint on a valid line (an executable line of code), the line on which the breakpoint is set becomes highlighted, and a red circle glyph with a checkmark
appears in the left margin of the breakpointed line.
Setting breakpoints after starting a program
While your program is running under the Debugger, you can set a breakpoint. Your program will pause when it reaches the breakpoint.
Valid and invalid breakpoints
A small blue dot
to the left of a line of code in the Source pane indicates that a breakpoint can be set on that line. For a breakpoint to be valid, it must be set on an executable line of code. Breakpoints set on comment lines, blank lines, declarations, or other non-executable lines of code are invalid and become disabled when you run your program.
Use the Breakpoints List window (View|Breakpoints) to see if any breakpoints are invalid.
Resolving invalid breakpoints
If you set an invalid breakpoint, you see the following message when you run the program:
Some breakpoints set on lines that do not contain debug information.
You can ignore the message, and the breakpoint is set to Disabled when you run your program. To prevent the message from appearing, delete the invalid breakpoint from the Breakpoints List window and set another breakpoint on a valid line.
Viewing the breakpoint list
To see the list of breakpoints, choose View|Breakpoint. The Breakpoints List window is displayed.
Disabling and enabling breakpoints
Disabling a breakpoint hides the breakpoint from the current program run. When you disable a breakpoint, all the breakpoint settings remain defined, but the breakpoint is hidden from the execution of your program - your program will not stop on a disabled breakpoint. Disabling a breakpoint is useful if you have defined a conditional breakpoint that you don't need to use now, but might need to use at a later time:
- To disable a breakpoint, open the Breakpoints List window and highlight the breakpoint you want to disable, then right-click and select Disable Breakpoint.
- To disable all current breakpoints, right-click and select Disable All Breakpoints in the Breakpoints List window.
- To enable a breakpoint that is disabled, right-click on the breakpoint in the Breakpoints List window, and select Enable Breakpoint.
- To enable all breakpoints that have been set, right-click in the Breakpoints List window, and select Enable All Breakpoints.
Deleting breakpoints
When you no longer need to examine the code at a breakpoint location, you can delete the breakpoint from the debugging session. You can delete breakpoints using either the Source pane or the Breakpoints List window.
Use any of the following methods to delete breakpoints:
- In the Source pane, place the text cursor in the line containing the breakpoint, right-click and choose Toggle Breakpoint.
- From the Breakpoints List window, highlight the breakpoint you want removed, then select Delete Breakpoint from the popup menu.
- To delete all currently set breakpoints, select Delete All Breakpoints from the Breakpoints popup menu.
Caution: The breakpoint delete commands are not reversible.
Viewing code at a breakpoint
If a breakpoint isn't displayed in the Source pane, you can use the Breakpoints List window to quickly find the breakpoint's location in your source code.
To use the Breakpoints List window to locate a breakpoint:
- In the Breakpoints List window, select a breakpoint.
- Right-click, and select Go To Breakpoint.
The Source pane is updated to show the breakpoint's location.
Locating breakpoints
If a breakpoint is not visible in the Source pane, you can use the Breakpoints List window to quickly locate the breakpoint in your source code.
To scroll the Source pane to the location of a breakpoint, right-click the breakpoint in the Breakpoints List window and select Goto Breakpoint.
Modifying breakpoint options
To view and modify the options of a breakpoint:
- In the Breakpoints List window, select a breakpoint.
- Right-click, and select Options.
The Breakpoint Options dialog box appears, with a Breakpoint Definition page and an Action page.
You can use the Breakpoint Options dialog box to:
- Select the type of breakpoint (source line or exception)
- Change the source location or exception type of a breakpoint
- Set a conditional breakpoint
- Set the threads to which the breakpoint will apply
- Set a pass count for the breakpoint
- Give the breakpoint a name
- Assign the breakpoint to a group of breakpoints
- Choose whether to have the breakpoint write to the Execution Log window.
- Choose which action the breakpoint will produce.
The Breakpoint Definition page for a source breakpoint:
The Action page for both source breakpoints and exception breakpoints:
Creating conditional breakpoints
When a breakpoint is first set, by default it pauses the program execution each time the breakpoint is encountered. However, using the Breakpoint Options dialog box, you can customize breakpoints so that they are activated only in certain conditions.
You can make a breakpoint conditional, based on:
- Boolean expressions
- Pass counts
- Thread ID
Setting the breakpoint condition
The Condition edit box in the Breakpoint Options dialog lets you enter an expression that is evaluated each time the breakpoint is encountered during the program execution. If the expression evaluates to True (or not zero), then the breakpoint pauses the program run. If the condition evaluates to False (or zero), then the Debugger does not stop at the breakpoint location.
Conditional breakpoints let you see how your program behaves when a variable falls into a certain range or what happens when a particular flag is set.
For example, suppose you want a breakpoint to pause on a line of code only when the variable mediumCount is greater than 10. To do so:
- Set a breakpoint on a line of code, by clicking to the left of the line in the Source pane.
- Open the Breakpoints List window by selecting View|Breakpoints.
- Open the Breakpoint Options dialog box by selecting the breakpoint you just set, right-clicking, and selecting Options.
- Enter the following expression into the Condition edit box, and click OK:
mediumCount > 10
You can enter any valid Java language expression into the Condition edit box, but all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain any method calls.
Using pass count breakpoints
The Pass Count condition specifies the number of times that a breakpoint must be passed for the breakpoint to be activated. The debugger pauses the program the nth time that the breakpoint is encountered during the program run. The default value of n is 1.
The pass count number is visibly decremented each time the breakpointed line of code is encountered during the program execution. If the pass count equals 1 when the breakpoint line is encountered, the breakpoint is activated, and the program pauses at that line.
Pass counts are useful when you think that a loop is failing on the nth iteration. Or, if you can't tell on which iteration the loop fails, you can set the pass count to the maximum loop count and run your program. When the program fails, look at the number remaining in the Pass Count field, and subtract from the original number to see how many times the program went through the loop.
When pass counts are used together with Boolean conditions, the breakpoint pauses the program execution the nth time that the condition is true; the Boolean condition must be true for the pass count to be decremented.
Using exception breakpoints
Breakpoints are typically attached to a particular line of code - they pause the Debugger when a particular line of code is about to be executed. You can also set a breakpoint to be activated when a certain type of exception is thrown. Exception breakpoints are not associated with a particular line of code.
If an unhandled exception occurs in your program, the program stops executing, and the exception stack trace is dumped to the task console window.
The task console window display depends on whether you are running in the Debugger:
- If you are not running in the Debugger, this exception stack trace appears in the java.exe task window, which usually closes before you can read it.
- If you are running in the Debugger, the exception stack trace goes to the BCWDBJKV window, which persists until you terminate the debug session. The stack trace tells you which lines in what methods of what classes were running when the exception occurred. From this information you can find the appropriate source lines to examine in your code to determine why the exception occurred.
You can control how exceptions are handled while you are debugging. If an exception occurs during a debugging session, a message dialog appears. When you click OK to close the dialog box, your program run continues and you can continue to debug your program. The Source pane appears, with the execution point positioned on the line of code that caused the exception.
To set an exception breakpoint:
- Choose Run|Add Breakpoint to open the Breakpoint Options dialog box.
- Select the Exception Breakpoint radio button.
The Breakpoint Definition page for exception breakpoints appears.
- For the Exception Breakpoint Type, choose the type of exception you want to break on.
- If desired, specify other options such as Condition, Thread Options, or Pass Count.
- Click OK.
The Debugger will now pause if an exception of the specified type is thrown.
Using breakpoint groups
You can enable or disable several breakpoints with a single action, by putting breakpoints into a breakpoint group.
Creating and deleting breakpoint groups
To put an existing breakpoint into a breakpoint group:
- Choose View|Breakpoints to open the Breakpoints List window.
- Select the breakpoint.
- Right-click and select Options.
- Enter a name in the Group Name field, and click OK.
To create a breakpoint and put it in a breakpoint group:
- Choose Run|Add Breakpoint.
The Breakpoint Options dialog box appears.
- Enter a name in the Group Name field, and click OK.
To remove a breakpoint from a group without deleting the breakpoint:
- Choose View|Breakpoints to open the Breakpoints List window.
- Select the breakpoint.
- Right-click and select Options.
The Breakpoint Options dialog box appears.
- Clear the Group Name field, and click OK.
To remove a breakpoint group and all the breakpoints in it:
- Choose View|Breakpints to open the Breakpoints List window.
- Select the breakpoint group.
- Right-click, and select Remove Group.
Disabling or enabling a breakpoint group
To disable or enable a group of breakpoints:
- Choose View|Breakpoints.
- Select the breakpoint group.
- Right-click, and select Disable Group (or Enable Group).
To disable or enable a group of breakpoints when another breakpoint occurs:
- Choose View|Breakpoints to open the Breakpoints List window appears.
- Select a breakpoint.
- Right-click, and select Options.
The Breakpoint Options dialog box appears.
- In the Group Name box on the Breakpoint Definition page choose a breakpoint group name.
- On the Action page select the Disable A Group Of Breakpoints radio button. Enter the breakpoint group name.