Package com.inductiveautomation.ignition.common.script

Class ScriptManager

java.lang.Object

com.inductiveautomation.ignition.common.script.ScriptManager

public class ScriptManager
extends java.lang.Object

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ScriptManager.ExecutionInfo
static class	ScriptManager.ScriptCanceledError
protected class	ScriptManager.ScriptFunctionImpl
static class	ScriptManager.UndefinedFunctionException

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

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.:
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)
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
boolean	validatePackageName(java.lang.String newName)

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

log

protected static LoggerEx log

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

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

compileFunction

public ScriptFunction compileFunction(java.lang.String code)
                               throws org.python.core.PyException,
                                      JythonExecException,
                                      ScriptManager.UndefinedFunctionException

Compiles a function definition (normally generated through the Extension Function style scripting system), and returns a compiled function that can be used and reused. The function name will be extracted from the definition, so the code is expected to start with "def funcName(..."

Throws:

org.python.core.PyException - ex

JythonExecException - ex

ScriptManager.UndefinedFunctionException - ex

compileFunction

public ScriptFunction compileFunction(java.lang.String id,
                                      java.lang.String functionName,
                                      java.lang.String code)
                               throws org.python.core.PyException,
                                      JythonExecException,
                                      ScriptManager.UndefinedFunctionException

Overload of compileFunction that allows the caller to define the identifier used for the compiled object, and the method to extract from the code. This version is necessary if the code provided might define multiple functions.

Throws:

org.python.core.PyException - ex

JythonExecException - ex

ScriptManager.UndefinedFunctionException - ex

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

public boolean validatePackageName(java.lang.String newName)

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

main

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

executingScripts

public static java.util.Set<ScriptManager.ExecutionInfo> executingScripts()