org.apache.bsf.debug
Interface BSFDebugManager
- Remote
- BSFDebugManagerImpl, DebugManagerStub
public interface BSFDebugManager
extends Remote
Debug Manager.
This is a service for remote debuggers to gain access
to remote debugging services on language engines.
Currently, there is only one debugger supported per
engine. However, multiple debuggers may register for
different engines. There may be more than one engine
per language given than more than one BSFManager can
be instanciated within a Java virtual machine.
Each debugger (instance of BSFDebugger) should first
register itself to a debug manager running in the Java
virtual machine in which debugging is intended.
A debugger registers for a specific language, such as
JavaScript.
As a consequence of registration, the debugger will be
notified of already existing engines as well as any
future creation or termination of engines for the
relevant language.
Upon this notification, the debugger can ask the engine
for its language-specific debugging interface and then
register the debugger callbacks for debugging events.
See org.apache.bsf.debug.jsdi.Callbacks for the JavaScript
example.
The debugging framework works on the concept of documents
and breakpoints. A document is basically a container for
scripts (be them functions, expressions, or actual scripts).
These scripts are subsets of the document. Documents are
declared to the BSFEngine when evaluating or executing some
scripts. Scripts are defined as a range, either line or
character range in their document. Correspondingly,
breakpoints can be set at lines or offsets in a document.
The line numbers and offsets are global numbers with respect
to the entire document.
So for instance, in a JSP with JavaScript, the document is
the JSP file. The scripts are the tags containing JavaScript
code. The Jasper compiler extracts the scripts from the JSP
and produces a Servlet that will provide these scripts to
the BSF JavaScript engine at execution time.
Each of these scripts start at a given line, offsets are
not supported. Breakpoints can therefore be set at lines
belonging to these JavaScript scripts, considering line
numbers at the document level, that is, the entire JSP file.
getLangFromFilename
public String getLangFromFilename(String fileName)
throws RemoteException
Determine the language of a script file by looking at the file
extension.
- the scripting language the file is in if the file extension
is known to me (must have been registered via
registerScriptingEngine).
isLanguageRegistered
public boolean isLanguageRegistered(String lang)
throws RemoteException
Determine whether a language is registered.
lang
- string identifying a language
placeBreakpointAtLine
public void placeBreakpointAtLine(int bpid,
String docname,
int lineno)
throws RemoteException
Breakpoints are placed within documents either at a specific line
or offset. While breakpoints can be set at lines and offsets in
the same document, there is no conversions between lines and offsets.
Some engines may support only offsets or only lines and therefore
some breakpoints may be ignored.
Placing a breakpoint is local to a debugger connection.
In other words, breakpoints set by other debuggers are not visible
to a given debugger.
Breakpoints are given identifiers so to make easier for debuggers
to manipulate breakpoints. Identifiers are allocated by the debugger;
they must be unique for the entire session between that debugger
and the debug manager.
placeBreakpointAtOffset
public void placeBreakpointAtOffset(int bpid,
String docname,
int offset)
throws RemoteException
registerDebugger
public void registerDebugger(String lang,
BSFDebugger debugger)
throws RemoteException
Register a debugger for a scripting engine.
lang
- string identifying language
removeBreakpoint
public void removeBreakpoint(String docname,
int brkptid)
throws RemoteException
Allows to remove a breakpoint.
setEntryExit
public void setEntryExit(String docname,
boolean on)
throws RemoteException
Allows setting entry/exit mode
supportBreakpointAtLine
public boolean supportBreakpointAtLine(String lang)
throws RemoteException
supportBreakpointAtOffset
public boolean supportBreakpointAtOffset(String lang)
throws RemoteException
Allows a debugger to ask if the engine for a given language
will support either line or offset breakpoints.
Note: this will most likely provoke the loading of the engine.
unregisterDebugger
public void unregisterDebugger(String lang)
throws RemoteException