Interface IScriptEvaluator
- All Superinterfaces:
ICookable
,IMultiCookable
- All Known Implementing Classes:
ScriptEvaluator
,ScriptEvaluator
The syntax of the script to compile is a sequence of import declarations (not allowed if you compile many scripts at a time, see below) followed by a sequence of statements, as defined in the Java Language Specification, Java SE 7 Edition, sections 7.5 and 14.
An implementation may or may not implement the concept of "local methods", i.e. method declarations being freely intermixed with statements.
Example:
import java.text.*; System.out.println("HELLO"); System.out.println(new DecimalFormat("####,###.##").format(a));
(Notice that this expression refers to a parameter "a", as explained below.)
The script may complete abnormally, e.g. through a RETURN statement:
if (a == null) { System.out.println("Oops!"); return; }
Optionally, the script may be declared with a non-void return type. In this case, the last statement of the script must be a RETURN statement (or a THROW statement), and all RETURN statements in the script must return a value with the given type.
The script evaluator is implemented by creating and compiling a temporary compilation unit defining one class with one method the body of which consists of the statements of the script.
To set up a IScriptEvaluator
object, proceed as follows:
- Create an
IScriptEvaluator
-implementing class. -
Configure the
IScriptEvaluator
by calling any of the following methods: -
Call any of the
Cookable.cook(Reader)
methods to scan, parse, compile and load the script into the JVM.
After the IScriptEvaluator
object is created, the script can be executed as often with different parameter
values (see evaluate(Object[])
). This execution is very fast, compared to the compilation.
Less common methods exist that allow for the specification of the name of the generated class, the class it
extends, the interfaces it implements, the name of the method that executes the script, the exceptions that this
method (i.e. the script) is allowed to throw, and the ClassLoader
that is used to define the generated
class and to load classes referenced by the script.
If you want to compile many scripts at the same time, you have the option to cook an array of scripts in
one IScriptEvaluator
by using the following methods:
setMethodNames(String[])
setParameters(String[][], Class[][])
setReturnTypes(Class[])
setStaticMethod(boolean[])
setThrownExceptions(Class[][])
ICookable.cook(Reader)
evaluate(int, Object[])
Notice that these methods have array parameters in contrast to their one-script brethren.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The name of the generated method(s), if no custom method name is configured withsetMethodNames(String[])
.static final Class<?>
The return type for any script for which no return type is explicitly configured. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Same asICookable.cook(Reader)
, but for multiple scripts.void
Same asICookable.cook(String)
, but for multiple scripts.void
Same asICookable.cook(String, Reader)
, but cooks a set of scripts into one class.void
Same asICookable.cook(String, String)
, but for multiple scripts.<T> T
createFastEvaluator
(Reader reader, Class<T> interfaceToImplement, String[] parameterNames) If the parameter and return types of the expression are known at compile time, then a "fast" script evaluator can be instantiated through this method.<T> T
createFastEvaluator
(String script, Class<T> interfaceToImplement, String[] parameterNames) Same asevaluate(Object[])
, but for multiple scripts.Calls the script with concrete parameter values.Class<?>
getClazz()
String[]
Class<?>
getMethod
(int idx) Same asgetMethod()
, but for multiple scripts.Method[]
void
setClassName
(String className) void
setCompileErrorHandler
(ErrorHandler compileErrorHandler) Installs anErrorHandler
which is invoked during compilation on each error.void
setDebuggingInformation
(boolean debugSource, boolean debugLines, boolean debugVars) Determines what kind of debugging information is included in the generates classes.void
setDefaultImports
(String... defaultImports) void
setDefaultReturnType
(Class<?> defaultReturnType) When thisIScriptEvaluator
is coooked, then the defaultReturnType applies to all scripts for which no explicit return type was configured.void
setExtendedClass
(Class<?> extendedClass) void
setImplementedInterfaces
(Class<?>[] implementedInterfaces) void
setMethodName
(String methodName) Defines the name of the generated method.void
setMethodNames
(String[] methodNames) Same assetMethodName(String)
, but for multiple scripts.void
setOverrideMethod
(boolean overrideMethod) Defines whether the generated method overrides a methods declared in a supertype.void
setOverrideMethod
(boolean[] overrideMethod) Same assetOverrideMethod(boolean)
, but for multiple scripts.void
setParameters
(String[][] names, Class<?>[][] types) Same assetParameters(String[], Class[])
, but for multiple scripts.void
setParameters
(String[] names, Class<?>[] types) Defines the names and types of the parameters of the generated method.void
setParentClassLoader
(ClassLoader parentClassLoader) The "parent class loader" is used to load referenced classes.void
setReturnType
(Class<?> returnType) Defines the return type of the generated method.void
setReturnTypes
(Class<?>[] returnTypes) Configures the return types of the generated methods.void
setStaticMethod
(boolean staticMethod) Defines whether the generated method should be STATIC or not.void
setStaticMethod
(boolean[] staticMethod) Same assetStaticMethod(boolean)
, but for multiple scripts.void
setThrownExceptions
(Class<?>[] thrownExceptions) Defines the exceptions that the generated method may throw.void
setThrownExceptions
(Class<?>[][] thrownExceptions) Same assetThrownExceptions(Class[])
, but for multiple scripts.void
setWarningHandler
(WarningHandler warningHandler) By default, warnings are discarded, but an application my install a customWarningHandler
.
-
Field Details
-
DEFAULT_METHOD_NAME
The name of the generated method(s), if no custom method name is configured withsetMethodNames(String[])
.The
'*'
in this string is replaced with the method index, starting at 0.- See Also:
-
DEFAULT_RETURN_TYPE
The return type for any script for which no return type is explicitly configured.
-
-
Method Details
-
setParentClassLoader
The "parent class loader" is used to load referenced classes. Useful values are:System.getSystemClassLoader()
The running JVM's class path Thread.currentThread().getContextClassLoader()
ornull
The class loader effective for the invoking thread ClassLoaders.BOOTCLASSPATH_CLASS_LOADER
The running JVM's boot class path The parent class loader defaults to the current thread's context class loader.
-
setDebuggingInformation
void setDebuggingInformation(boolean debugSource, boolean debugLines, boolean debugVars) Determines what kind of debugging information is included in the generates classes. The default is typically "-g:none
". -
setCompileErrorHandler
Installs anErrorHandler
which is invoked during compilation on each error. (By default, the compilation throws aCompileException
on the first error and terminates.)If the given
ErrorHandler
throws aCompileException
, then the compilation terminates and the exception is propagated.If the given
ErrorHandler
does not throw aCompileException
but completes normally, then the compilation may or may not continue, depending on the error. Iff the compilation completes normally but errors were reported, then it will throw aCompileException
indicating the number of errors.In other words: The
ErrorHandler
may throw aCompileException
or not, but the compilation will definitely throw aCompileException
if one or more compile errors have occurred.- Parameters:
compileErrorHandler
-null
to restore the default behavior (throwing aCompileException
)
-
setWarningHandler
By default, warnings are discarded, but an application my install a customWarningHandler
.- Parameters:
warningHandler
-null
to indicate that no warnings be issued
-
setClassName
- See Also:
-
setImplementedInterfaces
-
setExtendedClass
-
setDefaultReturnType
When thisIScriptEvaluator
is coooked, then the defaultReturnType applies to all scripts for which no explicit return type was configured.The initial default return type (if you want, the "default-default" return type) is
void.class
.- See Also:
-
getDefaultReturnType
Class<?> getDefaultReturnType()- Returns:
- The default return type that was previously configured with
setDefaultReturnType(Class)
, orDEFAULT_RETURN_TYPE
-
setOverrideMethod
void setOverrideMethod(boolean overrideMethod) Defines whether the generated method overrides a methods declared in a supertype. -
setStaticMethod
void setStaticMethod(boolean staticMethod) Defines whether the generated method should be STATIC or not. Defaults totrue
. -
setReturnType
Defines the return type of the generated method. Valuenull
means "use the default return type".- See Also:
-
setMethodName
Defines the name of the generated method.null
means use a reasonable "eval*". -
setParameters
Defines the names and types of the parameters of the generated method.names
.length
and types.length
must be equal. This invariant may be checked immediately, or later when the script is cooked.The parameters can be of primitive type, e.g.
double.class
.The default is to have zero parameters.
-
setThrownExceptions
Defines the exceptions that the generated method may throw. -
evaluate
Calls the script with concrete parameter values.Each argument must have the same type as specified through the
parameterTypes
parameter ofsetParameters(String[], Class[])
.Arguments of primitive type must passed with their wrapper class objects.
The object returned has the class as specified through
setReturnType(Class)
.This method is thread-safe.
- Parameters:
arguments
- The actual parameter values- Throws:
IllegalStateException
- This IScriptEvaluator is not yet cookedInvocationTargetException
-
getMethod
Method getMethod()- Returns:
- The generated and loaded
Method
- Throws:
IllegalStateException
- This IScriptEvaluator is not yet cooked
-
setOverrideMethod
void setOverrideMethod(boolean[] overrideMethod) Same assetOverrideMethod(boolean)
, but for multiple scripts. -
setStaticMethod
void setStaticMethod(boolean[] staticMethod) Same assetStaticMethod(boolean)
, but for multiple scripts. -
setReturnTypes
Configures the return types of the generated methods. If an element of the array isnull
, then use the "default return type" for that script.- Parameters:
returnTypes
- The methods' return types;null
elements mean "use the default return type"- See Also:
-
setMethodNames
Same assetMethodName(String)
, but for multiple scripts.Define the names of the generated methods. By default the methods have distinct and implementation-specific names.
If two scripts have the same name, then they must have different parameter types (see
setParameters(String[][], Class[][])
). -
setParameters
Same assetParameters(String[], Class[])
, but for multiple scripts. -
setThrownExceptions
Same assetThrownExceptions(Class[])
, but for multiple scripts. -
cook
Same asICookable.cook(Reader)
, but for multiple scripts.- Specified by:
cook
in interfaceIMultiCookable
- Throws:
CompileException
IOException
-
cook
Same asICookable.cook(String, Reader)
, but cooks a set of scripts into one class. Notice that if any of the scripts causes trouble, the entire compilation will fail. If you need to report which of the scripts causes the exception, you may want to use thefileNames
parameter to distinguish between the individual token sources.Iff the number of scanners is one, then that single script may contain leading IMPORT directives.
s- Specified by:
cook
in interfaceIMultiCookable
- Throws:
IllegalStateException
- if any of the precedingset...()
had an array size different from that ofscanners
CompileException
IOException
-
cook
Same asICookable.cook(String)
, but for multiple scripts.- Specified by:
cook
in interfaceIMultiCookable
- Throws:
CompileException
-
cook
Same asICookable.cook(String, String)
, but for multiple scripts.- Specified by:
cook
in interfaceIMultiCookable
- Throws:
CompileException
-
evaluate
Same asevaluate(Object[])
, but for multiple scripts.- Throws:
InvocationTargetException
-
getMethod
Same asgetMethod()
, but for multiple scripts. -
createFastEvaluator
<T> T createFastEvaluator(String script, Class<T> interfaceToImplement, String[] parameterNames) throws CompileException - Parameters:
script
- Contains the sequence of script tokens- Throws:
CompileException
- See Also:
-
createFastEvaluator
<T> T createFastEvaluator(Reader reader, Class<T> interfaceToImplement, String[] parameterNames) throws CompileException, IOException If the parameter and return types of the expression are known at compile time, then a "fast" script evaluator can be instantiated through this method.Script evaluation is faster than through
evaluate(Object[])
, because it is not done through reflection but through direct method invocation.Example:
public interface Foo { int bar(int a, int b); } ... IScriptEvaluator se =
CompilerFactoryFactory
.getDefaultCompilerFactory
().newScriptEvaluator
(); // Optionally configure the SE her: se.setClassName
("Bar"); se.setDefaultImports
(new String[] { "java.util.*" }); se.setExtendedClass
(SomeOtherClass.class); se.setParentClassLoader
(someClassLoader); Foo f = (Foo) se.createFastScriptEvaluator
( "return a - b;", Foo.class, new String[] { "a", "b" } ); System.out.println("1 - 2 = " + f.bar(1, 2));All other configuration (implemented type, static method, return type, method name, parameter names and types, thrown exceptions) are predetermined by the
interfaceToImplement
.Notice: The
sinterfaceToImplement
must either be declaredpublic
, or with package scope in the same package as the generated class (seesetClassName(String)
).- Parameters:
reader
- Produces the stream of script tokensinterfaceToImplement
- Must declare exactly one methodparameterNames
- The names of the parameters of that method- Returns:
- An object that implements the given interface
- Throws:
CompileException
IOException
-
setDefaultImports
-
getDefaultImports
String[] getDefaultImports()- See Also:
-
getClazz
Class<?> getClazz()- See Also:
-
getResult
Method[] getResult()- Returns:
- The generated and loaded methods that implement the cooked scripts
- Throws:
IllegalStateException
- ThisIScriptEvaluator
is not yet cooked
-