Version:0.1 Author:Jan Jancura, Sun Microsystems/NetBeans
Abstract:
This document tries to describe the functionality of Java module from the point
of view of an ordinary user. Parts of this documents are taken from NetBeans' Users Guide.
Document History:
[2000-Aug-31] : version 0.1 : First version of the document
The Debugger can be used to present "snapshots" of the system state
during execution. By placing breakpoints at key positions throughout your
source code, the Debugger can halt at these points and display details of
the current environment at that point in the source. You can effectively step
through your code, monitoring execution as it occurs. You can also connect
the debugger to an already-running process.
The Debugger Window is a three-tabbed display with tabs for
Breakpoints, Threads, and Watches.
In the right half of the window is the property sheet pane which
displays the properties and their current values for the selected
node in the left pane. By default, the Debugger Window opens (as part
of the Debugging workspace) when you start debugging an application.
Note: This window is a separate view of debugging information available
in the Explorer under Runtime / Debugger with the
Properties window open.
The Breakpoints tab simply lists the currently set breakpoints,
showing the class name, and the line number or method on which the
breakpoint has been set.
Position the insertion point at the desired line in the Editor window.
Choose Add/Remove Breakpoint from the Debug menu
or toolbar in the Main Window, right-click on the line in
the Editor and choose Add/Remove Breakpoint from
the contextual menu, or use the keyboard shortcut CTRL+F8.
The current line will be highlighted blue to indicate that
the breakpoint has been set.
or:
Choose New Breakpoint from the Debug menu
or toolbar to bring up the Add Breakpoint dialog box.
Choose the type of breakpoint (either exception,
method, or line)
from the combo box.
Enter the settings (exception class name, class
name and method name, or class name and line number).
If you set the breakpoint using the New Breakpoint
command, you have further options:
If you want to be notified in the Output Window when
the breakpoint is reached, check Print text in
the Add Breakpoint dialog box. You can also set the text
to be printed using a combination of plain text and these
self-explanatory substitution codes: {lineNumber},
{className}, and {threadName}.
In addition, you can use curly braces and a dollar sign
to create a substitution code for a watch (for example,
{$mywatch}).
Checking Suspend Debugging suspends the debugging
session (all threads) when the breakpoint is reached.
You can also set these options (and later change them)
in the property sheet for the breakpoint in the Debugger Window.
Position the insertion point on the line in the Editor window
where the breakpoint has been set.
Choose Debug | Add/Remove Breakpoint from the Main Window
or use the keyboard shortcut CTRL+F8.
Breakpoints can also be removed directly from the Debugger Window
by right-clicking on a listed breakpoint and choosing Delete
from the contextual menu or by selecting the breakpoint and pressing
DELETE on the keyboard.
The Threads tab displays all thread groups in the current
debugging process. These thread groups are expandable hierarchies;
each group containing other thread groups or single threads,
which in turn contain CallStack
and Locals nodes.
When a thread is suspended:
The CallStack node can be expanded to show the current
hierarchy of method calls made during execution.
The Locals node displays local variables and
their current values in the context of the current thread. You
can expand these nodes to see the object sub-structure.
If the process you are debugging has more than one thread, all threads
and thread groups appear in the Threads tab showing a thread
name and current status (such as "running", "at breakpoint",
"cond. waiting"and "suspended"). Suspended threads and threads
at breakpoint display all "current" system information.
The Debugger Window displays the following properties for each running thread:
Name - Thread name (according to the thread class).
State - Status of the thread, such as Running,
Cond. waiting, and so on.
Class - Name of the class in which the thread is suspended.
Method - Name of the method in which the thread is suspended.
Line Number - Current line in the thread.
Stack Depth - Number of methods in the call stack.
The Watches tab lists all currently set watches.
A watch is a node you can create in the Debugger Window
to display the current value of any variable of that name
currently in scope. You can monitor the value of the variable
as it changes during the execution of the program.
The contextual menu of the root Watches
item on the Watches tab of the Debugger Window.
From the contextual menu of a variable you have
selected in the Editor (double-click the variable to
select it, and then right-click to bring up the context menu).
A dialog box requesting the name of the variable to
watch will open. Once you have entered the name of a
variable in your source and clicked OK, it will
be listed in the Watches tree.
Click on this item in the Watches tree to select
it and display its property sheet.
Continue running the application and watch the variable change.
Whereas a standard watch refers to the value of
variable of that name
currently in scope, it is possible to create a
fixed watch, which always refers to the variable itself
that it was created on.
Right-click on the watch and choose Create Fixed Watch
from the contextual menu.
A new node will appear in the Watches tree showing the
value of that specific variable. If the context changes,
and the new context contains a different variable of the same
name, the watch will show the value of the variable currently
in scope, and the fixed watch will show the value of the particular
variable it was created on.
Set a breakpoint and then choose Debug | Start Debugging
from the Main Window (or press F5). (If you are debugging a GUI
application or another looped application, it is not necessary
to set a breakpoint before starting.)
By default, the IDE switches to the Debugging Workspace (to
configure it to do otherwise, see Customizing workspaces),
where the Debugger Window,
the Editor with the source being debugged, and the Output
Window all open up. The Output Window is split vertically,
with Debugger output on the right and any output from the
application being debugged on the left. When the Debugger
reaches a breakpoint in your source, that breakpoint
is highlighted pink. The pink line will move through your
source as you step through its execution.
Debugging can also be initiated by choosing the Trace Into
command, which causes the Debugger to stop on the first line
after the main method.
Once execution has halted (whether on a breakpoint or just
after the main method), use the Trace Into,
Go To Cursor, Trace Over, Trace Out,
and/or Continue menu or toolbar items under the
Main Window Debug menu (or the keyboard shortcuts
F7, F4, F8, CTRL+F7, and ALT+F5, respectively) to proceed.
Trace Into steps into the method at which the Debugger
is currently stopped if there is a method call on that line
and breaks at the start of the called method, enabling you
to observe execution incrementally. If there is no method
call on the current line, then it behaves like Trace Over.
Go To Cursor executes the current statement and all ensuing
statements until it reaches the line that the insertion point is on.
Trace Over executes the current statement without breaking
and stops at the next statement.
Trace Out halts execution after the current method finishes
and control passes to the caller.
Continue resumes execution, which continues until it reaches
the next breakpoint or the end of the application.
Finish Debugging (SHIFT+F5) ends the current debugging session.
By stepping through your code like this, you can monitor whatever parts
of the system you choose during execution of the code.
The Debug menu and toolbar also have Suspend All
and Resume All options, which enable you to "pause"
execution at any time and then continue from the point
execution was suspended.
Under the Threads tab in the Debugger Window, select
the nodes of those threads or thread groups (using SHIFT to
select multiple consecutive nodes and CTRL to select various
non-consecutive nodes).
Right-click on one of the selected nodes and choose Suspend
from the contextual menu.
Choose Suspend All from the Debug menu or toolbar.
Right-click on the root Threads node in the Debugger
Window and choose Suspend from the contextual menu.
When a thread is suspended, the Debugger Window displays all current
information for the thread.
Likewise, you can resume any or all of the suspended threads.
Choose Resume All from the Debug menu to resume
execution of all threads. To resume execution for threads
individually, right-click on the thread or thread group and
choose Resume from the contextual menu.
The current thread is set automatically when a breakpoint is reached.
When you use the Trace In, Trace Out, and Trace Over commands, they
affect only this thread. You can change the current thread manually.
Under the Threads tab in the Debugger Window,
right-click on the node of the thread you would like to
switch to and choose Switch to thread from the
contextual menu.
When launching the process, enter -Xdebug in the Java
virtual machine's parameter list (after -classic
when running on HotSpot) and note the agent password.
Choose Connect from the Debug menu or toolbar to
bring up the Connect to Running VM dialog box.
Enter the host name and agent password in the dialog box.
After clicking OK, the Debugger will connect to the running VM,
and you will be able to see all threads as if you were debugging locally.
If you have source code for the debugged application and you set
a breakpoint in the source code, the Editor will be opened with
the breakpoint line highlighted in the source.
The debugging category (for example, applet or standard) is set
for each separate object in the IDE. When you set debugging, you choose from
a list of "debugger types", each of which represents a specific configuration
of a debugger (including the path to Java and arguments). There can be multiple
debugging types for a given debugging category, though the IDE comes with only
one for each category. See Adding and modifying service types
for more information.
Select the object under the Filesystems tab in the Explorer.
Go to the object's property sheet (by choosing View | Properties
from the main menu).
Click on the Execution tab in the Properties window.
Rotate through the debugging types by double-clicking on
Debugger, or click on the Debugger property's
value and choose a type from the pull-down menu.
It is possible to switch the default debugger type. When you switch
the default debugger type, this switch affects all classes and templates
for which the user has not specifically assigned a debugger type.
Choose Project | Settings... from the main menu to open
the Project Settings window.
Select the Java Sources node in the left pane of
the Project Settings window.
Select the Default debugger type property and
choose a new default debugger type from the dropdown list.
Note: Once you change a class or template's debugger type,
the IDE will never again recognize the class as using the default
debugger type, even if you switch the debugger type for the class
back to the one that is the IDE default. Therefore, if you change
a class's debugger type and then change it back to the default
debugger type, the class's debugger type will not be affected if
you change the default debugger type.
It is also possible to customize the command-line template for the debugger,
thus affecting the way the debugger is called. For more information, see
Adding and modifying service types.
If you use more than one debugger type in your work, you can create
a set of templates with the different debugger types that you use.
See Creating your own templates
and Modifying existing templates
for more information.
