org.apache.bsf.debug

Interface BSFDebugManager

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

BSFDebugManagerImpl, DebugManagerStub

public interface BSFDebugManager
extends java.rmi.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.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getLangFromFilename(java.lang.String fileName) Determine the language of a script file by looking at the file extension.
boolean	isLanguageRegistered(java.lang.String lang) Determine whether a language is registered.
void	placeBreakpointAtLine(int bpid, java.lang.String docname, int lineno) Breakpoints are placed within documents either at a specific line or offset.
void	placeBreakpointAtOffset(int bpid, java.lang.String docname, int offset)
void	registerDebugger(java.lang.String lang, BSFDebugger debugger) Register a debugger for a scripting engine.
void	removeBreakpoint(java.lang.String docname, int brkptid) Allows to remove a breakpoint.
void	setEntryExit(java.lang.String docname, boolean on) Allows setting entry/exit mode
boolean	supportBreakpointAtLine(java.lang.String lang)
boolean	supportBreakpointAtOffset(java.lang.String lang) Allows a debugger to ask if the engine for a given language will support either line or offset breakpoints.
void	unregisterDebugger(java.lang.String lang)

Method Detail

getLangFromFilename

java.lang.String getLangFromFilename(java.lang.String fileName)
                                     throws java.rmi.RemoteException

Determine the language of a script file by looking at the file extension.

Parameters:

filename - the name of the file

Returns:

the scripting language the file is in if the file extension is known to me (must have been registered via registerScriptingEngine).

Throws:

BSFException - if file's extension is unknown.

java.rmi.RemoteException

isLanguageRegistered

boolean isLanguageRegistered(java.lang.String lang)
                             throws java.rmi.RemoteException

Determine whether a language is registered.

Parameters:

lang - string identifying a language

Returns:

true iff it is

Throws:

java.rmi.RemoteException

placeBreakpointAtLine

void placeBreakpointAtLine(int bpid,
                         java.lang.String docname,
                         int lineno)
                           throws java.rmi.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.

Throws:

java.rmi.RemoteException

placeBreakpointAtOffset

void placeBreakpointAtOffset(int bpid,
                           java.lang.String docname,
                           int offset)
                             throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException

removeBreakpoint

void removeBreakpoint(java.lang.String docname,
                    int brkptid)
                      throws java.rmi.RemoteException

Allows to remove a breakpoint.

Throws:

java.rmi.RemoteException

setEntryExit

void setEntryExit(java.lang.String docname,
                boolean on)
                  throws java.rmi.RemoteException

Allows setting entry/exit mode

Throws:

java.rmi.RemoteException

supportBreakpointAtOffset

boolean supportBreakpointAtOffset(java.lang.String lang)
                                  throws java.rmi.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.

Throws:

java.rmi.RemoteException

supportBreakpointAtLine

boolean supportBreakpointAtLine(java.lang.String lang)
                                throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException

registerDebugger

void registerDebugger(java.lang.String lang,
                    BSFDebugger debugger)
                      throws java.rmi.RemoteException

Register a debugger for a scripting engine.

Parameters:

lang - string identifying language

Throws:

java.rmi.RemoteException - if the language is unknown (i.e., if it has not been registered) with a reason of REASON_UNKNOWN_LANGUAGE. If the language is known but if the interface can't be created for some reason, then the reason is set to REASON_OTHER_ERROR and the actual exception is passed on as well.

unregisterDebugger

void unregisterDebugger(java.lang.String lang)
                        throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException