Using breakpoints

When your program execution encounters a breakpoint, the program is suspended, and the debugger displays the line containing the breakpoint in the editor. 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. 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.

Breakpoints are displayed and manipulated in the Data and code breakpoints view. The type of breakpoint and its status are displayed, along with information specific to the breakpoint type, such as line number, class name or method name. You can use the right-click menu to enable and disable breakpoints, as well as add and remove them.

Data and code breakpoints view

Setting breakpoints

Class, method, exception, and field breakpoints are features of JBuilder Professional and Enterprise. Cross-process breakpoints are a feature of JBuilder Enterprise.

You can set line, exception, class, method, field, and cross-process breakpoints in the debugger:

Setting a line breakpoint

A line breakpoint causes the debugger to stop when it reaches that particular line. You can set a line breakpoint directly in the editor or use the Add Line Breakpoint dialog box.

To set a line breakpoint in source code, click the left margin of the line you want to set the breakpoint on. You can also press F5 when on a line of source code to toggle a line breakpoint. When the debugger has focus, small blue dots    are displayed in the editor to the left of lines of executable code, indicating that a breakpoint can be set on that line.

Breakpoints set on comment lines, declarations, or other non-executable lines of code are invalid and become disabled when you run your program. Disabled breakpoints are indicated by    in the gutter of the editor.

To set a line breakpoint using the Add Line Breakpoint dialog box, do one of the following:

The Add Line Breakpoint dialog box is displayed.

To set a line breakpoint, choose the following options:

  1. If you're setting a breakpoint in a Java .class file, use the Class Name field. If the breakpoint is in a file that is not a .class file, use the File Name field.

  2. In the Line Number field, enter the number of the line to set the breakpoint on.

  3. Choose the Actions for the breakpoint. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions."

  4. In the Condition field, set the breakpoint condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."

  5. In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

  6. Click OK to close the dialog box.
    If the breakpoint is valid (set on 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 an exception breakpoint

Exception breakpoints are features of JBuilder Professional and Enterprise.

An exception breakpoint causes the debugger to stop when the specified exception is about to be thrown. The debugger can stop on caught and/or uncaught exceptions. To set an exception breakpoint, use the Add Exception Breakpoint dialog box.

To open the Add Exception Breakpoint dialog box, do one of the following:

The Add Exception Breakpoint dialog box is displayed.

To set an exception breakpoint,

  1. In the Class Name field, enter the name of the exception class file on which the debugger will stop. You can either enter the name or choose the ellipsis button to browse to a .class file.

  2. Choose when the debugger should stop: You can also choose both Caught and Uncaught to force the debugger to stop in both cases.

  3. Choose the Actions for the debugger. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions."

  4. In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."

  5. In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

  6. Click OK to close the dialog box.

Setting a class breakpoint

Class breakpoints are features of JBuilder Professional and Enterprise.

A class breakpoint causes the debugger to stop when any method from the specified class is called or when the specified class is instantiated. To set a class breakpoint, use the Add Class Breakpoint dialog box.

To open the Add Class Breakpoint dialog box, do one of the following:

The Add Class Breakpoint dialog box is displayed.

To set a class breakpoint,

  1. In the Class Name field, enter the name of the class file you want the debugger to stop on. You can either enter the name or choose the ellipsis button to browse to a .class file.

  2. Choose the Actions for the debugger. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions."

  3. In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."

  4. In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

  5. Click OK to close the dialog box.

Setting a method breakpoint

Method breakpoints are features of JBuilder Professional and Enterprise.

A method breakpoint causes the debugger to stop when the specified method in the specified class is called. To set a method breakpoint, use the Add Method Breakpoint dialog box.

To open the Add Method Breakpoint dialog box, do one of the following:

The Add Method Breakpoint dialog box is displayed.

To set a method breakpoint,

  1. In the Class Name field, enter the name of the class that contains the method you want the debugger to stop on. You can either enter the name or choose the ellipsis button to browse to a .class file.

  2. In the Method field, enter the name of the method you want the debugger to stop on. Click the Method button to browse to the method you want.

  3. In the Method Arguments field, enter a comma-delimited list of method arguments. This causes the debugger to stop only when the method name and argument list match. This is useful for overloaded methods. If you used the browser to add the method, method arguments are automatically filled in. If you don't specify any arguments, the debugger stops at all methods with the specified method name.

  4. Choose the Actions for the debugger. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions."

  5. In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."

  6. In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

  7. Click OK to close the dialog box.

Setting a field breakpoint

Field breakpoints are features of JBuilder Professional and Enterprise.

A field breakpoint causes the debugger to stop when the specified field is about to be read or written to, depending on your choices. A field is a Java variable that is defined in a Java object. In the following example:

     class Test {
        private int x;
        private Object y;
     }
     Test myTest = new Test();
myTest is a variable. The Java variables x and y are fields.

To add a field breakpoint, right-click a field variable in the Threads, call stacks, and data view and choose Add Field Breakpoint. The breakpoint is automatically added.

To control whether the debugger breaks on a read or a write action, open the Data and code breakpoints view. Right-click the field breakpoint you just set. By default, the Break On Read and Break On Write commands in the right-click menu are enabled, meaning that the debugger will stop when the specified field is about to be read or written to. You can turn off one or both of these options, allowing the debugger to continue, instead of stop, when the field is about to be read or written to.

Setting a cross-process breakpoint

Cross-process breakpoints are features of JBuilder Enterprise.

A cross-process breakpoint causes the debugger to stop when you step into any method or the specified method in the specified class in a separate process. This allows you to step into a server process from a client process, rather than having to set breakpoints on the the client side and on the server side. You will usually set a line breakpoint on the client side and a cross-process breakpoint on the server side. For a tutorial that walks through cross-process stepping, see the "Remote debugging tutorial".

To activate a cross-process breakpoint set on a server process,

  1. Start the server process on the remote computer in debug mode.
  2. On the client computer, from within JBuilder, attach to the server already running on the remote computer.
  3. Set a line breakpoint in the client code and start debugging the client. At the breakpoint, step into the server code. Do not use Step Over - stepping over will not stop at the cross-process breakpoint.

Note: You can use cross-process breakpoints to debug locally, for example a client/server application running on one computer.

To set a cross-process breakpoint, use the Add Cross-Process Breakpoint dialog box. To open the Add Cross-Process Breakpoint dialog box, do one of the following:

The Add Cross-Process Breakpoint dialog box is displayed.

For a tutorial that explains cross-process stepping, see the tutorial called "Remote debugging tutorial."

To set a cross-process breakpoint,

  1. In the Class Name field, enter the name of the server-side class that contains the method you want the debugger to stop on. You can either enter the name or choose the ellipsis button to browse to a .class file.

  2. In the Method field, enter the name of the method you want the debugger to stop on. Use the Browse button to display the Select Method dialog box where you can browse through the methods available in the selected class. The method name is not required. If you do not specify the method name, the debugger stops at all method calls in the specified class.

    Note: You cannot select a method if the selected class contains syntax or compiler errors.

  3. In the Method Arguments field, enter a comma-delimited list of method arguments. This causes the debugger to stop when the method name and argument list match. This is useful for overloaded methods.

  4. Choose the Actions for the debugger. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions."

  5. In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."

  6. In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

  7. Click OK to close the dialog box.

  8. Set a line breakpoint in the client on the method that calls the cross-process breakpoint.

  9. Click the Step Into icon    on the debugger toolbar to step into the server-side breakpointed method. (If you use Step Over, the debugger will not stop.)

Setting breakpoint properties

Once you've created a breakpoint, you can set or change its properties. To set breakpoint properties,
  1. Open the Data and code breakpoints view.

  2. Choose the breakpoint you want to set properties for. Right-click and choose Breakpoint Properties.
    The Breakpoint Properties dialog box is displayed.
    Note: The Breakpoint Properties dialog box contains the same options as the dialog box you used to create the breakpoint.

  3. You can change the following properties:
    Actions
    The actions to be performed when the breakpoint is hit. The debugger can stop execution at the breakpoint, display a message or evaluate an expression. For more information, see "Setting breakpoint actions."
    Condition
    The condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
    Pass Count
    The number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints."

To display the Breakpoint Properties dialog box in read-only mode, position the mouse in the gutter next to the breakpointed line. Press Ctrl plus the right mouse button. The core properties for the breakpoint are displayed, but they are read-only. You can edit the Actions, Conditions and Pass Count fields.

Setting breakpoint actions

This is a feature of JBuilder Professional and Enterprise.
You can select one more actions to be performed when a breakpoint occurs. The debugger can:

Actions are defined in the middle area of the Breakpoints dialog box.

Breakpoint actions

Stopping program execution

To stop program execution when the specified breakpoint is hit, choose the Stop Execution option. If you stop program execution, the debugger will stop at the specified breakpoint, display a status message on the debugger toolbar, and display the breakpoint in the Data and code breakpoints window.

The exact message displayed in the status bar depends on the type of breakpoint. The following example shows the status bar message for a line breakpoint.

Breakpoint status bar message

Logging a message

To log a message to the Console output, input and errors view when the breakpoint is hit, choose the Log Message option and enter a message in the Evaluate Expression box. When the debugger reaches the selected breakpoint, a message will be logged to the view. If the Stop Execution option is also selected the program will stop. Otherwise, it will continue to run.

Logging a message with a println statement

You can use println statements to log output messages. The following example shows a message in the Code and data breakpoints view that was logged with the statement - System.out.println("Breakpoint at line 204 reached"). The statement was entered in the Evaluate Expression input box and the Log Message option was checked.

Logging a message with expression evaluation

You can also use expression evaluation, instead of println statements, to log messages while debugging. To do this, enter an expression in the Evaluate Expression input field. The debugger will evaluate this expression when the breakpoint is hit and write the results of the evaluation to the Console output, input, and errors view. The expression can be any valid Java language statement.

This option is available only if you select the Log Message option. Note that you can choose to stop program execution when an expression is evaluated, by choosing the Stop Execution option.

The following example shows the results of the expression valueOneText entered in the Evaluate Expression field, with the Log Message option checked.

The Only Log Message option allows you to log only the results of this expression, so that the log is not cluttered with other information.

Creating conditional breakpoints

When a breakpoint is first set, by default it suspends the program execution each time the breakpoint is encountered. However, the Breakpoint Properties dialog box allows you to customize breakpoints so that they are activated only in certain conditions.

By setting a boolean expression in the Condition field, you can make a breakpoint conditional - program execution will stop at this breakpoint only if the condition evaluates to true. You can also base a breakpoint on a pass count, specified in the Pass Count field. This field is useful for debugging loops. Program execution stops at the breakpoint after it passes the loop the specified number of times.

Conditions are defined at the bottom of the Breakpoints dialog box.

Conditional breakpoints

Setting the breakpoint condition

The Condition edit box in the Breakpoint Properties dialog box lets you enter an expression that is evaluated each time the breakpoint is encountered during the program execution.

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 suspend execution 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 editor.
  2. Right-click and choose Breakpoint Properties.
  3. 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.

Using pass count breakpoints

The Pass Count condition in the Breakpoint Properties dialog box specifies the number of times that a breakpoint must be passed in order for the breakpoint to be activated. The debugger suspends the program the nth time that the breakpoint is encountered during the program run. The default value of n is 1.

Pass counts are useful when you think that a loop is failing on the nth iteration. When pass counts are used with boolean conditions, program execution is suspended the nth time the condition is true.

Disabling and enabling breakpoints

Disabling a breakpoint hides it 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:

You can also disable breakpoints for a runtime configuration. If two or more runtime configurations are defined for the current project, the menu command Disable For Configuration will be available when you right-click a breakpoint. You choose the configuration(s) to disable this breakpoint for. When you debug using the specified configuration, the selected breakpoint will be disabled.

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 a line breakpoint in the editor. Delete other types of breakpoints with the Data and code breakpoints view.

Note that you cannot delete the default breakpoint, all uncaught exceptions. You can, however, disable it.

Use any of the following methods to delete breakpoints:

Warning: The breakpoint delete commands are not reversible.

Locating line breakpoints

If a line breakpoint isn't displayed in the editor, you can use the Data and code breakpoints view to quickly find the breakpoint's location in your source code.

To locate a line breakpoint,

  1. In the Data and code breakpoints view, select a line breakpoint.
  2. Right-click, and select Go To Breakpoint. You can also double-click the selected breakpoint.
    The editor shows the breakpoint's location.