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 '
-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.
See the JSwat installation
instructions for the details on installing JSwat to your
system. Once JSwat is installed on your system, we can start the
debugger from the command line. Type "
com.bluemarsh.jswat.Main" in a command shell to launch
the debugger. If you see an error message stating that the JPDA
library cannot be found, see the JSwat
installation instructions and read the part about installing
the JPDA. JSwat requires this library in order to debug Java
Start the debugging session by launching JSwat and selecting "Start VM" from the "Debug" 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 check 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
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.
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 heirarchial 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
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
With the tutorial class running, set a breakpoint at the
actionPerformed() method. You could do this by typing
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
"Debug" menu. This displays a dialog like the one shown
Yet another way to set a breakpoint is using the source code
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
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 tuturial 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
[AWT-EventQueue-0]"), followed by the name
of the method ("
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
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
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) and
argument) are visible.
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
To resume execution of the debuggee VM, press the
"Play" button on the toolbar. Alternatively, you could
resume" at the command prompt. The
tutorial window will now have changed the button label to say
"Pushed 1 times".
At some point or another you will single-step into the Java core classes. This will happen often enough that you wish you could avoid stepping into such classes. Fortunately, JSwat provides the '
exclude' command for just this purpose. You can add
individual classes and entire packages to a list of class filters.
During single-stepping, you will never step into those classes.
See the exclude command's help for more information.
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 JSwat is easy. Select the "Exit" item from the
"File" menu. Or, type "
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.
Back to Documentation