house fly

JSwat Project

How To: Breakpoints


How to Set Breakpoints

JSwat supports setting breakpoints inside classes, including inner classes. Breakpoints can be set in at least two ways using JSwat. First there is the command 'stop' which can be used to set a breakpoint at a method in a class or at a code line in the class. Second, there is the "Set Breakpoint" item in the "Debug" menu, and finally there is a button in the toolbar. This presents a dialog which allows you to set a breakpoint at a code line in a class.

For using the 'stop' command, type 'help stop' to learn the syntax for the command. It is generally of the form "stop <class>:<line>" where <class> is the name of a class and <line> is the code line at which to set the breakpoint. To set a breakpoint inside an inner class, use the dollar sign ($) to separate the names of the outer and inner classes. Some examples are:

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

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 fully-qualified argument types.

What Breakpoints Do I Have Set?

Any breakpoints that have been set and resolved 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 'stop' command with no arguments. To see the breakpoints in a dialog, select the "Breakpoints..." menu item. There is also the panel labeled "Breakpoints".

Breakpoints are also visually displayed in the source code viewer. The breakpoints are displayed by colorizing the area on the left margin of the source window. Resolved breakpoints are colored with green and disabled breakpoints are gray. Breakpoints that have expired are red. Unresolved breakpoints are blue. Breakpoints that are skipping hits are yellow.

How to Disable/Enable Breakpoints

There are at least three 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.

Another way to disable or enable breakpoints is to use the "Breakpoints..." menu item. This presents a dialog that shows all the set breakpoints. Select a breakpoint in the dialog and click either the "Disable" or "Enable" button, as desired.

Yet another way to disable and enable breakpoints is by using the source code viewer. If a source file is displayed which contains breakpoints, you can right click on the code line with the breakpoint and a popup menu will appear. This menu has items to disable, enable, and remove breakpoints.

How to Clear Breakpoints

There are at least three ways to clear breakpoints. The first is through the 'clear' command. This takes the number of the breakpoint (as described above) to remove.

Another way to clear breakpoints is to use the "Breakpoints" menu item. This presents a dialog that shows all the set breakpoints. Select a breakpoint and click the "Remove" button to remove the breakpoint.

Yet another way to clear breakpoints is by using the source code viewer. If a source file is displayed which contains breakpoints, you can right click on the code line with the breakpoint and a popup menu will appear. This menu has items to disable, enable, and remove breakpoints.

Grouping Breakpoints

Breakpoints are automatically added to a breakpoint group called "Default". Via the breakpoints manager dialog (accessible via the "Debug" menu) 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 whenver 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. Expiration is when a breakpoint has been hit enough times that it is no longer useful. This 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.

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

This is very easy to do. Simply select all of the breakpoints you want to modify in the breakpoints panel, then select the button to modify them. You can enable, disable, and remove multiple breakpoints just be selecting them.

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 a "value" condition. The condition is satisfied when the named variable (e.g. "obj1.fieldx") equals a particular value (e.g. "123"). The variable type must be a primitive (boolean, byte, char, double, float, int, long, short) or a String.

Breakpoint Monitors

Breakpoints may have one or more monitors assigned to them. A monitor is something that is "performed" whenever the breakpoint is hit and the breakpoint is not disabled, skipping, or 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 yourself. For instance, you could add a monitor to invoke the "where" command whenever the assigned breakpoint is hit. In addition to the built-in commands, any defined alias or macro can be used.

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. "None" and "All" are obvious, while "Event" may be unclear. The event thread is the one in which the breakpoint event occurred.

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.

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 classs can be manipulated using either the breakpoint properties dialog box, or through the filter command.



Back to Documentation