com.ibm.di.script
Class ScriptEngine

java.lang.Object
  extended by 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.
 java.lang.Object eval(java.lang.String expression, com.ibm.jscript.engine.IExecutionContext context)
          Evaluates a script expression with a context.
 void exec(java.lang.Object script)
          Execute script
 void exec(java.lang.Object script, java.lang.String name)
          Execute script
 java.lang.Object getBean(java.lang.String name)
          Returns the Object with the specifed name
 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 getRefID(java.lang.String script)
           
 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 includeAllScripts(MetamergeConfig mc, java.util.Set<ScriptConfig> excludedScripts)
          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.
 com.ibm.jscript.IValue interpret(java.lang.String map, boolean registerFunctions, java.lang.String sourceRefID)
          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

eval

public java.lang.Object eval(java.lang.String expression,
                             com.ibm.jscript.engine.IExecutionContext context)
                      throws java.lang.Exception
Evaluates a script expression with a context.

Parameters:
expression - Script expression
context - The IExecutionContext to use.
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,
                              java.util.Set<ScriptConfig> excludedScripts)
                       throws java.lang.Exception
Include all scripts from the script library where auto-include is true. Any script configs in the excludedScripts set is not included.

Parameters:
mc - MetamergeConfig object from where scripts are included
excludedScripts - ScriptConfig objets that are explicitly excluded
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

interpret

public com.ibm.jscript.IValue interpret(java.lang.String map,
                                        boolean registerFunctions,
                                        java.lang.String sourceRefID)
                                 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.


getBean

public java.lang.Object getBean(java.lang.String name)
Returns the Object with the specifed name

Parameters:
name -
Returns:
Since:
7.2

getRefID

public java.lang.String getRefID(java.lang.String script)