net.janino
Class ScriptEvaluator

java.lang.Object
  |
  +--net.janino.EvaluatorBase
        |
        +--net.janino.ScriptEvaluator

public class ScriptEvaluator

extends EvaluatorBase

A script evaluator that executes a script in Java^TM bytecode.

The syntax of the script to compile is a sequence of import declarations followed by a sequence of statements, as defined in the , sections and .

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 is compiled when the ScriptEvaluator object is instantiated. The script, its return type, and its parameter names and types are specified at compile time.

The script evaluator is implemented by creating and compiling a temporary compilation unit defining one class with one static method the body of which consists of the statements of the script.

After the ScriptEvaluator 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.

The more elaborate constructors of ScriptEvaluator also 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 is allowed to throw, and the java.lang.ClassLoader that is used to define the generated class and to load classes referenced by the expression. This degree of flexibility is usually not required; the most commonly used constructor is ScriptEvaluator(String, Class, String[], Class[]).

Constructor Summary

ScriptEvaluator(Scanner scanner, java.lang.Class extendedType, java.lang.Class[] implementedTypes, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions, java.lang.ClassLoader classLoader)
Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.

ScriptEvaluator(Scanner scanner, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions, java.lang.ClassLoader classLoader)
Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.

ScriptEvaluator(Scanner scanner, java.lang.String className, java.lang.Class extendedType, java.lang.Class[] implementedTypes, java.lang.Class returnType, java.lang.String methodName, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions, java.lang.ClassLoader classLoader)
Parse a script from a String that returns a value with the given type and compile it.

ScriptEvaluator(java.lang.String script)
Parse a script from a String and compile it.

ScriptEvaluator(java.lang.String script, java.lang.Class returnType)
Parse a script from a String and compile it.

ScriptEvaluator(java.lang.String script, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes)
Parse a script from a String and compile it.

ScriptEvaluator(java.lang.String script, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions)
Parse a script from a String and compile it.

ScriptEvaluator(java.lang.String fileName, java.io.InputStream is, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions, java.lang.ClassLoader classLoader)
Parse a script from an InputStream and compile it.

ScriptEvaluator(java.lang.String fileName, java.io.Reader reader, java.lang.Class returnType, java.lang.String[] parameterNames, java.lang.Class[] parameterTypes, java.lang.Class[] thrownExceptions, java.lang.ClassLoader classLoader)
Parse a script from a Reader and compile it.

Method Summary

java.lang.Object	evaluate(java.lang.Object[] parameterValues) Evaluates a script with concrete parameter values.
java.lang.reflect.Method	getMethod() If, for any reason, somebody needs the java.lang.reflect.Method object...

Methods inherited from class net.janino.EvaluatorBase

addClassDeclaration, addClassMethodBlockDeclaration, classesToTypes, classToType, compileAndLoad, compileAndLoad, makeFormalParameters, parseImportDeclarations

Methods inherited from class java.lang.Object

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

Constructor Detail

ScriptEvaluator

public ScriptEvaluator(java.lang.String script)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a String and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(java.lang.String script,
                       java.lang.Class returnType)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a String and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(java.lang.String script,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a String and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(java.lang.String script,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a String and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(java.lang.String fileName,
                       java.io.InputStream is,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions,
                       java.lang.ClassLoader classLoader)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from an InputStream and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(java.lang.String fileName,
                       java.io.Reader reader,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions,
                       java.lang.ClassLoader classLoader)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a Reader and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions,
                       java.lang.ClassLoader classLoader)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       java.lang.Class extendedType,
                       java.lang.Class[] implementedTypes,
                       java.lang.Class returnType,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions,
                       java.lang.ClassLoader classLoader)
                throws Java.CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       java.io.IOException

Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.

See Also:

ScriptEvaluator(Scanner, String, Class, Class[], Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       java.lang.String className,
                       java.lang.Class extendedType,
                       java.lang.Class[] implementedTypes,
                       java.lang.Class returnType,
                       java.lang.String methodName,
                       java.lang.String[] parameterNames,
                       java.lang.Class[] parameterTypes,
                       java.lang.Class[] thrownExceptions,
                       java.lang.ClassLoader classLoader)
                throws Scanner.ScanException,
                       Parser.ParseException,
                       Java.CompileException,
                       java.io.IOException

Parse a script from a String that returns a value with the given type and compile it. Parameters with the given names and types are accessible in the script.

The script is allowed to throw any of the specified exceptions.

Parameters:

scanner - Source of tokens to parse

className - Name of the temporary class (uncritical)

extendedType - Superclass of the temporary class or null

implementedTypes - The interfaces that the the generated object implements (all methods must be implemented by the extendedType)

returnType - The return type of the temporary method that implements the script, e.g. Double.TYPE or Void.TYPE

methodName - The name of the temporary method (uncritical)

parameterNames - The names of the script parameters, e.g. "i" and "j".

parameterTypes - The types of the script parameters, e.g. Integer.TYPE or Double.TYPE.

thrownExceptions - The exceptions that the script is allowed to throw, e.g. java.io.IOException.class.

classLoader - Loads referenced classes and defines the generated class

See Also:

Construct a script evaluator that processes the given script with the given return type, parameter names and types. A script is a sequence of valid Java^TM statements.

If the return type of the script is Void.TYPE, then all RETURN statements must have no value, and the script need not be concluded by a RETURN statement.

parameterNames and parameterTypes must have the same length.

The classLoader serves two purposes:

• It is used to look for classes referenced by the script.
• It is used to load the generated Java^TM class into the JVM; directly if it is a subclass of {@link ByteArrayClassLoader}, or by creation of a temporary {@link ByteArrayClassLoader} if not.

A null classLoader means to use the current thread's context class loader.

A number of constructors exist that provide useful default values for the various parameters, or parse their script from a String, an InputStream or a Reader instead of a {@link Scanner}.

Method Detail

evaluate

public java.lang.Object evaluate(java.lang.Object[] parameterValues)
                          throws java.lang.reflect.InvocationTargetException

Evaluates a script with concrete parameter values.

Each parameter value must have the same type as specified through the "parameterTypes" parameter of ScriptEvaluator(String, Class, String[], Class[]).

Parameters of primitive type must passed with their wrapper class objects.

The object returned has the class specified through the "returnType" parameter of ScriptEvaluator(String, Class, String[], Class[]).

Parameters:

parameterValues - The concrete parameter values.

getMethod

public java.lang.reflect.Method getMethod()

If, for any reason, somebody needs the java.lang.reflect.Method object...