Breakpoints

How to Set Breakpoints

JSwat supports setting several types of breakpoints. Typically breakpoints will be set at a particular location in code. These breakpoints can be set in one of several ways. First there is the stop command which can be used to set a breakpoint at a particular method or at a code line in a class. Second, there is the "Set Breakpoint" item in the "Breakpoints" menu. Additionally, the source view can be used to set breakpoints through its popup menu.

For help on using the stop command, type 'help stop' at the command prompt to learn the syntax for the command. To set a breakpoint inside an inner class, use a dollar sign ($) to separate the names of the outer and inner classes. Here are examples of valid breakpoint specifications:

  MyClass:213
  mypackage.MyClass.myMethod(String, int)
  *.ClassName$Inner:41

The first example is setting a breakpoint at line 213 in the class MyClass. The second example demonstrates setting a breakpoint at a method, by giving the method name and argument types. You do not give the argument names, just the argument types, consisting of primitives ("boolean", "byte", "char", "double", "float", "int", "long", "short") and class names. Classes in the "java.lang" package are matched automatically if not fully-qualified (e.g. "String"). The third example uses a wildcard to match one or more classes; it also specifies an inner class.

What Breakpoints Do I Have Set?

Any breakpoints that have been set are assigned numbers. The numbers assigned to a breakpoint remain in effect for the life of the breakpoint. To see the breakpoints and their numbers, use the brkinfo command with no arguments.

To see the breakpoints in a panel, select the "Breakpoints..." tab, found just above the Messages text area. This panel displays the breakpoints in their breakpoint groups. Breakpoints drawn in bold are resolved, while disabled breakpoints are italicised. If the breakpoint label is in plain text (neither bold nor italic), then it is unresolved and enabled.

Breakpoints are also visually displayed in the source view. The breakpoints are indicated by colorizing the source view gutter. See the view help for the details.

How to Disable/Enable Breakpoints

There are no less than four ways to disable and enable breakpoints. The first is through the disable and enable commands. These each take the number of the breakpoint (as described above) to disable or enable.

The second way to disable and enable breakpoints is by using the breakpoints panel. Select the breakpoint you want to change and click one of the buttons on the right side of the panel.

The third way to disable and enable breakpoints is by using the source view. If a source file is displayed which shows breakpoints, you can right click on the line with the breakpoint and a popup menu will appear. This menu has items to disable, enable, and remove breakpoints.

Yet another means of altering breakpoints is by clicking in the source view gutter. See the view help for the details.

How to Clear Breakpoints

There are no less than four ways to clear breakpoints. The first is through the clear command. This takes the number of the breakpoint (as described above) to remove.

The second way to disable and enable breakpoints is by using the breakpoints panel. Select the breakpoint you want to change and click one of the buttons on the right side of the panel.

The third way to clear breakpoints is by using the source view. If a source file is displayed which shows breakpoints, you can right click on the line with the breakpoint and a popup menu will appear. This menu has items to disable, enable, and remove breakpoints.

Yet another means of clearing breakpoints is by clicking in the source view gutter. See the view help for the details.

Grouping Breakpoints

Breakpoints are automatically added to a breakpoint group called "Default". Via the breakpoints panel it is possible to create new breakpoint groups and move breakpoints to that group. Breakpoint groups can be disabled, causing all of the breakpoints contained within them to also be disabled. Re-enabling the group will restore the breakpoints to their original enabled state.

Breakpoint groups can contain other groups, which may contain yet other groups.

Deleting a breakpoint group will delete all of the breakpoints and groups contained therein.

The "Default" breakpoint group cannot be deleted and it will be automatically re-enabled whenever a session is restarted.

Skipping and Expiration

All breakpoints support the notion of skipping and expiration. Skipping means that a breakpoint will be hit but will immediately resume execution of the debuggee VM until the breakpoint has been hit enough times. A skip value of zero means the breakpoint will not skip at all. This is the default.

Expiration is the inverse of skipping, where the breakpoint will halt execution of the VM until the breakpoint expires. An expiration value of zero means the breakpoint will never expire. This is the default.

If the skip value is larger than the expiration value (assuming the expiration value is non-zero), the breakpoint will effectively never halt execution of the debuggee VM.

Manipulating Multiple Breakpoints

Using the breakpoints panel, select all the breakpoints you want to modify, then select the button to modify them. You can enable, disable, and remove multiple breakpoints in this manner.

Breakpoint Conditions

Breakpoints may have one or more conditions assigned to them, allowing you to avoid hitting the breakpoint more often than is necessary. Presently only one type of breakpoint condition is supported, called an "expression" condition. The condition is satisfied when the given boolean expression evaluates to true. The ==, !=, <, >, <=, >=, &&, and || boolean operators are supported. See the Expression Evaluation for more information about expressions.

Breakpoint Monitors

Breakpoints may have one or more monitors assigned to them. A monitor is an action that is "performed" whenever the breakpoint is hit. The breakpoint must be enabled, not skipping, and not expired. Presently only one type of monitor is supported, called a "command" monitor. When this monitor is performed, the named command is executed, just as if you had entered it at the command prompt.

Thread Suspend Policy

Normally when a breakpoint causes execution of the debuggee VM to stop, all of the debuggee threads are suspended. This behavior can be modified with the breakpoints properties dialog. The "Suspend Threads" radio buttons indicate which threads should be suspended when the breakpoint is hit. The "None" and "All" options are obvious. The "Event" option causes only the thread in which the breakpoint event occurred to suspend.

Filters

Location-based breakpoints (line and method) support thread filters. That is, the breakpoint is only considered hit if it occurs on a particular thread or threads. The set of threads can be manipulated using either the breakpoint properties dialog box, or through the filter command.

Thread filters can only be applied when the thread exists at the time the breakpoint is resolved. If a single filter is provided and the chosen thread does not exist, the breakpoint will still cause the debuggee to halt when the breakpoint location is reached.

Traces and exception catches can have both thread and class filters. A class filter causes the trace or catch to only operate when the event occurs within the given class or classes. The set of class can be manipulated using either the breakpoint properties dialog box, or through the filter command.

Other Types of Breakpoints

Class

A class breakpoint is one that halts execution when a particular class has either prepared or unloaded. This type of breakpoint can be created with either the classbrk command or the dialog accessible from the "Class Breakpoint..." menu item in the "Breakpoints" menu. Like trace breakpoints, class breakpoints use class filters to filter on one or more classes. As with all other types of breakpoints, class breakpoints have properties that can be managed via the properties editor dialog.

Thread

A thread breakpoint is one that halts execution when a particular thread has either started or died. This type of breakpoint can be created with either the threadbrk command or the dialog accessible from the "Thread Breakpoint..." menu item in the "Breakpoints" menu. Thread breakpoints can be set for one or all threads. That is, either it stops for a single thread of a given name, or it stops for all threads. As with all other types of breakpoints, thread breakpoints have properties that can be managed via the properties editor dialog.

Watch

A watch breakpoint is one that halts execution when a particular field variable has either been accessed or modified. This type of breakpoint can be created with either the watch command or the dialog accessible from the "Watch Variable..." menu item in the "Breakpoints" menu.

Because watch breakpoints refer to a particular field in a particular class, it is necessary to set the watchpoint when that field is visible. That is, in order for the watchpoint to work, the debugger's current location must be set at a point in your code where the desired field is visible. Otherwise, an error message is printed to the messages panel, and the watchpoint will be disabled. It can be enabled when the current location is properly set. A watchpoint is automatically disabled when the debuggee VM exits or is disconnected.

Watchpoints support object instance filters, in which events will occur only for a specific object instance. This is useful when you want to watch for a field change in just one of many objects of the same class. However, because of the ephemeral nature of objects, this filter only lasts as long as the active session. When the session deactivates, the instance filter is automatically erased. A new watchpoint will have to be created from that point forward.

If the debuggee VM does not support instance filters, any watched field will be for all object instances. This is not terribly useful in which case you should avoid using watchpoints. See the support command to determine which features the debuggee supports.

As with all other types of breakpoints, watchpoints have properties that can be managed via the properties editor dialog.