house fly

JSwat Project

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.

Installing and Starting JSwat

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

Loading the Class

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.

load dialog

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.

tutorial loaded

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 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 "Debug" menu. This displays a dialog like the one shown below.

setting breakpoints

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 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 ("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) and e (method argument) 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.

stopped at breakpoint

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

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

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.



Back to Documentation