org.codehaus.commons.compiler
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 , 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:

1. Create an IScriptEvaluator-implementing class.
2. Configure the IScriptEvaluator by calling any of the following methods:
   • setReturnType(Class)
   • setParameters(String[], Class[])
   • setThrownExceptions(Class[])
   • SimpleCompiler.setParentClassLoader(ClassLoader)
   • ClassBodyEvaluator.setDefaultImports(String[])
3. 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 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

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

void	cook([] readers) Same as ICookable.cook(Reader), but for multiple scripts.
void	cook([] strings) Same as ICookable.cook(String), but for multiple scripts.
void	cook([] optionalFileNames, [] readers) Same as ICookable.cook(String, Reader), but cooks a set of scripts into one class.
void	cook([] optionalFileNames, [] strings) Same as ICookable.cook(String, String), but for multiple scripts.
<T>	createFastEvaluator( reader, <T> interfaceToImplement, [] 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>	createFastEvaluator( script, <T> interfaceToImplement, [] parameterNames)
	evaluate(int idx, [] arguments) Same as evaluate(Object[]), but for multiple scripts.
	evaluate([] arguments) Calls the script with concrete parameter values.
	getMethod() Returns the loaded .
	getMethod(int idx) Same as getMethod(), but for multiple scripts.
void	setMethodName( methodName) Define the name of the generated method.
void	setMethodNames([] 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([][] names, [][] types) Same as setParameters(String[], Class[]), but for multiple scripts.
void	setParameters([] names, [] types) Define the names and types of the parameters of the generated method.
void	setReturnType( returnType) Defines the return type of the generated method.
void	setReturnTypes([] returnTypes) Defines 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([] thrownExceptions) Define the exceptions that the generated method may throw.
void	setThrownExceptions([][] thrownExceptions) Same as setThrownExceptions(Class[]), but for multiple scripts.

Methods inherited from interface org.codehaus.commons.compiler.IClassBodyEvaluator

createInstance, getClazz, setClassName, setDefaultImports, setExtendedClass, setExtendedType, setImplementedInterfaces, setImplementedTypes

Methods inherited from interface org.codehaus.commons.compiler.ICookable

cook, cook, cook, cook, cook, cook, cook, cook, cookFile, cookFile, cookFile, cookFile, setCompileErrorHandler, setDebuggingInformation, setParentClassLoader, setWarningHandler

Method Detail

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 to true.

setReturnType

void setReturnType( returnType)

Defines the return type of the generated method. The meaning of a null value is implementation-dependent.

setMethodName

void setMethodName( methodName)

Define the name of the generated method. Defaults to an unspecified name.

setParameters

void setParameters([] names,
                   [] types)

Define the names and types of the parameters of the generated method.

names and types must have the same number of elements.

The parameters can be of primitive type, e.g. double.class.

The default is to have zero parameters.

setThrownExceptions

void setThrownExceptions([] thrownExceptions)

Define the exceptions that the generated method may throw.

evaluate

 evaluate([] arguments)
                throws 

Calls the script with concrete parameter values.

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.

Parameters:

arguments - The actual parameter values

Throws:

getMethod

 getMethod()

Returns the loaded .

This method must only be called after exactly one of the ICookable.cook(String, Reader) methods was called.

setOverrideMethod

void setOverrideMethod(boolean[] overrideMethod)

Same as setOverrideMethod(boolean), but for multiple scripts.

setStaticMethod

void setStaticMethod(boolean[] staticMethod)

Same as setStaticMethod(boolean), but for multiple scripts.

setReturnTypes

void setReturnTypes([] returnTypes)

Defines the return types of the generated methods. The meaning of null elements is implementation-dependent.

setMethodNames

void setMethodNames([] methodNames)

Same as 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[][])).

setParameters

void setParameters([][] names,
                   [][] types)

Same as setParameters(String[], Class[]), but for multiple scripts.

setThrownExceptions

void setThrownExceptions([][] thrownExceptions)

Same as setThrownExceptions(Class[]), but for multiple scripts.

cook

void cook([] readers)
          throws CompileException,
                 

Same as ICookable.cook(Reader), but for multiple scripts.

Throws:

CompileException

cook

void cook([] optionalFileNames,
          [] readers)
          throws CompileException,
                 

Same as 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.

If and only if the number of scanners is one, then that single script may contain leading IMPORT directives.

Throws:

- if any of the preceding set...() had an array size different from that of scanners

CompileException

cook

void cook([] strings)
          throws CompileException

Same as ICookable.cook(String), but for multiple scripts.

Throws:

CompileException

cook

void cook([] optionalFileNames,
          [] strings)
          throws CompileException

Same as ICookable.cook(String, String), but for multiple scripts.

Throws:

CompileException

evaluate

 evaluate(int idx,
                [] arguments)
                throws 

Same as evaluate(Object[]), but for multiple scripts.

Throws:

getMethod

 getMethod(int idx)

Same as getMethod(), but for multiple scripts.

createFastEvaluator

<T>  createFastEvaluator( script,
                               <T> interfaceToImplement,
                               [] parameterNames)
                           throws CompileException

Parameters:

script - Contains the sequence of script tokens

Throws:

CompileException

See Also:

createFastEvaluator(Reader, Class, String[])

createFastEvaluator

<T>  createFastEvaluator( reader,
                               <T> interfaceToImplement,
                               [] parameterNames)
                           throws CompileException,
                                  

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 interfaceToImplement must either be declared public, or with package scope in the same package as the generated class (see IClassBodyEvaluator.setClassName(String)).

Parameters:

reader - Produces the stream of script tokens

interfaceToImplement - Must declare exactly one method

parameterNames - The names of the parameters of that method

Returns:

An object that implements the given interface

Throws:

CompileException