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:

When you set a breakpoint, the line on which the breakpoint is set becomes highlighted, and a red circle glyph 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 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 View Breakpoints window to see if any breakpoints are invalid.

Resolving invalid breakpoints

Breakpoints must be set on executable lines of code. A breakpoint set on a comment, a blank line, or declaration is invalid. If you set an invalid breakpoint, you get an "Invalid breakpoint" message when you run the program. You can ignore the "Invalid breakpoint" 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 window and set another breakpoint on a valid line.

Viewing the breakpoint list

To see the list of breakpoints, select View|Breakpoint. The Breakpoints window appears.

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:

  1. Open the Breakpoints window and highlight the breakpoint you want to disable.
  2. Right-click, and select Disable Breakpoint.
To disable all current breakpoints:

To enable a breakpoint that is disabled:

To enable all breakpoints that have been set:

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 window:

Use any of the following methods to delete breakpoints:

Caution about deleting breakpoints:
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 window to quickly find the breakpoint's location in your source code.

To use the Breakpoints window to locate a breakpoint:

  1. In the Breakpoints window, select a breakpoint.
  2. 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 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 window and select Goto Breakpoint.

Modifying breakpoint options

To view and modify the options of a breakpoint:
  1. In the Breakpoints window, select a breakpoint.
  2. 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:

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:

Setting the breakpoint condition

The Condition edit box in the Breakpoint Options dialog box 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:

  1. Set a breakpoint on a line of code, by clicking to the left of the line in the Source pane.
  2. Open the Breakpoints window by selecting View|Breakpoints.
  3. Open the Breakpoint Options dialog box by selecting the breakpoint you just set, right-clicking, and selecting Options.
  4. 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. Instead, you can 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. 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:

  1. Select Run|Add Breakpoint to open the Breakpoint Options dialog box.
  2. Select the Exception Breakpoint radio button.
    The Breakpoint Definition page for exception breakpoints appears.

  3. In the Exception Type field, enter the type of exception you want to break on.
  4. If desired, specify other options such as Condition, Thread Options, Pass Count, and Action.
  5. 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:
  1. Select View|Breakpoints.
  2. Select the breakpoint.
  3. Right-click, and select Options.
  4. Enter a name in the Group Name field, and click OK.

To create a breakpoint and put it in a breakpoint group:

  1. Select Run|Add Breakpoint.
    The Breakpoint Options dialog box appears.
  2. Enter a name in the Group Name field, and click OK.

To remove a breakpoint from a group without deleting the breakpoint:

  1. Select View|Breakpoints.
  2. Select the breakpoint.
  3. Right-click, and select Options.
  4. Clear the Group Name field, and click OK.

To remove a breakpoint group and all the breakpoints in it:

  1. Select View|Breakpints.
  2. Select the breakpoint group.
  3. Right-click, and select Remove Group.

Disabling or enabling a breakpoint group

To disable or enable a group of breakpoints:
  1. Select View|Breakpoints.
  2. Select the breakpoint group.
  3. Right-click, and select Disable Group (or Enable Group).

To disable or enable a group of breakpoints when another breakpoint occurs:

  1. Select View|Breakpoints.
    The Breakpoints window appears.
  2. Select a breakpoint.
  3. Right-click, and select Options.
    The Breakpoint Options dialog box appears.
  4. In the Group Name choice menu, select a breakpoint group name.
  5. In the action section, select the Disable A Group Of Breakpoints radio button.