In order to get started with the tutorial, you will need to create
a sample program to debug. One has already been written, it simply
needs to be saved to a file. Follow this
link to the example code, select the
program text and press the "Copy" button in the help viewer
toolbar; then paste the text into a text editor and save it to a file
named tutorial.java
. We will be using this example to
learn more about JSwat's features and how to use them.
Compile the file you just created using javac -g, which will compile the class with local variable and line number information. This information is needed when you plan on debugging your code. Without it, the debugger cannot debug the class.
Assuming you are an experienced Java developer, you know what the classpath is and how it is used, so that will not be covered here. For an explanation on how JSwat uses the classpath setting, see the "Classpath" related help page, accessible from the built-in help.
Start JSwat and select the "Set Classpath" item from the
"Options" menu. In the dialog that appears, clear out all
of the entries already found there, as chances are they have more to
do with running JSwat than debugging the tutorial sample. Do this
with the "Remove Path" button at the bottom of the dialog.
Once all of the classpath entries are removed, enter a new path entry
by pressing the "Add Path" button. Use the file selector
dialog that appears to select the directory containing the
tutorial.class
file. Once that is done, accept the new
classpath setting by selecting the "OK" button.
If you placed the tutorial.java
and
tutorial.class
files in different directories, you will
need to set the JSwat sourcepath setting. The sourcepath is similar
to the classpath except that it tells JSwat where to find source code
rather than class files. The sourcepath is set in the same manner as
the classpath, except that it is done by selecting "Set
Sourcepath" from the "Options" menu. The purpose is to
select the directory where the tutorial.java
file is
located, which allows JSwat to find it when all that is known is the
name of the class.
Now that the classpath is set, start the debugging session by selecting "Start VM" from the "VM" 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. 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. Now press the Ok button and you should see a message that looks something like this:
VM loading with following options, class name, and class arguments. /jdk/bin/java -cp /java/samples 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.
Now that JSwat and the tutorial sample are running, you should notice that the JSwat window is made up of various panels that display information related to the debuggee. 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 through code; 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.
We are now ready to try setting breakpoints with JSwat. We can do
this through the source code viewer. The tutorial.java
file should be visible already on the right side of the JSwat window.
If it is not, go to the "Classes" panel and expand the
"tutorial" node; double-click on the
"main(String[])" node and the tutorial.java
source file should open.
With the tutorial source view open, click in the source view gutter area at line 12 of the source code. The gutter area is the part of the source view that shows the line numbers and has a gray background. The line number will now have a green background color. This indicates that a breakpoint is set at that line.
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 by raising its window above all others. The line of code that is about to be executed will be highlighted in blue in the source view. Additionally, JSwat will show the current location in the messages panel; the name of the thread is in square brackets, followed by the name of the class and method, which is in turn followed by the name of the source file and the line number where execution has stopped.
By the way, 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.
Now you are ready to learn about single stepping through the source code. Stepping one line of code at a time can be 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 panel forward and show the currently visible local variables. At line 12 of the tutorial class, only "e" (method argument), and "this" (reference to the current object) are visible. Expand the "this" node to see the "pushCount" field.
Press the F12 key several times now and observe how the source line highlighter moves along through the source view. 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. The tutorial window will now have changed the button label to say "Pushed 1 times".
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. 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 -- just press on the window close button. JSwat will close the debuggee VM and then exit.
If you exit JSwat while debugging a remote debuggee, JSwat will merely detach from the remote VM without terminating it.