Package com.inductiveautomation.ignition.common.script

Class ScriptManager

  • public class ScriptManager
extends java.lang.Object

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.ThreadLocal<java.lang.Boolean> EDGE_SCRIPT_BYPASS  
      protected static LoggerEx log  

    • Constructor Summary

      Constructors 
      Constructor Description
      ScriptManager​(java.lang.String contextName)
      Initializes ScriptManager without a path to 3rd party system Python modules.
      ScriptManager​(java.lang.String contextName, java.lang.String pathToExternalLibs)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addGlobalVariable​(java.lang.String name, org.python.core.PyObject value)  
      void addScriptModule​(java.lang.String path, java.lang.Class<?> javaFunctionClass)
      Expose all static methods of javaFunctionClass as scripting functions.
      void addScriptModule​(java.lang.String path, java.lang.Class<?> javaFunctionClass, ScriptFunctionDocProvider docProvider)
      Expose all static methods of javaFunctionClass as scripting functions.
      void addScriptModule​(java.lang.String path, java.lang.Object obj)
      Expose all static and instance methods of obj as scripting functions.
      void addScriptModule​(java.lang.String path, java.lang.Object obj, ScriptFunctionDocProvider docProvider)
      Expose all static and instance methods of obj as scripting functions.
      void addScriptModule​(java.lang.String path, java.lang.String moduleCode)
      Adds a script module on the given path (e.g.
      void addScriptModule​(java.lang.String path, java.lang.String moduleCode, ScriptScopeStyle scopeStyle)  
      void addStaticFields​(java.lang.String path, java.lang.Class<?> clazz)
      Adds all public static final fields defined by this class as python variables in the given path.
      void addStdErrStream​(java.io.OutputStream os)  
      void addStdOutStream​(java.io.OutputStream os)  
      static void asynchInit()  
      static void asynchInit​(java.lang.String pathToExternalLibs)
      Initialize the Jython System.
      void clearAppModule()  
      void clearModule​(java.lang.String moduleName)
      Clears the given module's internal mapping
      void clearProjectScriptModules()
      Removes all project resource script modules
      void clearThirdPartyModules()
      Removes all modules that are not default to Ignition or have been added from project resources
      ScriptFunction compileFunction​(java.lang.String code)
      Compiles a function definition (normally generated through the Extension Function style scripting system), and returns a compiled function that can be used and reused.
      ScriptFunction compileFunction​(java.lang.String id, java.lang.String functionName, java.lang.String code)
      Overload of compileFunction that allows the caller to define the identifier used for the compiled object, and the method to extract from the code.
      protected void configureScriptContext()  
      org.python.core.PyStringMap createLocalsMap()
      Creates a new local namespace with the 'system', 'fpmi', ['app'], and project resource packages imported automatically.
      static org.python.core.PySystemState createUtf8PySystemState​(java.io.OutputStream stdOut, java.io.OutputStream stdErr)
      Initializes a PySystemState and sets the default encoding to utf-8.
      static java.util.Set<ScriptManager.ExecutionInfo> executingScripts()  
      org.python.core.PyStringMap getGlobals()
      Provides programmatic access to the global map
      java.util.Map<java.lang.String,​java.util.List<ScriptFunctionHint>> getHintsMap()
      Maps the first element of hint path to the entire path, e.g.:
      org.python.core.PyStringMap getModules()  
      java.util.UUID getUUID()  
      static void interrupt​(java.lang.Long threadId)  
      static void main​(java.lang.String[] args)  
      void removeStdErrStream​(java.io.OutputStream os)  
      void removeStdOutStream​(java.io.OutputStream os)  
      void runCode​(java.lang.String code, org.python.core.PyObject locals, java.lang.String filename)
      Compiles and then runs some python code with the given locals map.
      void runCode​(java.lang.String code, org.python.core.PyObject locals, org.python.core.PyObject globals, java.lang.String filename)
      Compiles and then runs some python code with the given locals map and globals map.
      void runCode​(org.python.core.PyCode code, org.python.core.PyObject locals)
      Runs compiled python code with the given locals map.
      void runCode​(org.python.core.PyCode code, org.python.core.PyObject locals, org.python.core.PyObject globals)
      Runs compiled python code with the given locals map and globals map.
      org.python.core.PyObject runFunction​(org.python.core.PyObject function, org.python.core.PyObject... arguments)  
      org.python.core.PyObject runFunction​(org.python.core.PyObject function, org.python.core.PyObject[] arguments, java.lang.String[] keywords)  
      void setContextName​(java.lang.String name)
      Resets this script manager's context name, which only affects logging
      void setPaused​(boolean paused)
      Sets the script manager to be 'paused'.
      protected void setState()
      Sets the python thread state to our PySystemState
      void shutdown()  
      boolean validatePackageName​(java.lang.String newName)
      Deprecated.
      Prefer ModuleLibrary's static validation methods - you can use getModules() to retrieve this manager's loaded modules to check against.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EDGE_SCRIPT_BYPASS

        public static final java.lang.ThreadLocal<java.lang.Boolean> EDGE_SCRIPT_BYPASS

    • Constructor Detail

      • ScriptManager

        public ScriptManager​(java.lang.String contextName)
        Initializes ScriptManager without a path to 3rd party system Python modules. Use this constructor if asynchInit has already been called and the path initialized, as a second call will be ignored.

      • ScriptManager

        public ScriptManager​(java.lang.String contextName,
                     java.lang.String pathToExternalLibs)

    • Method Detail

      • shutdown

        public void shutdown()

      • addStdOutStream

        public void addStdOutStream​(java.io.OutputStream os)

      • removeStdOutStream

        public void removeStdOutStream​(java.io.OutputStream os)

      • addStdErrStream

        public void addStdErrStream​(java.io.OutputStream os)

      • removeStdErrStream

        public void removeStdErrStream​(java.io.OutputStream os)

      • setContextName

        public void setContextName​(java.lang.String name)
        Resets this script manager's context name, which only affects logging

      • setState

        protected void setState()
        Sets the python thread state to our PySystemState

      • asynchInit

        public static void asynchInit​(java.lang.String pathToExternalLibs)
        Initialize the Jython System. If this is the first time that the system is initialized, Then it will be a somewhat lengthy processes, as the system package manager reads all system jars and caches them to a temp directory. This method allows the init method to safely be run in a background thread, because the constructor will wait for it to be done

      • asynchInit

        public static void asynchInit()

      • createUtf8PySystemState

        public static org.python.core.PySystemState createUtf8PySystemState​(java.io.OutputStream stdOut,
                                                                    java.io.OutputStream stdErr)
        Initializes a PySystemState and sets the default encoding to utf-8. Also wraps the supplied output stream in a PyFile that has the encoding set to utf-8.
        Parameters:
        stdOut - the standard output stream
        stdErr - the standard error stream
        Returns:
        a new PySystemState

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.String moduleCode)
        Adds a script module on the given path (e.g. "app.foo" or "shared.mystuff"). Uses legacy Python21 scoping style.

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.String moduleCode,
                            ScriptScopeStyle scopeStyle)

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.Class<?> javaFunctionClass)

        Expose all static methods of javaFunctionClass as scripting functions. Also exposes all static fields.

        These functions will be part of the auto-complete system, but will not have any documentation provided. To provide documentation as well use addScriptModule(String, Class, ScriptFunctionDocProvider).

        Parameters:
        path - The namespace to add these functions to i.e. "system.net".
        javaFunctionClass - The Class to search for static methods.

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.Class<?> javaFunctionClass,
                            ScriptFunctionDocProvider docProvider)

        Expose all static methods of javaFunctionClass as scripting functions. Also exposes all static fields.

        Parameters:
        path - The namespace to add these functions to i.e. "system.net".
        javaFunctionClass - The Class to search for static methods.
        docProvider - A ScriptFunctionDocProvider that can produce documentation for use in the hints system.

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.Object obj)

        Expose all static and instance methods of obj as scripting functions. Also exposes all static fields.

        These functions will be part of the auto-complete system, but will not have any documentation provided. To provide documentation as well use addScriptModule(String, Class, ScriptFunctionDocProvider).

        Parameters:
        path - The namespace to add these functions to i.e. "system.net".
        obj - The Object to search for static methods.

      • addScriptModule

        public void addScriptModule​(java.lang.String path,
                            java.lang.Object obj,
                            ScriptFunctionDocProvider docProvider)

        Expose all static and instance methods of obj as scripting functions. Also exposes all static fields.

        Parameters:
        path - The namespace to add these functions to i.e. "system.net".
        obj - The Object to search for static methods.
        docProvider - A ScriptFunctionDocProvider that can produce documentation for use in the hints system.

      • addStaticFields

        public void addStaticFields​(java.lang.String path,
                            java.lang.Class<?> clazz)
        Adds all public static final fields defined by this class as python variables in the given path.

      • clearAppModule

        public void clearAppModule()

      • clearModule

        public void clearModule​(java.lang.String moduleName)
        Clears the given module's internal mapping

      • clearProjectScriptModules

        public void clearProjectScriptModules()
        Removes all project resource script modules

      • clearThirdPartyModules

        public void clearThirdPartyModules()
        Removes all modules that are not default to Ignition or have been added from project resources

      • createLocalsMap

        public org.python.core.PyStringMap createLocalsMap()
        Creates a new local namespace with the 'system', 'fpmi', ['app'], and project resource packages imported automatically.

      • getGlobals

        public org.python.core.PyStringMap getGlobals()
        Provides programmatic access to the global map

      • addGlobalVariable

        public void addGlobalVariable​(java.lang.String name,
                              org.python.core.PyObject value)

      • runCode

        public void runCode​(java.lang.String code,
                    org.python.core.PyObject locals,
                    java.lang.String filename)
             throws JythonExecException
        Compiles and then runs some python code with the given locals map. Uses Python21 style scoping (shared global namespace)
        Parameters:
        code - the python script
        locals - locals map
        filename - source file name
        Throws:
        JythonExecException - ex
        See Also:
        ScriptScopeStyle.Python21

      • runCode

        public void runCode​(org.python.core.PyCode code,
                    org.python.core.PyObject locals)
             throws JythonExecException
        Runs compiled python code with the given locals map. Uses Python21 style scoping (shared global namespace)
        Parameters:
        code - the compiled python code
        locals - locals map
        Throws:
        JythonExecException - ex
        See Also:
        ScriptScopeStyle.Python21

      • runCode

        public void runCode​(java.lang.String code,
                    org.python.core.PyObject locals,
                    org.python.core.PyObject globals,
                    java.lang.String filename)
             throws JythonExecException
        Compiles and then runs some python code with the given locals map and globals map. Uses Python21 or Python25 style scoping, depending on the supplied globals map.
        Parameters:
        code - the python script
        locals - locals map
        globals - globals map
        filename - source file name
        Throws:
        JythonExecException - ex
        See Also:
        ScriptScopeStyle.Python21, ScriptScopeStyle.Python25

      • runCode

        public void runCode​(org.python.core.PyCode code,
                    org.python.core.PyObject locals,
                    org.python.core.PyObject globals)
             throws JythonExecException
        Runs compiled python code with the given locals map and globals map.
        Parameters:
        code - the compiled python code
        locals - locals map
        globals - globals map. If null, Python21 style scoping is used (shared global namespace).
        Throws:
        JythonExecException - ex

      • configureScriptContext

        protected void configureScriptContext()

      • runFunction

        public org.python.core.PyObject runFunction​(org.python.core.PyObject function,
                                            org.python.core.PyObject... arguments)
                                     throws JythonExecException
        Throws:
        JythonExecException

      • runFunction

        public org.python.core.PyObject runFunction​(org.python.core.PyObject function,
                                            org.python.core.PyObject[] arguments,
                                            java.lang.String[] keywords)
                                     throws JythonExecException
        Throws:
        JythonExecException

      • setPaused

        public void setPaused​(boolean paused)
        Sets the script manager to be 'paused'. When paused, scripts simply don't run at all.

      • getHintsMap

        public java.util.Map<java.lang.String,​java.util.List<ScriptFunctionHint>> getHintsMap()
        Maps the first element of hint path to the entire path, e.g.: 

         "path" -> ["path.to.autocomplete", "path.for.somethingelse"]
        Returns:
        The hints map.

      • interrupt

        public static void interrupt​(@Nonnull
                             java.lang.Long threadId)

      • getUUID

        public java.util.UUID getUUID()
        Returns:
        The UUID of this script manager, which can be used by other systems to determine if the script manager has recently been replaced (perhaps due to installing an updated module).

      • validatePackageName

        @Deprecated
public boolean validatePackageName​(java.lang.String newName)
        Deprecated.
        Prefer ModuleLibrary's static validation methods - you can use getModules() to retrieve this manager's loaded modules to check against.
        Parameters:
        newName - the proposed new package name
        Returns:
        true if the package does not exist in the system modules, and thus can safely be used as a new package name without conflicts

      • getModules

        public org.python.core.PyStringMap getModules()

      • main

        public static void main​(java.lang.String[] args)