org.apache.bsf

Interface BSFEngine

All Superinterfaces:

java.util.EventListener, java.beans.PropertyChangeListener

All Known Implementing Classes:

ActiveScriptEngine, BSFEngineImpl, JaclEngine, JavaClassEngine, JavaScriptEngine, JPythonEngine, JythonEngine, NetRexxEngine, XSLTEngine

public interface BSFEngine
extends java.beans.PropertyChangeListener

This is the view of a scripting engine assumed by the bean scripting framework. This interface is used when an application decides to run some script under application control. (This is the reverse of the more common situation, which is that of the scripting language calling into the application.)

When a scripting engine is first fired up, the initialize() method is called right after construction.

A scripting engine must provide two access points for applications to call into them: via function calls and via expression evaluation. It must also support loading scripts.

A scripting engine is a property change listener and will be notified when any of the relevant properties of the manager change. (See BSFManager to see which of its properties are bound.)

Author:

Sanjiva Weerawarana, Matthew J. Duftler

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	apply(java.lang.String source, int lineNo, int columnNo, java.lang.Object funcBody, java.util.Vector paramNames, java.util.Vector arguments) This is used by an application to invoke an anonymous function.
java.lang.Object	call(java.lang.Object object, java.lang.String name, java.lang.Object[] args) This is used by an application to call into the scripting engine to make a function/method call.
void	compileApply(java.lang.String source, int lineNo, int columnNo, java.lang.Object funcBody, java.util.Vector paramNames, java.util.Vector arguments, CodeBuffer cb) This is used by an application to compile an anonymous function.
void	compileExpr(java.lang.String source, int lineNo, int columnNo, java.lang.Object expr, CodeBuffer cb) This is used by an application to compile a value-returning expression.
void	compileScript(java.lang.String source, int lineNo, int columnNo, java.lang.Object script, CodeBuffer cb) This is used by an application to compile some script.
void	declareBean(BSFDeclaredBean bean) Declare a bean after the engine has been started.
void	disconnectedDebuggerNotify() Notify the engine that the connection to its debugger has been lost.
java.lang.Object	eval(java.lang.String source, int lineNo, int columnNo, java.lang.Object expr) This is used by an application to evaluate an expression.
void	exec(java.lang.String source, int lineNo, int columnNo, java.lang.Object script) This is used by an application to execute some script.
java.lang.Object	getSpecificDebuggingInterface() The language-specific interface on the engine for debugging...
void	initialize(BSFManager mgr, java.lang.String lang, java.util.Vector declaredBeans) This method is used to initialize the engine right after construction.
void	placeBreakpointAtLine(int brkptid, java.lang.String docname, int lineno)
void	placeBreakpointAtOffset(int brkptid, java.lang.String docname, int offset)
void	removeBreakpoint(java.lang.String docname, int brkptid)
void	setEntryExit(java.lang.String docname, boolean on)
void	terminate() Graceful termination
void	undeclareBean(BSFDeclaredBean bean) Undeclare a previously declared bean.

Methods inherited from interface java.beans.PropertyChangeListener

propertyChange

Method Detail

disconnectedDebuggerNotify

void disconnectedDebuggerNotify()

Notify the engine that the connection to its debugger has been lost.

getSpecificDebuggingInterface

java.lang.Object getSpecificDebuggingInterface()

The language-specific interface on the engine for debugging...

placeBreakpointAtLine

void placeBreakpointAtLine(int brkptid,
                         java.lang.String docname,
                         int lineno)
                           throws BSFException

Throws:

BSFException

placeBreakpointAtOffset

void placeBreakpointAtOffset(int brkptid,
                           java.lang.String docname,
                           int offset)
                             throws BSFException

Throws:

BSFException

removeBreakpoint

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

Throws:

BSFException

setEntryExit

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

Throws:

BSFException

apply

java.lang.Object apply(java.lang.String source,
                     int lineNo,
                     int columnNo,
                     java.lang.Object funcBody,
                     java.util.Vector paramNames,
                     java.util.Vector arguments)
                       throws BSFException

This is used by an application to invoke an anonymous function. An anonymous function is a multi-line script which when evaluated will produce a value. These are separated from expressions and scripts because the prior are spsed to be good 'ol expressions and scripts are not value returning. We allow anonymous functions to have parameters as well for completeness.

Parameters:

source - (context info) the source of this expression (e.g., filename)

lineNo - (context info) the line number in source for expr

columnNo - (context info) the column number in source for expr

funcBody - the multi-line, value returning script to evaluate

paramNames - the names of the parameters above assumes

arguments - values of the above parameters

Throws:

BSFException - if anything goes wrong while doin' it.

call

java.lang.Object call(java.lang.Object object,
                    java.lang.String name,
                    java.lang.Object[] args)
                      throws BSFException

This is used by an application to call into the scripting engine to make a function/method call. The "object" argument is the object whose method is to be called, if that applies. For non-OO languages, this is typically ignored and should be given as null. For pretend-OO languages such as VB, this would be the (String) name of the object. The arguments are given in the args array.

Parameters:

object - object on which to make the call

name - name of the method / procedure to call

args - the arguments to be given to the procedure

Throws:

BSFException - if anything goes wrong while eval'ing a BSFException is thrown. The reason indicates the problem.

compileApply

void compileApply(java.lang.String source,
                int lineNo,
                int columnNo,
                java.lang.Object funcBody,
                java.util.Vector paramNames,
                java.util.Vector arguments,
                CodeBuffer cb)
                  throws BSFException

This is used by an application to compile an anonymous function. See comments in apply for more hdetails.

Parameters:

source - (context info) the source of this expression (e.g., filename)

lineNo - (context info) the line number in source for expr

columnNo - (context info) the column number in source for expr

funcBody - the multi-line, value returning script to evaluate

paramNames - the names of the parameters above assumes

arguments - values of the above parameters

cb - the CodeBuffer to compile into

Throws:

BSFException - if anything goes wrong while doin' it.

compileExpr

void compileExpr(java.lang.String source,
               int lineNo,
               int columnNo,
               java.lang.Object expr,
               CodeBuffer cb)
                 throws BSFException

This is used by an application to compile a value-returning expression. The expr may be string or some other type, depending on the language. The generated code is dumped into the CodeBuffer.

Parameters:

source - (context info) the source of this expression (e.g., filename)

lineNo - (context info) the line number in source for expr

columnNo - (context info) the column number in source for expr

expr - the expression to compile

cb - the CodeBuffer to compile into

Throws:

BSFException - if anything goes wrong while compiling a BSFException is thrown. The reason indicates the problem.

compileScript

void compileScript(java.lang.String source,
                 int lineNo,
                 int columnNo,
                 java.lang.Object script,
                 CodeBuffer cb)
                   throws BSFException

This is used by an application to compile some script. The script may be string or some other type, depending on the language. The generated code is dumped into the CodeBuffer.

Parameters:

source - (context info) the source of this script (e.g., filename)

lineNo - (context info) the line number in source for script

columnNo - (context info) the column number in source for script

script - the script to compile

cb - the CodeBuffer to compile into

Throws:

BSFException - if anything goes wrong while compiling a BSFException is thrown. The reason indicates the problem.

declareBean

void declareBean(BSFDeclaredBean bean)
                 throws BSFException

Declare a bean after the engine has been started. Declared beans are beans that are named and which the engine must make available to the scripts it runs in the most first class way possible.

Parameters:

bean - the bean to declare

Throws:

BSFException - if the engine cannot do this operation

eval

java.lang.Object eval(java.lang.String source,
                    int lineNo,
                    int columnNo,
                    java.lang.Object expr)
                      throws BSFException

This is used by an application to evaluate an expression. The expression may be string or some other type, depending on the language. (For example, for BML it'll be an org.w3c.dom.Element object.)

Parameters:

source - (context info) the source of this expression (e.g., filename)

lineNo - (context info) the line number in source for expr

columnNo - (context info) the column number in source for expr

expr - the expression to evaluate

Throws:

BSFException - if anything goes wrong while eval'ing a BSFException is thrown. The reason indicates the problem.

exec

void exec(java.lang.String source,
        int lineNo,
        int columnNo,
        java.lang.Object script)
          throws BSFException

This is used by an application to execute some script. The expression may be string or some other type, depending on the language. Returns nothing but if something goes wrong it excepts (of course).

Parameters:

source - (context info) the source of this expression (e.g., filename)

lineNo - (context info) the line number in source for expr

columnNo - (context info) the column number in source for expr

script - the script to execute

Throws:

BSFException - if anything goes wrong while exec'ing a BSFException is thrown. The reason indicates the problem.

initialize

void initialize(BSFManager mgr,
              java.lang.String lang,
              java.util.Vector declaredBeans)
                throws BSFException

This method is used to initialize the engine right after construction. This method will be called before any calls to eval or call. At this time the engine should capture the current values of interesting properties from the manager. In the future, any changes to those will be mirrored to me by the manager via a property change event.

Parameters:

mgr - The BSFManager that's hosting this engine.

lang - Language string which this engine is handling.

declaredBeans - Vector of BSFDeclaredObject containing beans that should be declared into the language runtime at init time as best as possible.

Throws:

BSFException - if anything goes wrong while init'ing a BSFException is thrown. The reason indicates the problem.

terminate

void terminate()

Graceful termination

undeclareBean

void undeclareBean(BSFDeclaredBean bean)
                   throws BSFException

Undeclare a previously declared bean.

Parameters:

bean - the bean to undeclare

Throws:

BSFException - if the engine cannot do this operation