The display areas within the main JSwat window are themselves called windows. These windows display the variables, threads, classes, breakpoints, sessions, and so on. Initially not all of the windows are visible, so you may want to peruse the Window menu to look for the other available windows. To arrange the windows within the main window, click on the title bar of the window and drag it to a different location. You will see a colorful outline that indicates where the window will be displayed when you release the mouse button. You can change the size of the windows in relation to one another by dragging the dividers between the window areas (an area is a collection of windows which occupy the same space, referred to as "modes" in NetBeans terminology).
To start debugging your code, you may launch your application from within the debugger, or start it separately and connect the debugger as needed. The launching dialog is generally appropriate for small applications with a simple launching mechanism, whereas you would use the attaching method if the application has a launcher of its own, or requires significant setup.
To launch the debuggee, select Start from the Session menu (or click on the corresponding toolbar button). The dialog that appears has a Help button that will display the help page to explain all of the input fields. You must provide the name of your application's main class, as well as the classpath that is normally used to launch your application.
Once the debuggee is launched, it is in a paused state, waiting for you to signal it to start. To start the debuggee, select Continue from the Session menu (or click on the corresponding toolbar button). The debuggee will run until it hits a breakpoint, or it exits normally.
Attaching to a debuggee after it has been launched requires that the debuggee was launched with certain debugging flags. Examples for each of the different JDK versions are shown below.
| JDK Version | Debug Flags |
|---|---|
| 1.2, 1.3 | -Xdebug -Xnoagent -Djava.compiler=NONE
-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5000 |
| 1.4 | -Xdebug
-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5000 |
| 1.5 |
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5000 |
You are free to use a different number for the
address value, as long as it is between 1024 and 65535,
inclusive, and not already in use by another program. Alternately, if
you are using Microsoft Windows you can choose to use the shared
memory transport instead of the sockets transport. Do this by
changing the dt_socket to dt_shmem and the
address value to some name, such as
jpdaconn.
Once the debuggee has been launched with the flags shown above,
select Attach from the Session menu
(or click on the corresponding toolbar button). The dialog that
appears has a Help button that will display the help
page to explain all of the input fields. For the port number field,
you should enter the number given as the address in the
debug flags (e.g. 5000). If you used the shared memory transport,
then select the shared memory option from the
Transport field in the attach dialog, and enter the
name from the address option in the debug flags
If the debuggee was launched with suspend=y then you
may start the debuggee by selecting Continue from
the Session menu (or click on the corresponding
toolbar button). The debuggee will run until it hits a breakpoint, or
it exits normally.
You probably have already set the classpath for your application when you launched it, either from the debugger or in a separate command window. In any case, you can inspect the classpath via the Settings item in the Session menu. Note that while the session is connected to the debuggee, you will be prevented from modifying the classpath, since it is impossible to modify the classpath of a running JVM.
In addition to the classpath, you can use the Settings dialog to
specify the directories and archives containing the source code for
your application. This is referred to as the sourcepath. The
sourcepath has the same structure as the classpath, except it refers
to the location of source code, rather than the location of class
files. Thus, if you have a classpath that looks like
/home/me/java/build, which contains .class
files such as org/mine/Widget.class, and your source
code is similarly located in a directory such as
/home/me/project/src, which contains .java
files such as org/mine/Widget.java, then the sourcepath
would be set to /home/me/project/src. Note that the
sourcepath can contain directories as well as archives, such as
.jar and .zip files.
To set breakpoints, use the debugger to open the source file containing the code in which you want to stop. Scroll the editor to the desired line, then click the mouse in the gray margin on the left side of the editor view. Clicking in the margin will create a line breakpoint, and clicking on the line breakpoint icon will remove the breakpoint.
Additional types of breakpoints may be created from the Breakpoint menu, including class, exception, method, thread, trace, and variable breakpoints. The dialog for creating breakpoints has a Help button that displays a help topic explaining the various input fields.
Once the debuggee has been launched and it hits a breakpoint, you can begin stepping through the code. Do this by selecting one of the items in the Stepping menu. The Step Into item will perform a single-step operation, stepping into method calls, while Step Over will step through the method call in one action. Step Out will finish the current method and stop at the calling method. Run to Cursor will set a breakpoint at the current cursor location, resume the debuggee so that it will hit the breakpoint, and then automatically delete the breakpoint.
As with many of the other menu items, there are corresponding keyboard shortcuts. Look at the menu items to see the current keyboard shortcut assignments for each item.
There are three ways in which to view the values of variables. The first is with the Variables window, which shows all local variables, as well as the fields of the current object. This display is automatically updated each time the debuggee hits a breakpoint, as well as when you step through your code.
In addition to that view, there is the editor tooltip, whereby the value of the variable under the mouse pointer will be displayed as a tooltip in the source editor. Naturally, this requires having a source file open in the editor that contains references to the desired variables. This also requires that the debuggee has stopped at a breakpoint in order for the evaluator to have a current thread and stack frame from which to evaluate the variable reference.
The third option is to use the Evaluator view.
You can type any Java-like expression (with a few minor omissions,
such as ternary operators and the new and
super keywords) and it will be evaluated and the result
displayed in the window. This requires that the debuggee has stopped
at a breakpoint in order to evaluate any variable references.
When you see a flashing red icon in the lower right corner of the main window, that indicates that an unexpected error occurred. Click the icon to see an explanation, along with a stack trace. If such an error prevents you from debugging properly, please send the error message and stack trace to jswat-bugs@bluemarsh.com so the problem can be entered into the bug tracking system.