Package com.ibm.di.script

Class ScriptEngine

  • public class ScriptEngine
extends java.lang.Object
    This is the script engine wrapper used by TDI components.

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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)