Interface IScriptEvaluator
-
- All Superinterfaces:
IClassBodyEvaluator
,ICookable
- All Known Subinterfaces:
IExpressionEvaluator
- All Known Implementing Classes:
ExpressionEvaluator
,ExpressionEvaluator
,ScriptEvaluator
,ScriptEvaluator
public interface IScriptEvaluator extends IClassBodyEvaluator
An engine that executes a script in Java™ bytecode.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, 2nd edition, sections 7.5 and 14.
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.
IScriptEvaluator
object is created, the script can be executed as often with different parameter values (seeevaluate(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
Notice that these methods have array parameters in contrast to their one-script brethren.IScriptEvaluator
by using the following methods:
-
-
Field Summary
-
Fields inherited from interface org.codehaus.commons.compiler.IClassBodyEvaluator
DEFAULT_CLASS_NAME
-
Fields inherited from interface org.codehaus.commons.compiler.ICookable
BOOT_CLASS_LOADER, SYSTEM_PROPERTY_SOURCE_DEBUGGING_DIR, SYSTEM_PROPERTY_SOURCE_DEBUGGING_ENABLE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
cook(java.io.Reader[] readers)
Same asICookable.cook(Reader)
, but for multiple scripts.void
cook(java.lang.String[] strings)
Same asICookable.cook(String)
, but for multiple scripts.void
cook(java.lang.String[] optionalFileNames, java.io.Reader[] readers)
Same asICookable.cook(String, Reader)
, but cooks a set of scripts into one class.void
cook(java.lang.String[] optionalFileNames, java.lang.String[] strings)
Same asICookable.cook(String, String)
, but for multiple scripts.java.lang.Object
createFastEvaluator(java.io.Reader reader, java.lang.Class interfaceToImplement, java.lang.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.java.lang.Object
createFastEvaluator(java.lang.String script, java.lang.Class interfaceToImplement, java.lang.String[] parameterNames)
java.lang.Object
evaluate(int idx, java.lang.Object[] arguments)
Same asevaluate(Object[])
, but for multiple scripts.java.lang.Object
evaluate(java.lang.Object[] arguments)
Calls the script with concrete parameter values.java.lang.reflect.Method
getMethod()
Returns the loadedMethod
.java.lang.reflect.Method
getMethod(int idx)
Same asgetMethod()
, but for multiple scripts.void
setMethodName(java.lang.String methodName)
Define the name of the generated method.void
setMethodNames(java.lang.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(java.lang.String[][] names, java.lang.Class[][] types)
Same assetParameters(String[], Class[])
, but for multiple scripts.void
setParameters(java.lang.String[] names, java.lang.Class[] types)
Define the names and types of the parameters of the generated method.void
setReturnType(java.lang.Class returnType)
Defines the return type of the generated method.void
setReturnTypes(java.lang.Class[] returnTypes)
Defines the return types of the generated methods.void
setStaticMethod(boolean staticMethod)
Define whether the generated method should be STATIC or not.void
setStaticMethod(boolean[] staticMethod)
Same assetStaticMethod(boolean)
, but for multiple scripts.void
setThrownExceptions(java.lang.Class[] thrownExceptions)
Define the exceptions that the generated method may throw.void
setThrownExceptions(java.lang.Class[][] thrownExceptions)
Same assetThrownExceptions(Class[])
, but for multiple scripts.-
Methods inherited from interface org.codehaus.commons.compiler.IClassBodyEvaluator
createInstance, getClazz, setClassName, setDefaultImports, setExtendedClass, setExtendedType, setImplementedInterfaces, setImplementedTypes
-
-
-
-
Method Detail
-
setOverrideMethod
void setOverrideMethod(boolean overrideMethod)
Defines whether the generated method overrides a methods declared in a supertype.
-
setStaticMethod
void setStaticMethod(boolean staticMethod)
Define whether the generated method should be STATIC or not. Defaults totrue
.
-
setReturnType
void setReturnType(java.lang.Class returnType)
Defines the return type of the generated method. The meaning of anull
value is implementation-dependent.
-
setMethodName
void setMethodName(java.lang.String methodName)
Define the name of the generated method. Defaults to an unspecified name.
-
setParameters
void setParameters(java.lang.String[] names, java.lang.Class[] types)
Define the names and types of the parameters of the generated method.names
andtypes
must have the same number of elements.The parameters can be of primitive type, e.g.
double.class
.
-
setThrownExceptions
void setThrownExceptions(java.lang.Class[] thrownExceptions)
Define the exceptions that the generated method may throw.
-
evaluate
java.lang.Object evaluate(java.lang.Object[] arguments) throws java.lang.reflect.InvocationTargetException
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:
java.lang.reflect.InvocationTargetException
-
getMethod
java.lang.reflect.Method getMethod()
Returns the loadedMethod
.This method must only be called after exactly one of the
ICookable.cook(String, Reader)
methods was called.
-
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
void setReturnTypes(java.lang.Class[] returnTypes)
Defines the return types of the generated methods. The meaning ofnull
values is implementation-dependent.
-
setMethodNames
void setMethodNames(java.lang.String[] methodNames)
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
void setParameters(java.lang.String[][] names, java.lang.Class[][] types)
Same assetParameters(String[], Class[])
, but for multiple scripts.
-
setThrownExceptions
void setThrownExceptions(java.lang.Class[][] thrownExceptions)
Same assetThrownExceptions(Class[])
, but for multiple scripts.
-
cook
void cook(java.io.Reader[] readers) throws CompileException, java.io.IOException
Same asICookable.cook(Reader)
, but for multiple scripts.- Throws:
CompileException
java.io.IOException
-
cook
void cook(java.lang.String[] optionalFileNames, java.io.Reader[] readers) throws CompileException, java.io.IOException
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 theoptionalFileNames
parameter to distinguish between the individual token sources.If and only if the number of scanners is one, then that single script may contain leading IMPORT directives.
- Throws:
java.lang.IllegalStateException
- if any of the precedingset...()
had an array size different from that ofscanners
CompileException
java.io.IOException
-
cook
void cook(java.lang.String[] strings) throws CompileException
Same asICookable.cook(String)
, but for multiple scripts.- Throws:
CompileException
-
cook
void cook(java.lang.String[] optionalFileNames, java.lang.String[] strings) throws CompileException
Same asICookable.cook(String, String)
, but for multiple scripts.- Throws:
CompileException
-
evaluate
java.lang.Object evaluate(int idx, java.lang.Object[] arguments) throws java.lang.reflect.InvocationTargetException
Same asevaluate(Object[])
, but for multiple scripts.- Throws:
java.lang.reflect.InvocationTargetException
-
getMethod
java.lang.reflect.Method getMethod(int idx)
Same asgetMethod()
, but for multiple scripts.
-
createFastEvaluator
java.lang.Object createFastEvaluator(java.lang.String script, java.lang.Class interfaceToImplement, java.lang.String[] parameterNames) throws CompileException
- Parameters:
script
- Contains the sequence of script tokens- Throws:
CompileException
- See Also:
createFastEvaluator(Reader, Class, String[])
-
createFastEvaluator
java.lang.Object createFastEvaluator(java.io.Reader reader, java.lang.Class interfaceToImplement, java.lang.String[] parameterNames) throws CompileException, java.io.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 =
All other configuration (implemented type, static method, return type, method name, parameter names and types, thrown exceptions) are predetermined by theCompilerFactoryFactory
.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));interfaceToImplement
. Notice: TheinterfaceToImplement
must either be declaredpublic
, or with package scope in the same package as the generated class (seeIClassBodyEvaluator.setClassName(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
java.io.IOException
-
-