com.ibm.di.script
Class ScriptEngine

java.lang.Object
  com.ibm.di.script.ScriptEngine

public class ScriptEngine
extends java.lang.Object

This is the script engine wrapper used by TDI components.

Constructor Summary

ScriptEngine(java.lang.String scriptlang)
Constructor

ScriptEngine(java.lang.String scriptlang, RSInterface server)
Constructor for the ScriptEngine object.

ScriptEngine(java.lang.String scriptlang, RSInterface server, boolean debug)

Method Summary

void	addDebugListener(ScriptEngineOptions.TDIDebugListener listener) Adds a listener to the list of debug callbacks.
java.lang.Object	call(java.lang.String function, java.lang.Object[] param) Calls a script function with given parameters.
java.lang.Object	call(java.lang.String function, java.lang.Object[] param, boolean ignoreMissing) Calls a script function with given parameters.
void	clear() Remove all declared non-static beans from the engine and local cache.
void	clearAll() Remove all statically declared beans from the engine.
void	debug(java.lang.String msg) NOOP
void	declareBean(java.lang.String name, java.lang.Object obj) Declares a "transient" script variable
void	declareBean(java.lang.String name, java.lang.Object obj, java.lang.Class<?> cls) Declares a "transient" script variable
void	declareStaticBean(java.lang.String name, java.lang.Object obj) Declares a "static" script variable that stays in the engine until undeclared.
void	declareStaticBean(java.lang.String name, java.lang.Object obj, java.lang.Class<?> cls) Declares a "static" script variable that stays in the engine until undeclared.
void	declareTaskBean() Declares the "task" bean in the engine (the AssemblyLine).
void	declareTaskBean(java.lang.Object context) Declares the "task" bean in the engine (the AssemblyLine).
void	declareUserFunctions() Declare the standard java objects and user defined java objects as global variables in the engine.
void	dumpJSEngine() Dumps the IBM JavaScript engine's variables and assignments (nice for debugging).
java.lang.Object	eval(java.lang.String expression) Evaluates a script expression.
void	exec(java.lang.Object script) Execute script
void	exec(java.lang.Object script, java.lang.String name) Execute script
com.ibm.jscript.JSExpression	getCompiledExpression(java.lang.String source) Returns a previously compiled expression
boolean	getDebug() Returns current status of the debugMode flag.
ScriptExitCode	getExitCode() Gets the exitCode attribute of the ScriptEngine object
com.ibm.jscript.JSInterpreter	getJsengine() Returns the IBMJS interpreter.
ScriptEngineOptions	getJSOptions() Returns the ScriptEngineOptions object used by the script engine.
java.lang.String	getLanguage() Gets the language attribute of the ScriptEngine object
java.lang.String	getScriptPrefix() Returns the magic prefix used to signal the beginning of a script (not used internally by ScriptEngine).
void	includeAllScripts(MetamergeConfig mc) Include all scripts from the script library where auto-include is true.
void	includeScript(java.lang.String files) Includes a script from an external location (either file or URL)
void	includeScript(java.lang.String scriptName, java.lang.String files) Includes a script from an external location (either file or URL)
void	interpret(java.lang.String script) Calls the jsengine.interpret(script).
com.ibm.jscript.IValue	interpret(java.lang.String map, boolean registerFunctions) Calls the jsengine.interpret(exp), and unwraps some Exceptions.
boolean	isFunctionDefined(java.lang.String functionName) Returns true if a specific function exists in the script engine.
com.ibm.jscript.InterpretException	lastException(java.lang.Exception cause) Return the last InterpretException, to supply line number for easier error detection.
void	loadScript(RSInterface parent, java.lang.String contextName, java.lang.String name, boolean forceInclude) This method includes a script in the current script engine context.
void	loadScript(java.lang.String contextName, ScriptConfig map, boolean forceInclude) This method includes a script in the current script engine context.
void	popStackFrame() Restores script engine bean references from a previously saved stack (pushStackFrame())
void	pushStackFrame() Preserves all declared beans in a stack (see popStackFrame)
void	removeDebugListener(ScriptEngineOptions.TDIDebugListener listener) Removes the specified listener from the list of debug callbacks.
void	terminate() Release resources
void	undeclareBean(java.lang.String name) Removes the named script variable from the engine.
void	undeclareStaticBean(java.lang.String name) Removes the named script variable from the engine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScriptEngine

public ScriptEngine(java.lang.String scriptlang)
             throws java.lang.Exception

Constructor

Parameters:

scriptlang - Script language to use (ignored, always javascript)

Throws:

java.lang.Exception - Script

ScriptEngine

public ScriptEngine(java.lang.String scriptlang,
                    RSInterface server)
             throws java.lang.Exception

Constructor for the ScriptEngine object.

Parameters:

scriptlang - Script language to use (ignored, always javascript)

server - Hosting TDI config instance

Throws:

java.lang.Exception

ScriptEngine

public ScriptEngine(java.lang.String scriptlang,
                    RSInterface server,
                    boolean debug)
             throws java.lang.Exception

Throws:

java.lang.Exception

Method Detail

declareUserFunctions

public void declareUserFunctions()
                          throws java.lang.Exception

Declare the standard java objects and user defined java objects as global variables in the engine.

Throws:

java.lang.Exception

getLanguage

public java.lang.String getLanguage()

Gets the language attribute of the ScriptEngine object

Returns:

The language value, always "javascript".

getExitCode

public ScriptExitCode getExitCode()

Gets the exitCode attribute of the ScriptEngine object

Returns:

The exitCode value

declareTaskBean

public void declareTaskBean()
                     throws java.lang.Exception

Declares the "task" bean in the engine (the AssemblyLine).

Throws:

java.lang.Exception

declareTaskBean

public void declareTaskBean(java.lang.Object context)
                     throws java.lang.Exception

Declares the "task" bean in the engine (the AssemblyLine).

Parameters:

context -

Throws:

java.lang.Exception

declareStaticBean

public void declareStaticBean(java.lang.String name,
                              java.lang.Object obj)
                       throws java.lang.Exception

Declares a "static" script variable that stays in the engine until undeclared.

Parameters:

name - The script name (as used in the script)

obj - The java object name refers to

Throws:

java.lang.Exception

declareStaticBean

public void declareStaticBean(java.lang.String name,
                              java.lang.Object obj,
                              java.lang.Class<?> cls)
                       throws java.lang.Exception

Declares a "static" script variable that stays in the engine until undeclared.

Parameters:

name - The script name (as used in the script)

obj - The java object name refers to

cls - The class type of the object, ignored

Throws:

java.lang.Exception

undeclareStaticBean

public void undeclareStaticBean(java.lang.String name)
                         throws java.lang.Exception

Removes the named script variable from the engine. The name refers to a previously defined variable (declareStaticBean)

Parameters:

name - The script name (as used in the script)

Throws:

java.lang.Exception

declareBean

public void declareBean(java.lang.String name,
                        java.lang.Object obj)
                 throws java.lang.Exception

Declares a "transient" script variable

Parameters:

name - The script name (as used in the script)

obj - The java object that name refers to.

Throws:

java.lang.Exception

declareBean

public void declareBean(java.lang.String name,
                        java.lang.Object obj,
                        java.lang.Class<?> cls)
                 throws java.lang.Exception

Declares a "transient" script variable

Parameters:

name - The script name (as used in the script)

obj - The java object that name refers to.

cls - obj's class, ignored

Throws:

java.lang.Exception

undeclareBean

public void undeclareBean(java.lang.String name)

Removes the named script variable from the engine. The name refers to a previously defined variable (declareBean)

Parameters:

name - The script name (as used in the script)

pushStackFrame

public void pushStackFrame()

Preserves all declared beans in a stack (see popStackFrame)

popStackFrame

public void popStackFrame()

Restores script engine bean references from a previously saved stack (pushStackFrame())

eval

public java.lang.Object eval(java.lang.String expression)
                      throws java.lang.Exception

Evaluates a script expression.

Parameters:

expression - Script expression

Returns:

Returned result of the script evaluation

Throws:

java.lang.Exception

call

public java.lang.Object call(java.lang.String function,
                             java.lang.Object[] param)
                      throws java.lang.Exception

Calls a script function with given parameters. Before this method can be called, a script body defining the function must have been executed. This may be done explicitly by calling exec(script) or implicitly through the inclusion of global scripts.

Parameters:

function - Name of the function

param - Array of positional parameters

Returns:

The result from the function call

Throws:

java.lang.Exception - If any error occurs

call

public java.lang.Object call(java.lang.String function,
                             java.lang.Object[] param,
                             boolean ignoreMissing)
                      throws java.lang.Exception

Calls a script function with given parameters. Before this method can be called, a script body defining the function must have been executed. This may be done explicitly by calling exec(script) or implicitly through the inclusion of global scripts.

Parameters:

function - Name of the function

param - Array of positional parameters

ignoreMissing - If true, return null if function is missing. If false, throw an Exception if function is missing.

Returns:

The result from the function call

Throws:

java.lang.Exception - If any error occurs

exec

public void exec(java.lang.Object script)
          throws java.lang.Exception

Execute script

Parameters:

script - The script to execute

Throws:

java.lang.Exception

exec

public void exec(java.lang.Object script,
                 java.lang.String name)
          throws java.lang.Exception

Execute script

Parameters:

script - The script to execute

name - Name context (used in error messages etc)

Throws:

java.lang.Exception

clear

public void clear()

Remove all declared non-static beans from the engine and local cache.

clearAll

public void clearAll()

Remove all statically declared beans from the engine.

terminate

public void terminate()

Release resources

dumpJSEngine

public void dumpJSEngine()

Dumps the IBM JavaScript engine's variables and assignments (nice for debugging).

getScriptPrefix

public java.lang.String getScriptPrefix()

Returns the magic prefix used to signal the beginning of a script (not used internally by ScriptEngine).

Returns:

The scriptPrefix value

loadScript

public void loadScript(RSInterface parent,
                       java.lang.String contextName,
                       java.lang.String name,
                       boolean forceInclude)
                throws java.lang.Exception

This method includes a script in the current script engine context. Use this method to dynamically make functions and variables available in the script context.

Parameters:

parent - The RSInterface to get the configuration from

contextName - A name identifying the context

name - The script library name

forceInclude - Force inclusion of the script (in case autoinclude is false)

Throws:

java.lang.Exception

loadScript

public void loadScript(java.lang.String contextName,
                       ScriptConfig map,
                       boolean forceInclude)
                throws java.lang.Exception

This method includes a script in the current script engine context. Use this method to dynamically make functions and variables available in the script context.

Parameters:

contextName - A name identifying the context

map - The ScriptConfig object

forceInclude - Force inclusion of the script (in case autoinclude is false)

Throws:

java.lang.Exception

includeScript

public void includeScript(java.lang.String files)
                   throws java.lang.Exception

Includes a script from an external location (either file or URL)

Parameters:

files - CRLF separated list of files/URLs

Throws:

java.lang.Exception

includeScript

public void includeScript(java.lang.String scriptName,
                          java.lang.String files)
                   throws java.lang.Exception

Includes a script from an external location (either file or URL)

Parameters:

scriptName - Name of the script

files - CRLF separated list of files/URLs

Throws:

java.lang.Exception

includeAllScripts

public void includeAllScripts(MetamergeConfig mc)
                       throws java.lang.Exception

Include all scripts from the script library where auto-include is true.

Parameters:

mc - MetamergeConfig object from where scripts are included

Throws:

java.lang.Exception

debug

public void debug(java.lang.String msg)

NOOP

Parameters:

msg -

getDebug

public boolean getDebug()

Returns current status of the debugMode flag.

Returns:

Always returns false.

getCompiledExpression

public com.ibm.jscript.JSExpression getCompiledExpression(java.lang.String source)
                                                   throws java.lang.Exception

Returns a previously compiled expression

Parameters:

source - The script source

Returns:

The compiledExpression value

Throws:

java.lang.Exception

interpret

public void interpret(java.lang.String script)
               throws java.lang.Exception

Calls the jsengine.interpret(script). Use this method when you want to execute scripts without clearing beans.

Parameters:

script - The script

Throws:

java.lang.Exception

interpret

public com.ibm.jscript.IValue interpret(java.lang.String map,
                                        boolean registerFunctions)
                                 throws java.lang.Exception

Calls the jsengine.interpret(exp), and unwraps some Exceptions.

Parameters:

map - The string expression to interpret

Throws:

java.lang.Exception - The Exception thrown by the interpret method, but "com.ibm.di.*" Exceptions are unwrapped

lastException

public com.ibm.jscript.InterpretException lastException(java.lang.Exception cause)

Return the last InterpretException, to supply line number for easier error detection.

Parameters:

cause - The Exception that contains the cause of the last Exception.

Returns:

Returns the InterpretException if it was the cause of the last exception. Otherwise, null is returned.

getJsengine

public com.ibm.jscript.JSInterpreter getJsengine()

Returns the IBMJS interpreter.

Returns:

The IBMJS interpreter

isFunctionDefined

public boolean isFunctionDefined(java.lang.String functionName)

Returns true if a specific function exists in the script engine.

Parameters:

functionName - The function name

Returns:

Returns true if a specific function exists in the script engine. Otherwise, false is returned.

addDebugListener

public void addDebugListener(ScriptEngineOptions.TDIDebugListener listener)

Adds a listener to the list of debug callbacks. Callbacks are only done when the script engine was created with debug=true.

Parameters:

listener - The callback object

removeDebugListener

public void removeDebugListener(ScriptEngineOptions.TDIDebugListener listener)

Removes the specified listener from the list of debug callbacks.

Parameters:

listener - The callback object

getJSOptions

public ScriptEngineOptions getJSOptions()

Returns the ScriptEngineOptions object used by the script engine.