public interface IScriptEvaluator extends IClassBodyEvaluator
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:
IScriptEvaluator
-implementing class.IScriptEvaluator
by calling any of the following methods:
setReturnType(Class)
setParameters(String[], Class[])
setThrownExceptions(Class[])
org.codehaus.janino.SimpleCompiler#setParentClassLoader(ClassLoader)
org.codehaus.janino.ClassBodyEvaluator#setDefaultImports(String[])
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.
DEFAULT_CLASS_NAME
BOOT_CLASS_LOADER, SYSTEM_PROPERTY_SOURCE_DEBUGGING_DIR, SYSTEM_PROPERTY_SOURCE_DEBUGGING_ENABLE
Modifier and Type | Method and Description |
---|---|
void |
cook(Reader[] readers)
Same as
ICookable.cook(Reader) , but for multiple scripts. |
void |
cook(String[] strings)
Same as
ICookable.cook(String) , but for multiple scripts. |
void |
cook(String[] optionalFileNames,
Reader[] readers)
Same as
ICookable.cook(String, Reader) , but cooks a set of scripts into one class. |
void |
cook(String[] optionalFileNames,
String[] strings)
Same as
ICookable.cook(String, String) , but for multiple scripts. |
<T> Object |
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> Object |
createFastEvaluator(String script,
Class<T> interfaceToImplement,
String[] parameterNames) |
Object |
evaluate(int idx,
Object[] arguments)
Same as
evaluate(Object[]) , but for multiple scripts. |
Object |
evaluate(Object[] arguments)
Calls the script with concrete parameter values.
|
Method |
getMethod()
Returns the loaded
Method . |
Method |
getMethod(int idx)
Same as
getMethod() , but for multiple scripts. |
void |
setMethodName(String methodName)
Defines the name of the generated method.
|
void |
setMethodNames(String[] methodNames)
Same as
setMethodName(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 as
setOverrideMethod(boolean) , but for multiple scripts. |
void |
setParameters(String[][] names,
Class<?>[][] types)
Same as
setParameters(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 |
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 as
setStaticMethod(boolean) , but for multiple scripts. |
void |
setThrownExceptions(Class<?>[] thrownExceptions)
Defines the exceptions that the generated method may throw.
|
void |
setThrownExceptions(Class<?>[][] thrownExceptions)
Same as
setThrownExceptions(Class[]) , but for multiple scripts. |
createInstance, getClazz, setClassName, setDefaultImports, setExtendedClass, setExtendedType, setImplementedInterfaces, setImplementedTypes
cook, cook, cook, cook, cook, cook, cook, cook, cookFile, cookFile, cookFile, cookFile, setCompileErrorHandler, setDebuggingInformation, setParentClassLoader, setWarningHandler
void setOverrideMethod(boolean overrideMethod)
void setStaticMethod(boolean staticMethod)
true
.void setReturnType(Class<?> returnType)
null
is equivalent with void.class
.void setMethodName(String methodName)
void setParameters(String[] names, Class<?>[] types)
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.
void setThrownExceptions(Class<?>[] thrownExceptions)
@Nullable Object evaluate(@Nullable Object[] arguments) throws InvocationTargetException
Each argument must have the same type as specified through the parameterTypes
parameter of setParameters(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.
arguments
- The actual parameter valuesInvocationTargetException
Method getMethod()
Method
.
This method must only be called after one of the ICookable.cook(String, Reader)
methods was called.
void setOverrideMethod(boolean[] overrideMethod)
setOverrideMethod(boolean)
, but for multiple scripts.void setStaticMethod(boolean[] staticMethod)
setStaticMethod(boolean)
, but for multiple scripts.void setReturnTypes(Class<?>[] returnTypes)
null
.
Unless this method is invoked, the return type of all script is void.class
.
void setMethodNames(String[] methodNames)
setMethodName(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[][])
).
void setParameters(String[][] names, Class<?>[][] types)
setParameters(String[], Class[])
, but for multiple scripts.void setThrownExceptions(Class<?>[][] thrownExceptions)
setThrownExceptions(Class[])
, but for multiple scripts.void cook(Reader[] readers) throws CompileException, IOException
ICookable.cook(Reader)
, but for multiple scripts.CompileException
IOException
void cook(@Nullable String[] optionalFileNames, Reader[] readers) throws CompileException, IOException
ICookable.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 the
optionalFileNames
parameter to distinguish between the individual token sources.
Iff the number of scanners is one, then that single script may contain leading IMPORT directives.
sIllegalStateException
- if any of the preceding set...()
had an array
size different from that of scanners
CompileException
IOException
void cook(String[] strings) throws CompileException
ICookable.cook(String)
, but for multiple scripts.CompileException
void cook(@Nullable String[] optionalFileNames, String[] strings) throws CompileException
ICookable.cook(String, String)
, but for multiple scripts.CompileException
@Nullable Object evaluate(int idx, @Nullable Object[] arguments) throws InvocationTargetException
evaluate(Object[])
, but for multiple scripts.InvocationTargetException
Method getMethod(int idx)
getMethod()
, but for multiple scripts.<T> Object createFastEvaluator(String script, Class<T> interfaceToImplement, String[] parameterNames) throws CompileException
script
- Contains the sequence of script tokensCompileException
createFastEvaluator(Reader, Class, String[])
<T> Object createFastEvaluator(Reader reader, Class<T> interfaceToImplement, String[] parameterNames) throws CompileException, IOException
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 interfaceToImplement
must either be declared public
, or with package scope in the
same package as the generated class (see IClassBodyEvaluator.setClassName(String)
).
reader
- Produces the stream of script tokensinterfaceToImplement
- Must declare exactly one methodparameterNames
- The names of the parameters of that methodCompileException
IOException
Copyright © 2016. All rights reserved.