de.ipcon.tools

Class GroovyScript

java.lang.Object

de.ipcon.tools.AbstractScript

de.ipcon.tools.GroovyScript

Direct Known Subclasses:

FilterGroovyScript, PaintGroovyScript

public class GroovyScript
extends AbstractScript

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	GroovyScript.Function
static class	GroovyScript.HGB

Field Summary

Fields inherited from class de.ipcon.tools.AbstractScript

RM_DEFAULT, RM_RESULT, RM_SCRIPT, SL_BEANSHELL, SL_DEFAULT, SL_GROOVY, STR_VALUES_FALSE, STR_VALUES_TRUE

Constructor Summary

Constructors

Constructor and Description
GroovyScript(java.lang.String _source, boolean _precompile) Instantiates a new Groovy script runner instance.
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl, java.util.Map<java.lang.String,java.lang.Object> _initialvars)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl, java.util.Map<java.lang.String,java.lang.Object> _initialvars, java.util.List<ScriptImport> _defaultImports)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl, java.util.Map<java.lang.String,java.lang.Object> _initialvars, java.util.List<ScriptImport> _defaultImports, java.lang.String _baseClassName)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl, java.util.Map<java.lang.String,java.lang.Object> _initialvars, java.util.List<ScriptImport> _defaultImports, java.lang.String _baseClassName, GroovyScript.HGB _binding)
GroovyScript(java.lang.String _source, boolean _precompile, GroovyScript _parent, java.lang.ClassLoader _cl, java.util.Map<java.lang.String,java.lang.Object> _initialvars, java.util.List<ScriptImport> _defaultImports, java.lang.String _baseClassName, GroovyScript.HGB _binding, java.lang.String _scriptname)

Method Summary

Modifier and Type	Method and Description
boolean	asBool(java.lang.Object o, boolean nullValue) Converts an object to a boolean.
static boolean	asBoolStatic(java.lang.Object o, boolean nullValue)
java.lang.Object	boolConverter(java.lang.Object o, java.lang.Object nullValue)
void	clear() Clears local variable bindings and cached execution state.
void	close() Closes this script instance, freeing up resources.
void	compileNT(int offset, java.lang.String errorTip) Compiles the script with a specified line offset and error tip.
static boolean	compilesToSame(java.lang.String sourceA, java.lang.String sourceB) Checks if the two given pieces of source code will result in the same actual script, that is not only differ in things like comments or whitespace.
ScriptFunctionI	createFunction(java.lang.String src, java.lang.String[] parmNames, java.lang.Class[] parmTypes, java.lang.Class returnType) Creates a function from a script source string.
ScriptFunctionI	createFunction(java.lang.String src, java.lang.String[] parmNames, java.lang.Class[] parmTypes, java.lang.Class returnType, java.lang.String scriptName, java.lang.String functionName) Creates a function from a script source string.
ScriptFunctionI	createFunction(java.lang.String src, java.lang.String[] parmNames, java.lang.Class[] parmTypes, java.lang.Class returnType, java.lang.String scriptName, java.lang.String functionName, int offset) Creates a function from a script source string.
ScriptFunctionI	createFunction(java.lang.String src, java.lang.String[] parmNames, java.lang.Class[] parmTypes, java.lang.Class returnType, java.lang.String scriptName, java.lang.String functionName, int offset, java.lang.Object delegate) Creates a function from a script source string.
void	createScript()
boolean	evalAsBoolNT(java.lang.String s, boolean nullValue, int offset, java.lang.String errorTip) Evaluates a string as a script with a specified null value and line offset and returns the result as boolean.
java.lang.Object	evalNT(java.lang.String s, java.lang.Object nullValue, int offset, java.lang.String errorTip) Evaluates a string as a script with a specified null value and line offset and returns the result as Object.
java.lang.Object	evalNT(java.lang.String s, java.lang.Object nullValue, int offset, java.lang.String errorTip, java.util.function.BiFunction typeConverter)
GroovyScript.HGB	getBinding()
org.codehaus.groovy.control.CompilerConfiguration	getCompilerConf()
groovy.lang.Script	getEvalScript(java.lang.String s)
groovy.lang.Script	getEvalScript(java.lang.String s, java.lang.String name)
java.lang.String	getLanguage() Returns the scripting language of this script instance.
int	getLineOffset()
java.lang.Object	getNT(java.lang.String name, java.lang.Object exValue) Gets the value of a variable from the script context.
GroovyScript	getParent()
groovy.lang.GroovyShell	getShell()
java.lang.String	getSource() Hierarchical Groovy Binding (HGB).
boolean	hasSource() Checks if this script has source code.
void	initShellInstance(java.lang.ClassLoader cl, java.util.List<ScriptImport> imports, java.lang.String baseClassName)
static boolean	isActualScript(java.lang.String _str) Checks if the given text, supposed to be script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments.
static boolean	isActualScriptNT(java.lang.String _str) Checks if the given text, supposed to be script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments.
static boolean	isActualScriptNT(java.lang.String _str, boolean _errorValue)
static boolean	isActualScriptNT(java.lang.String _str, boolean _errorValue, boolean _logException)
static boolean	isActualScriptTR(java.lang.String _src) Checks if the given text, supposed to be syntactically valid script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments.
static boolean	isActualScriptTR(java.lang.String _src, java.lang.String _msg)
static boolean	isValidVarName(java.lang.Object o) Checks if the passed Object is a valid variable name for Groovy.
int	nextFunctionCounter()
int	nextScriptCounter()
static java.lang.String	replaceCustomLogicalOperators(java.lang.String scriptCode) Replaces our custom logical operators (for hassle-free usage in XML, avoiding a CDATA block just for that) in the given string with standard Groovy logical operators.
java.lang.Object	runAsObjectNT(java.lang.Object nullValue, int offset, java.lang.String errorTip) Executes the compiled script and returns the result as an arbitrary Object.
void	setBinding(GroovyScript.HGB $16)
void	setCompilerConf(org.codehaus.groovy.control.CompilerConfiguration $15)
void	setLineOffset(int $12) Sets an offset for line numbers, used for error reporting.
void	setNT(java.lang.String name, java.lang.Object value, boolean local) Sets a variable, optionally with local scope.
void	setParent(GroovyScript $13)
void	setPrecompile(boolean _b) Sets the pre-compile flag.
void	setShell(groovy.lang.GroovyShell $14)
void	setSource(java.lang.String $11) Sets the source code of this script.

Methods inherited from class de.ipcon.tools.AbstractScript

asString, compileNT, compileNT, evalAsBoolNT, evalAsBoolNT, evalAsBoolNT, evalAsStringNT, evalAsStringNT, evalAsStringNT, evalAsStringNT, evalNT, evalNT, evalNT, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInterrupt, getJavaSyntaxImports, getJavaSyntaxImports, getNT, isScriptException, runAsBoolNT, runAsBoolNT, runAsBoolNT, runAsBoolNT, runAsObjectNT, runAsObjectNT, runAsObjectNT, runAsStringNT, runAsStringNT, runAsStringNT, runAsStringNT, runNT, runNT, runNT, setInterrupt, setNT, setNT, setNT, setNT, setNT, setNT, setNT, setNT, setNT, setNT, setNT, setNT

Methods inherited from class java.lang.Object

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

Constructor Detail

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile)

Instantiates a new Groovy script runner instance.

Parameters:

_source - raw script source code

_precompile - if true, compiles the script into bytecode immediately upon instantiation

_parent - optional parent script to inherit variable bindings from

_cl - custom classloader for resolving domain dependencies

_initialvars - initial key-value pairs populated into the execution scope

_defaultImports - list of default import descriptors automatically prepended to the script

_baseClassName - optional base script class extending Script

_binding - custom hierarchical binding context instance (HGB)

_scriptname - identifier used for debugging, stack traces, and profiler metrics

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl,
                    java.util.Map<java.lang.String,java.lang.Object> _initialvars)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl,
                    java.util.Map<java.lang.String,java.lang.Object> _initialvars,
                    java.util.List<ScriptImport> _defaultImports)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl,
                    java.util.Map<java.lang.String,java.lang.Object> _initialvars,
                    java.util.List<ScriptImport> _defaultImports,
                    java.lang.String _baseClassName)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl,
                    java.util.Map<java.lang.String,java.lang.Object> _initialvars,
                    java.util.List<ScriptImport> _defaultImports,
                    java.lang.String _baseClassName,
                    GroovyScript.HGB _binding)

GroovyScript

public GroovyScript(java.lang.String _source,
                    boolean _precompile,
                    GroovyScript _parent,
                    java.lang.ClassLoader _cl,
                    java.util.Map<java.lang.String,java.lang.Object> _initialvars,
                    java.util.List<ScriptImport> _defaultImports,
                    java.lang.String _baseClassName,
                    GroovyScript.HGB _binding,
                    java.lang.String _scriptname)

Method Detail

replaceCustomLogicalOperators

public static java.lang.String replaceCustomLogicalOperators(java.lang.String scriptCode)

Replaces our custom logical operators (for hassle-free usage in XML, avoiding a CDATA block just for that) in the given string with standard Groovy logical operators.

This method transforms custom logical operators "@and" and "@or" into "&&" and "||" respectively. It is particularly useful for converting Groovy script strings coming from XML that contain non-standard logical syntax for avoiding a CDATA block into a format that is compatible with Groovy's standard logical operators.

Example Usage:

 
 String groovyScript = "true @and false @or true";
 String convertedScript = replaceCustomLogicalOperators(groovyScript);
 System.out.println(convertedScript); // Output: true && false || true
 
 

Parameters:

scriptCode - the input string containing custom logical operators

Returns:

a new string with the custom logical operators replaced by standard Groovy logical operators or null if the input string was null

setPrecompile

public void setPrecompile(boolean _b)

Description copied from class: AbstractScript

Sets the pre-compile flag.

Specified by:

setPrecompile in class AbstractScript

Parameters:

_b - The boolean value for the pre-compile flag.

hasSource

public boolean hasSource()

Description copied from class: AbstractScript

Checks if this script has source code.

Specified by:

hasSource in class AbstractScript

Returns:

true if source code is present, false otherwise.

getLanguage

public java.lang.String getLanguage()

Description copied from class: AbstractScript

Returns the scripting language of this script instance.

Specified by:

getLanguage in class AbstractScript

Returns:

The language as a String (e.g., "beanshell", "groovy").

nextScriptCounter

public int nextScriptCounter()

nextFunctionCounter

public int nextFunctionCounter()

initShellInstance

public void initShellInstance(java.lang.ClassLoader cl,
                              java.util.List<ScriptImport> imports,
                              java.lang.String baseClassName)

getNT

public java.lang.Object getNT(java.lang.String name,
                              java.lang.Object exValue)

Description copied from class: AbstractScript

Gets the value of a variable from the script context.

Specified by:

getNT in class AbstractScript

Parameters:

name - The name of the variable to retrieve the value of.

exValue - This parameter is unused in all implementing classes. Maybe it was once intended to be a default value?

Returns:

The value of the variable with the passed name.

setNT

public void setNT(java.lang.String name,
                  java.lang.Object value,
                  boolean local)

Description copied from class: AbstractScript

Sets a variable, optionally with local scope.

Specified by:

setNT in class AbstractScript

Parameters:

name - The name of the variable to set.

value - The value of the variable to set.

local - A flag indicating if the variable shall have a local scope.

runAsObjectNT

public java.lang.Object runAsObjectNT(java.lang.Object nullValue,
                                      int offset,
                                      java.lang.String errorTip)

Executes the compiled script and returns the result as an arbitrary Object.

Specified by:

runAsObjectNT in class AbstractScript

Parameters:

nullValue - currently unused; retained for consistency with abstract super class

offset - line adjustment offset applied to runtime stack traces for error reporting

errorTip - diagnostic hint displayed in error reports when script evaluation fails

Returns:

script execution result

Throws:

GroovyScriptException - if script execution throws a runtime exception

getEvalScript

public groovy.lang.Script getEvalScript(java.lang.String s)

getEvalScript

public groovy.lang.Script getEvalScript(java.lang.String s,
                                        java.lang.String name)

evalNT

public java.lang.Object evalNT(java.lang.String s,
                               java.lang.Object nullValue,
                               int offset,
                               java.lang.String errorTip)

Description copied from class: AbstractScript

Evaluates a string as a script with a specified null value and line offset and returns the result as Object.

Specified by:

evalNT in class AbstractScript

Parameters:

s - The source of the script to evaluate.

nullValue - The value to return if the evaluation returns null.

offset - An integer line offset to use for error reporting.

errorTip - A string to use as an error message tip if evaluation fails.

Returns:

The result of the script evaluation as Object or "nullValue" if the evaluation returned null.

evalNT

public java.lang.Object evalNT(java.lang.String s,
                               java.lang.Object nullValue,
                               int offset,
                               java.lang.String errorTip,
                               java.util.function.BiFunction typeConverter)

evalAsBoolNT

public boolean evalAsBoolNT(java.lang.String s,
                            boolean nullValue,
                            int offset,
                            java.lang.String errorTip)

Description copied from class: AbstractScript

Evaluates a string as a script with a specified null value and line offset and returns the result as boolean.

Overrides:

evalAsBoolNT in class AbstractScript

Parameters:

s - The source of the script to evaluate.

nullValue - The value to return if the evaluation returns null.

offset - An integer line offset to use for error reporting.

errorTip - A string to use as an error message tip if evaluation fails.

Returns:

The result of the script evaluation as boolean or "nullValue" if the evaluation returned null.

boolConverter

public java.lang.Object boolConverter(java.lang.Object o,
                                      java.lang.Object nullValue)

compileNT

public void compileNT(int offset,
                      java.lang.String errorTip)

Description copied from class: AbstractScript

Compiles the script with a specified line offset and error tip.

Specified by:

compileNT in class AbstractScript

Parameters:

offset - An integer line offset to use for error reporting.

errorTip - A string to use as an error message tip if compilation fails.

close

public void close()

Description copied from class: AbstractScript

Closes this script instance, freeing up resources.

Overrides:

close in class AbstractScript

clear

public void clear()

Clears local variable bindings and cached execution state.

Delegates to the underlying GroovyScript.HGB binding hierarchy to ensure bound variables and closure delegates do not leak into long-lived heaps.

Specified by:

clear in class AbstractScript

createScript

public void createScript()

createFunction

public ScriptFunctionI createFunction(java.lang.String src,
                                      java.lang.String[] parmNames,
                                      java.lang.Class[] parmTypes,
                                      java.lang.Class returnType)

Description copied from class: AbstractScript

Creates a function from a script source string.

Specified by:

createFunction in class AbstractScript

Parameters:

src - The script source code.

parmNames - An array of names for the function's parameters.

parmTypes - An array of Class objects representing the types of the function's parameters.

returnType - The Class object representing the return type of the function.

Returns:

A ScriptFunctionI instance representing the created function.

createFunction

public ScriptFunctionI createFunction(java.lang.String src,
                                      java.lang.String[] parmNames,
                                      java.lang.Class[] parmTypes,
                                      java.lang.Class returnType,
                                      java.lang.String scriptName,
                                      java.lang.String functionName)

Description copied from class: AbstractScript

Creates a function from a script source string.

Specified by:

createFunction in class AbstractScript

Parameters:

src - The script source code.

parmNames - An array of names for the function's parameters.

parmTypes - An array of Class objects representing the types of the function's parameters.

returnType - The Class object representing the return type of the function.

scriptName - The name of the script, used for debugging and error reporting.

functionName - The name of the function.

Returns:

A ScriptFunctionI instance representing the created function.

createFunction

public ScriptFunctionI createFunction(java.lang.String src,
                                      java.lang.String[] parmNames,
                                      java.lang.Class[] parmTypes,
                                      java.lang.Class returnType,
                                      java.lang.String scriptName,
                                      java.lang.String functionName,
                                      int offset)

Description copied from class: AbstractScript

Creates a function from a script source string.

Specified by:

createFunction in class AbstractScript

Parameters:

src - The script source code.

parmNames - An array of names for the function's parameters.

parmTypes - An array of Class objects representing the types of the function's parameters.

returnType - The Class object representing the return type of the function.

scriptName - The name of the script, used for debugging and error reporting.

functionName - The name of the function.

offset - An integer line offset to use for error reporting.

Returns:

A ScriptFunctionI instance representing the created function.

createFunction

public ScriptFunctionI createFunction(java.lang.String src,
                                      java.lang.String[] parmNames,
                                      java.lang.Class[] parmTypes,
                                      java.lang.Class returnType,
                                      java.lang.String scriptName,
                                      java.lang.String functionName,
                                      int offset,
                                      java.lang.Object delegate)

Description copied from class: AbstractScript

Creates a function from a script source string.

Specified by:

createFunction in class AbstractScript

Parameters:

src - The script source code.

parmNames - An array of names for the function's parameters.

parmTypes - An array of Class objects representing the types of the function's parameters.

returnType - The Class object representing the return type of the function.

scriptName - The name of the script, used for debugging and error reporting.

functionName - The name of the function.

offset - An integer line offset to use for error reporting.

delegate - The object to which the function's method calls will be delegated.

Returns:

A ScriptFunctionI instance representing the created function.

isActualScript

public static boolean isActualScript(java.lang.String _str)
                              throws groovyjarjarantlr.RecognitionException,
                                     groovyjarjarantlr.TokenStreamException

Checks if the given text, supposed to be script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments. Test is performed via actual GroovyRecognizer (and not just custom regexps or similar), so should be very reliable. Will pass through all Exceptions that can occur if _str is not parseable as a GroovyScript.

Parameters:

_str - the supposed-to-be-script-source text.

Returns:

true if _str is an actual script (one that isn't null, empty or only comments); false if not.

Throws:

groovyjarjarantlr.RecognitionException

groovyjarjarantlr.TokenStreamException

isActualScriptTR

public static boolean isActualScriptTR(java.lang.String _src)
                                throws IRuntimeException

Checks if the given text, supposed to be syntactically valid script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments. Test is performed via actual GroovyRecognizer (and not just custom regexps or similar), so should be very reliable. Will internally catch RecognitionException and TokenStreamException and wrap them in an IRuntimeException. This is a convenience method to be used when one can be - almost - sure that _str will indeed be syntactically valid Groovy and so one does not want to (as one does not have to need to) catch the exceptions that theoretically might occur.

Parameters:

_src - the script source, supposed to be valid Groovy script syntax if not null or empty string.

Throws:

IRuntimeException

isActualScriptTR

public static boolean isActualScriptTR(java.lang.String _src,
                                       java.lang.String _msg)
                                throws IRuntimeException

Throws:

IRuntimeException

isActualScriptNT

public static boolean isActualScriptNT(java.lang.String _str)

Checks if the given text, supposed to be script source, actually results in a valid (Groovy) script, that is one that does not completely consist only of comments. Test is performed via actual GroovyRecognizer (and not just custom regexps or similar), so should be very reliable.

Parameters:

_str - the supposed-to-be-script-source text.

_errorValue - boolean value that is returned when the parsing of _str resulted in an error, that is the given text could not be parsed by the GroovyRecognizer. If a syntactically invalid script is seen as "actual script" will depend on where this method is called and so is configurable via this value. Defaults to false.

_logException - if true, parsing (and other) exceptions during the check will produce a message in the log; if false (the default) they will not produce any output.

Returns:

true if _str is an actual script (one that isn't null, empty or only comments); false if not; _errorValue when an exception occurred during the check, for example when _str couldn't be parsed by the GroovyRecognizer.

isActualScriptNT

public static boolean isActualScriptNT(java.lang.String _str,
                                       boolean _errorValue)

isActualScriptNT

public static boolean isActualScriptNT(java.lang.String _str,
                                       boolean _errorValue,
                                       boolean _logException)

asBool

public boolean asBool(java.lang.Object o,
                      boolean nullValue)

Description copied from class: AbstractScript

Converts an object to a boolean.

Overrides:

asBool in class AbstractScript

Parameters:

o - The Object to convert.

nullValue - The value to return if the passed object is null.

Returns:

The boolean representation of the passed Object, or "nullValue" if the passed object is null.

asBoolStatic

public static boolean asBoolStatic(java.lang.Object o,
                                   boolean nullValue)

isValidVarName

public static boolean isValidVarName(java.lang.Object o)

Checks if the passed Object is a valid variable name for Groovy. Three checks are made currently: 1. Is the passed object a String? 2. Is the passed String no Groovy keyword? 3. Does the passed String match the Groovy variable name rules? If all three answers are yes, the passed object may be used as a variable name.

Parameters:

o - the object to test

Returns:

true if o is a valid variable name, false otherwise

compilesToSame

public static boolean compilesToSame(java.lang.String sourceA,
                                     java.lang.String sourceB)

Checks if the two given pieces of source code will result in the same actual script, that is not only differ in things like comments or whitespace. The comparison is done via actual Groovy source code parsing which means that it is a bit costly but should be very reliable. It should not result in false positives but may result in false negatives for scripts which a human (or AI ;-) might consider "equivalent". This method can be of use if a "real" change of a script must result in - possibly costly - recalculation or updating of things while only cosmetical changes do not require that (examples of this will be in the alarm system code).

getSource

public java.lang.String getSource()

Hierarchical Groovy Binding (HGB).

Provides scoped variable management supporting parent inheritance, thread isolation, and explicit cleanup mechanics for Groovy executions.

Specified by:

getSource in class AbstractScript

Returns:

The source code as a String.

setSource

public void setSource(java.lang.String $11)

Description copied from class: AbstractScript

Sets the source code of this script.

Specified by:

setSource in class AbstractScript

Parameters:

$11 - The new source code as a String.

getLineOffset

public int getLineOffset()

setLineOffset

public void setLineOffset(int $12)

Description copied from class: AbstractScript

Sets an offset for line numbers, used for error reporting.

Specified by:

setLineOffset in class AbstractScript

Parameters:

$12 - The line offset.

getParent

public GroovyScript getParent()

setParent

public void setParent(GroovyScript $13)

getShell

public groovy.lang.GroovyShell getShell()

setShell

public void setShell(groovy.lang.GroovyShell $14)

getCompilerConf

public org.codehaus.groovy.control.CompilerConfiguration getCompilerConf()

setCompilerConf

public void setCompilerConf(org.codehaus.groovy.control.CompilerConfiguration $15)

getBinding

public GroovyScript.HGB getBinding()

setBinding

public void setBinding(GroovyScript.HGB $16)