Tutorial

Tutorial Program

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.

Setting the Classpath

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.

Setting the Sourcepath

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.

Loading 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.

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.

Setting Breakpoints

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.

Single-Stepping

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".

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. 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 -- 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.