ojluni/src/main/java/com/sun/tools/example/doc/javadt.html - platform/libcore.git - Git at Google

 <HTML>
 <HEAD>
    <TITLE>Release notes for the javadt debugger</TITLE>
 </HEAD>
 <BODY BGCOLOR="#FFFFFF">
 <H1>Release notes for the javadt debugger</H1>

 <P>
 As a demonstration of the
 <A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html">
 Java<sup><font size=-2>TM</font></sup> Platform Debugger Architecture</A>
 we are providing source code for
 a simple GUI debugging tool - <b>javadt</b>.
 It is included as an example and demonstration of
 <A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html#jdi">
 JDI</A>.  It is not a finished or polished debugger and is
 missing many features of importance for real debugging work.
 <P>

 <H2>Invoking javadt</H2>
 <P>
 <b>javadt</b> can be run by executing:
 <PRE>
    java com.sun.tools.example.debug.gui.GUI &lt;options&gt;.. &lt;class-name&gt;
 </PRE>
 where &lt;class-name&gt; is the name you would normally
 place on the <code>java</code> command line.
 Note: the path to the <A HREF="index.html#SETUP">JDI Library</A> and to
 the compiled <b>javadt</b> class files must be on the class path
 used to invoke gui.GUI.
 <p>
 For example, you can invoke the javadt debugger as follows:
 <PRE>
    java com.sun.tools.example.debug.gui.GUI -classpath . Hello
 </PRE>
 Note: this <code>-classpath</code> option controls the
 class path for the <code>Hello</code> application.
 Once the window appears, you can issue the 'run' command to begin
 execution immediately.  It is also
 possible to give the class name in the 'run' command, in
 which case it may be omitted when invoking the debugger from the
 shell.
 <P>
 The classpath may also be set from within the debugger, using the
 'classpath' command.  Currently, other arguments to the VM must be
 given on the shell command line when the debugger is initially
 invoked.  The most recently mentioned classpath, VM arguments, main
 class name, and program arguments are retained as defaults for later
 'run' and 'load' commands.  (Unfortunately, at present, the debugger
 will likely crash if you attempt to begin another debugging session
 with another debuggee process from within the same invocation of the
 debugger.  You should exit to the shell and start a new debugger
 process.)
 <P>

 <H2>Using javadt</H2>
 The javadt normally displays context related to the "current thread",
 that is, the thread that most recently encountered a breakpoint, threw
 an uncaught exception, or was single-stepped by the user.  When
 program execution is suspended on account of one of these events, a
 current thread exists, and the javadt displays the following information
 about it:
 <P>
 <UL>
 <LI>  A stack backtrace.

 <LI>  The source code surrounding the line corresponding to the
       instruction counter for the thread, if the source code is
       available.
 </UL>
 <P>
 In addition, a tabbed pane allows the user to view one of three
 additional views:
 <P>
 <UL>
 <LI>  A tree of all source files available on the source path.

 <LI>  A tree of all loaded class files, organized hierarchically
       by package.

 <LI>  A tree of all active threads, organized hierarchically
       by thread group.
 </UL>
 <P>
 By clicking on the name of a source file, the source view can be
 directed to display it.  Likewise, clicking on a thread will make that
 thread the current thread.  These features are normally used while the
 program is suspended, e.g, at a breakpoint.  Upon resumption and
 encountering another breakpoint, for example, the current thread will
 be automatically reset and the views will be updated.  The views tile
 the javadt display, and are adjustable in size.
 <P>
 The javadt functionality is rather basic, thus a command-line interaction
 window is also provided that allows access to functions that are not
 yet exposed in the javadt.  In particular, it is necessary to use the
 command line in order to set breakpoints and examine variables. The
 javadt debugger command interpreter implements roughly a subset of the
 <a href="jdb.html">jdb</a>
  functionality, but adds a few commands of its own.  The
 'help' command lists the complete set of commands and their function.
 Shortcuts for a set of the most common commands is provided on a
 button-bar at the top of the display.
 <P>
 The program to be debugged may be started either as a child of the
 debugger, or the debugger can be attached to an existing process,
 provided that its VM is prepared to accept the connection.  If the
 debuggee is started by the debugger as a child, a line-oriented
 interface to its standard input, output, and error streams is provided
 in an application interaction pane.
 <P>
 The debugger expects to find the program source code on its
 sourcepath, set with the 'use' or 'sourcepath' command.  If you find
 that sources are not being displayed because the sourcepath is
 incorrect, you may change it at that time, and the source view will be
 immediately updated.
 <P>
 The message "No current thread" is often encountered when stepping
 through a program.  This message does not mean that the thread or
 the VM has died, merely that a current thread is undefined.  This
 situation can easily occur unexpectedly when the program being
 stepped is waiting, eg., for input.  The VM appears to be stopped,
 as it would be after the successful completion of a step, but it
 is considered to be "running", not "interrupted".  The prompt
 in the command interaction pane indicates the state by changing
 to a thread name and frame number when the VM is interrupted.
 When it is running, the prompt "Command:" is displayed.
 <P>
 <H2>Source for javadt</H2>
 Full source code for <b>javadt</b> is included under the
 <code>debug</code> directory of <code>examples.jar</code>.
 Note: these directories also include the
 source for <a href="jdb.html"><code>jdb</code></a>.
 Source code for these example applications is included to provide concrete
 examples for debugger developers.  Example code may be used, modified
 and redistributed by debugger developers providing they adhere to the
 terms in the COPYRIGHT notice.
 <P>
 <b>javadt</b> uses the following packages (found under the
 <code>debug</code> directory):
 <DL>
 <DT><code>gui</code>
 <DD>User interface code
 <DT><code>bdi</code>
 <DD>Debugger core code
 <DT><code>events</code>
 <DD>Event Set code
 <DT><code>expr</code>
 <DD>Expression processing code
 </DL>
 <P>
 <H2>Building javadt</H2>
 To build the <b>javadt</b> classes from the
 provided source files under the <code>debug</code> directory,
 you need only to compile them. No special
 options are required, aside from those which set your classpath to
 include the <A HREF="index.html#SETUP">JDI Library</A>.
 </P>
 <P>
 However, if you want to modify the expression parser in the file
 <code>Expr.jj</code>, you will need the
 <a href="http://www.metamata.com/javacc/">
 JavaCC parser generator</a>.
 It is available free from
 <a
 href="http://www.webgain.com/products/metamata/java_doc.html">Metamata
 (now part of WebGain)</a>.
 <P>
     <hr>
     <address><a href="mailto:java-debugger@java.sun.com">java-debugger@java.sun.com</a></address>
     </P>
 <P>
 </P>
 </BODY>
 </HTML>
	<HTML>
	<HEAD>
	<TITLE>Release notes for the javadt debugger</TITLE>
	</HEAD>
	<BODY BGCOLOR="#FFFFFF">
	<H1>Release notes for the javadt debugger</H1>

	<P>
	As a demonstration of the
	<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html">
	Java<sup><font size=-2>TM</font></sup> Platform Debugger Architecture</A>
	we are providing source code for
	a simple GUI debugging tool - <b>javadt</b>.
	It is included as an example and demonstration of
	<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html#jdi">
	JDI</A>. It is not a finished or polished debugger and is
	missing many features of importance for real debugging work.
	<P>

	<H2>Invoking javadt</H2>
	<P>
	<b>javadt</b> can be run by executing:
	<PRE>
	java com.sun.tools.example.debug.gui.GUI <options>.. <class-name>
	</PRE>
	where <class-name> is the name you would normally
	place on the <code>java</code> command line.
	Note: the path to the <A HREF="index.html#SETUP">JDI Library</A> and to
	the compiled <b>javadt</b> class files must be on the class path
	used to invoke gui.GUI.
	<p>
	For example, you can invoke the javadt debugger as follows:
	<PRE>
	java com.sun.tools.example.debug.gui.GUI -classpath . Hello
	</PRE>
	Note: this <code>-classpath</code> option controls the
	class path for the <code>Hello</code> application.
	Once the window appears, you can issue the 'run' command to begin
	execution immediately. It is also
	possible to give the class name in the 'run' command, in
	which case it may be omitted when invoking the debugger from the
	shell.
	<P>
	The classpath may also be set from within the debugger, using the
	'classpath' command. Currently, other arguments to the VM must be
	given on the shell command line when the debugger is initially
	invoked. The most recently mentioned classpath, VM arguments, main
	class name, and program arguments are retained as defaults for later
	'run' and 'load' commands. (Unfortunately, at present, the debugger
	will likely crash if you attempt to begin another debugging session
	with another debuggee process from within the same invocation of the
	debugger. You should exit to the shell and start a new debugger
	process.)
	<P>

	<H2>Using javadt</H2>
	The javadt normally displays context related to the "current thread",
	that is, the thread that most recently encountered a breakpoint, threw
	an uncaught exception, or was single-stepped by the user. When
	program execution is suspended on account of one of these events, a
	current thread exists, and the javadt displays the following information
	about it:
	<P>
	<UL>
	<LI> A stack backtrace.

	<LI> The source code surrounding the line corresponding to the
	instruction counter for the thread, if the source code is
	available.
	</UL>
	<P>
	In addition, a tabbed pane allows the user to view one of three
	additional views:
	<P>
	<UL>
	<LI> A tree of all source files available on the source path.

	<LI> A tree of all loaded class files, organized hierarchically
	by package.

	<LI> A tree of all active threads, organized hierarchically
	by thread group.
	</UL>
	<P>
	By clicking on the name of a source file, the source view can be
	directed to display it. Likewise, clicking on a thread will make that
	thread the current thread. These features are normally used while the
	program is suspended, e.g, at a breakpoint. Upon resumption and
	encountering another breakpoint, for example, the current thread will
	be automatically reset and the views will be updated. The views tile
	the javadt display, and are adjustable in size.
	<P>
	The javadt functionality is rather basic, thus a command-line interaction
	window is also provided that allows access to functions that are not
	yet exposed in the javadt. In particular, it is necessary to use the
	command line in order to set breakpoints and examine variables. The
	javadt debugger command interpreter implements roughly a subset of the
	<a href="jdb.html">jdb</a>
	functionality, but adds a few commands of its own. The
	'help' command lists the complete set of commands and their function.
	Shortcuts for a set of the most common commands is provided on a
	button-bar at the top of the display.
	<P>
	The program to be debugged may be started either as a child of the
	debugger, or the debugger can be attached to an existing process,
	provided that its VM is prepared to accept the connection. If the
	debuggee is started by the debugger as a child, a line-oriented
	interface to its standard input, output, and error streams is provided
	in an application interaction pane.
	<P>
	The debugger expects to find the program source code on its
	sourcepath, set with the 'use' or 'sourcepath' command. If you find
	that sources are not being displayed because the sourcepath is
	incorrect, you may change it at that time, and the source view will be
	immediately updated.
	<P>
	The message "No current thread" is often encountered when stepping
	through a program. This message does not mean that the thread or
	the VM has died, merely that a current thread is undefined. This
	situation can easily occur unexpectedly when the program being
	stepped is waiting, eg., for input. The VM appears to be stopped,
	as it would be after the successful completion of a step, but it
	is considered to be "running", not "interrupted". The prompt
	in the command interaction pane indicates the state by changing
	to a thread name and frame number when the VM is interrupted.
	When it is running, the prompt "Command:" is displayed.
	<P>
	<H2>Source for javadt</H2>
	Full source code for <b>javadt</b> is included under the
	<code>debug</code> directory of <code>examples.jar</code>.
	Note: these directories also include the
	source for <a href="jdb.html"><code>jdb</code></a>.
	Source code for these example applications is included to provide concrete
	examples for debugger developers. Example code may be used, modified
	and redistributed by debugger developers providing they adhere to the
	terms in the COPYRIGHT notice.
	<P>
	<b>javadt</b> uses the following packages (found under the
	<code>debug</code> directory):
	<DL>
	<DT><code>gui</code>
	<DD>User interface code
	<DT><code>bdi</code>
	<DD>Debugger core code
	<DT><code>events</code>
	<DD>Event Set code
	<DT><code>expr</code>
	<DD>Expression processing code
	</DL>
	<P>
	<H2>Building javadt</H2>
	To build the <b>javadt</b> classes from the
	provided source files under the <code>debug</code> directory,
	you need only to compile them. No special
	options are required, aside from those which set your classpath to
	include the <A HREF="index.html#SETUP">JDI Library</A>.
	</P>
	<P>
	However, if you want to modify the expression parser in the file
	<code>Expr.jj</code>, you will need the
	<a href="http://www.metamata.com/javacc/">
	JavaCC parser generator</a>.
	It is available free from
	<a
	href="http://www.webgain.com/products/metamata/java_doc.html">Metamata
	(now part of WebGain)</a>.
	<P>
	<hr>
	<address><a href="mailto:java-debugger@java.sun.com">java-debugger@java.sun.com</a></address>
	</P>
	<P>
	</P>
	</BODY>
	</HTML>