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:
- A line breakpoint is set on a specific line of source code. The debugger stops on that line.
- An exception breakpoint causes the debugger to stop when the specified exception is about to be thrown.
- A class breakpoint causes the debugger to stop when any method from the specified class is called or when the specified class is instantiated.
- A method breakpoint causes the debugger to stop when the specified method in the specified class is called.
- A field breakpoint causes the debugger to stop when the specified field is about to be read or written to. A field is a Java variable that is defined in a Java object.
- A cross-process breakpoint causes the debugger to stop when either any method or the specified method in the specified class in a separate process are stepped into.
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:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Line Breakpoint.
- When you're in a debugging session, click the down-facing arrow to the right of the Add Breakpoint icon
on the debugger toolbar and choose Add Line Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Line Breakpoint.
The Add Line Breakpoint dialog box is displayed.
To set a line breakpoint, choose the following options:
- 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.
- If the file is a .class file, either enter the name or choose the ellipsis button to browse to a .class file.
- If the file is not a .class file, choose the ellipsis button to browse to the file.
- In the Line Number field, enter the number of the line to set the breakpoint on.
- 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."
- In the Condition field, set the breakpoint condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
- 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."
- 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:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Exception Breakpoint.
- When you're in a debugging session, click the down-facing arrow to the right of the Add Breakpoint icon
on the debugger toolbar and choose Add Exception Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Exception Breakpoint.
The Add Exception Breakpoint dialog box is displayed.
To set an exception breakpoint,
- 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.
- Choose when the debugger should stop:
- Select the Caught option to force the debugger to stop when the exception is caught.
- Select the Uncaught option to force the debugger to stop when the exception is not caught.
You can also choose both Caught and Uncaught to force the debugger to stop in both cases.
- 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."
- In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
- 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."
- 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:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Class Breakpoint.
- When you're in a debugging session, click the down-facing arrow to the right of the Add Breakpoint icon
on the debugger toolbar and choose Add Class Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Class Breakpoint.
The Add Class Breakpoint dialog box is displayed.
To set a class breakpoint,
- 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.
- 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."
- In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
- 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."
- 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:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Method Breakpoint.
- When you're in a debugging session, click the down-facing arrow to the right of the Add Breakpoint icon
on the debugger toolbar and choose Add Method Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Method Breakpoint.
The Add Method Breakpoint dialog box is displayed.
To set a method breakpoint,
- 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.
- 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.
- 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.
- 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."
- In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
- 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."
- 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,
- Start the server process on the remote computer in debug mode.
- On the client computer, from within JBuilder, attach to the server already running on the remote computer.
- 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:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Cross-Process Breakpoint.
- When you're in a debugging session, click the
down-facing arrow to the right of the Add Breakpoint icon
on the debugger toolbar and choose Add Cross-Process Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Cross-Process Breakpoint.
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,
- 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.
- 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.
- 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.
- If you don't specify any arguments, the debugger stops at all methods with the specified method name.
- If you choose a method name from the Select Method dialog box, the Methods Argument field is automatically filled in.
- 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."
- In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints."
- 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."
- Click OK to close the dialog box.
- Set a line breakpoint in the client on the method that calls the cross-process breakpoint.
- 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,
- Open the Data and code breakpoints view.
- 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.
- 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.
- If the condition evaluates to true, the debugger will stop at the breakpoint location if the Stop Execution option is on.
- If the condition evaluates to false, 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 suspend execution 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 editor.
- Right-click and choose Breakpoint Properties.
- 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:
- To disable a single breakpoint, right-click it in the Data and code breakpoints view. Choose Enable Breakpoint to toggle the command and disable the breakpoint. When this toggle is off, the breakpoint is disabled and will not be stopped at. When it is on, the breakpoint is enabled and will be stopped at. Breakpoints are enabled by default.
- To disable or enable all breakpoints set for a debugging session, open the Data and code breakpoints view. Right-click an empty area of the view and choose Disable All or Enable All.
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:
- In the editor, place the cursor in the line containing the breakpoint, press F5 or right-click and choose Toggle Breakpoint.
- From the Data and code breakpoints view, highlight the breakpoint you want removed, right-click, and choose Remove Breakpoint or press Delete.
- To delete all breakpoints set for a debugging session, open the Data and code breakpoints view. Right-click an empty area of the view and choose Remove All.
- Select a group of breakpoints in the Data and code breakpoints view and press Delete.
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,
- In the Data and code breakpoints view, select a line breakpoint.
- Right-click, and select Go To Breakpoint. You can also double-click the selected breakpoint.
The editor shows the breakpoint's location.