Debugger API for Rhino

The Debugger API for Rhino consists of a set of Java interfaces which describes a high level debugger API and a default implementation of that API.

Most of the API is in the com.netscape.javascript.debug package. It is built upon low-level support built into the core engine in com.netscape.javascript.

The com.netscape.javascript.debug package includes an implementation of the Debugger API interfaces outlined below. The class com.netscape.javascript.debug.DebugManager.java implements the IDebugManager interface and com.netscape.javascript.debug.SourceTextManagerImpl.java implements the SourceTextManager interface.

The class com.netscape.javascript.tools.shell.Main.java provides an example which invokes the Debugger API.

The core interface of the API is IDebugManager. This interface provide the central point for interacting with the debug system. It supports the setting of the following hooks:

• IInterruptHook for immediate interrupt.
• IInstructionHook for breakpoints.
• IDebugBreakHook for breaking on errors.
• IErrorReporter for hooking into the error reporter system.
• IScriptHook for notification of script and function load and unload.

When hooks are called they are passed appropriate objects which are implemented by the Debugger API to describe such things as stack frames, program counter locations, etc. The interfaces for these objects are:

• IThreadState representing the state of the stopped thread.
• IStackFrame representing a stack frame.
• IPC representing a program counter location.
• IScript representing a compiled JavaScript script or function.
• ISourceLocation representing a location in the souce code.

SourceTextManager is an interface used to supply a centralized location from which a debugger client can access JavaScript source. It supports capturing source as it is parsed by Rhino. Alternately, source can be fed to it by the embedding; e.g. in a browser embedding where the JavaScript code is just a part of the html source the browser can feed the entire source to the SourceTextManager so that a debugger can 'see' the whole source and not just the part that is fed to the JavaScript compiler.

SourceTextItem is an interface representing a single 'block' of source code text (typically this is an entire source file). This may be pure JavaScript source, or may include JavaScript source embedded in html or whatever. The point is that this is the text that a debugger should show to a user while debugging the JavaScript code. This interface supports incrementally updated content. This is specifically useful in browser embeddings where text is received in blocks. In fact, in a browser it is possible that some of the source on a page may be compiled and run even before the entire content of the page has been received from a server.

ILaunchableDebugger is an interface that abstractly represents a debugger user interface. It is defined to allow an embedding to request that a debugger be launched without requiring that the embedding be coupled at compile time to a particular debugger implementation.

Limitations and unimplemented features

• Data Watchpoints are not implemented.
• Catching exceptions thrown in JavaScript code is not implemented.
• Per context hooking is not implemented.
• Setting the debug level to any non-zero value forces the optimization level to zero.
• Tracking of calls to plain Java methods from JavaScript is not implemented.
• Running at debug level >= 6 causes JIT errors with the Symantec JVM (but no other JVMs)
• The Debug API has not been rigorously tested.