JSwat Tutorial
Tutorial Program
Start by saving this Java source
code to a file and call it tutorial.java . We
will be using this example source code to learn more about
what JSwat can do and how to use it. Compile this code using
'javac -g ' which will compile the class
with local variables and line number information. Both are
needed when using any Java debugger. Make sure the
tutorial.class file is located somewhere in your
classpath.
Note that using Jikes may result in invalid class
debugging information. I recommend using the Java compiler
that comes with the JDK.
Loading the Class
Start the debugging session by launching JSwat and
selecting "Start VM" from the "Session"
menu. A dialog will appear asking you for the name of the
class to be debugged, along with some other information that
has already been filled in for you. Verify that the classpath
shown in the "Options" field is correct. Then enter
"tutorial" in the "Class name" field.
Make sure the "suspended" checkbox is checked so
the session will not resume until you tell it to.

With the information entered, click on the Ok button. You
should see a message that looks something like:
VM loading with following options, class name, and class arguments.
/path/to/java -cp /home/me/java
tutorial
VM loaded.
This indicates that the debuggee VM was successfully
created. At this point the debuggee VM has not attempted to
locate the class in question. That is, you could use the
start dialog to load the "noclass "
class and the debuggee VM will load without an error. Only
when you click on the "Play" button in the toolbar
does the debuggee VM start and try to locate the main class.
In fact, do this now to start the tutorial debuggee VM.
The tutorial class will start and create a window with a
single button. Now the tutorial program is waiting for you to
do something. This gives us an opportunity to take a closer
look at the JSwat window.
JSwat Window
Now that JSwat and the tutorial sample are running, you
should notice that the JSwat window is made up of various
panels. There is a panel called "Threads" which
shows the threads in the debuggee VM. A panel showing the
messages from JSwat is also visible, with a command input
field below that. To the right is where source files are
shown.

You will notice that above the threads panel are a set of
labeled tabs. When pressed these tabs bring other panels
forward. They include a panel called "Classes"
which shows the currently loaded classes in a hierarchal
tree; "Locals" displays the local variables while
single-stepping; and "Watches" which allows viewing
field and local variables during program execution.
If you have looked at the tutorial.java file
you will notice that the first line of the
main() method prints a message to the
System.out output stream. The output from the
debuggee VM is captured by JSwat into one of its panels.
Click on the "Output" tab above the messages panel
and you will see the message from the tutorial class. The
"Input:" field below the output display is for
entering text input to the debuggee VM on its
System.in input stream.
Setting Breakpoints
With the tutorial class running, set a breakpoint at the
actionPerformed() method. You could do this by
typing "stop
tutorial.actionPerformed(java.awt.event.ActionEvent) ".
This is a rather lengthy way to set a breakpoint. Another way
is to set the breakpoint at a specific line of code. You can
do this with "stop tutorial:12 ".
Another way to set the breakpoint is through the "Set
Breakpoint" item in the "Breakpoints" menu.
This displays a dialog like the one shown below.

Yet another way to set a breakpoint is using the source
code viewer. The tutorial.java file should be
visible already, but if it is not, click on the
"Classes" tab to bring the class tree panel
forward, then double-click on the "tutorial" node
and the tutorial.java source file should open.
Now right-click on line 12 of the source code and you should
see a popup menu appear. Select the "Add
breakpoint" item and a new breakpoint will be set at
line 12. The source code viewer will reflect this by drawing
the line number in green. Disabled breakpoints are shown in
gray.
Now switch to the tutorial program's window and click
on the "Push me" button. Immediately JSwat signals
that the debuggee VM has hit a breakpoint. It shows the
current location in the messages panel. The name of the
thread is in square brackets (e.g.
"[AWT-EventQueue-0] "), followed by the
name of the method
("tutorial.actionPerformed "), which is
in turn followed by the name of the source file and the line
number where execution has stopped
("(tutorial.java:12) "). You should
also notice that the source code viewer has changed slightly.
The source line at line 12 is highlighted which indicates
that it is the current line of execution.
Just for your information, when a breakpoint is hit at a
certain line number (in this example, line 12), the debuggee
VM has not yet executed that line of code. In this example,
the pushCount field variable has not yet been
incremented.
Single-Stepping
Now you are ready to learn about single stepping through
the source code. Stepping one line of code at a time is done
by pressing the shortcut key for the "Next Line"
menu item under the "Step" menu. The default
shortcut key for this is the F12 function
key.
Before you start single-stepping, click on the
"Locals" tab above the class tree panel. This will
bring the local variables display panel forward and show the
currently visible local variables. At line 12 of the tutorial
class, only pushCount (field variable),
e (method argument), and this
(reference to 'this') are visible.
Press the F12 key several times right now and
observe how the source line highlighter moves along through
the actionPerformed() method of the tutorial
class. As you step through the code, you will also notice
that the local variables panel is updated to show the latest
visible variables and their values.

To resume execution of the debuggee VM, press the
"Play" button on the toolbar. Alternatively, you
could type "resume " at the command
prompt. The tutorial window will now have changed the button
label to say "Pushed 1 times".
Restarting the Session
Say that we want to reload the tutorial class after we
have made a change to the source code and recompiled. An easy
way to do this is to press the "New "
button on the toolbar (the third button from the left). This
brings up the "Start VM" dialog that you saw at the
beginning of the tutorial. Notice that the dialog contains
the values you entered earlier. That is because JSwat
remembers the values from the last time we started the
debuggee VM.
When you click the Ok button in the Start VM dialog, it
will terminate the current debugging session and start a new
one.
Exiting the Session
Exiting JSwat is easy. Select the "Exit" item
from the "File" menu. Or, type
"exit " at the command prompt, or click
on the window close button. All these methods will result in
the same thing: the debuggee VM will be terminated and JSwat
will exit.
If you are debugging a remote debuggee VM (using the
'attach ' JSwat command), JSwat will
merely detach from the remote VM without terminating it.
|