Web Site

org.codehaus.janino
Class ScriptEvaluator

java.lang.Object
  extended byorg.codehaus.janino.EvaluatorBase
      extended byorg.codehaus.janino.ScriptEvaluator

public class ScriptEvaluator
extends EvaluatorBase

A script evaluator that executes a script in JavaTM bytecode.

The syntax of the script to compile is a sequence of import declarations 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 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 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 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, Class optionalExtendedType, Class[] implementedTypes, Class returnType, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions, ClassLoader optionalParentClassLoader)
          Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.
ScriptEvaluator(Scanner scanner, Class returnType, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions, ClassLoader optionalParentClassLoader)
          Parse a script from a sequence of Scanner.Tokens delivered by the given Scanner object and compile it.
ScriptEvaluator(Scanner scanner, String className, Class optionalExtendedType, Class[] implementedTypes, boolean staticMethod, Class returnType, String methodName, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions, ClassLoader optionalParentClassLoader)
          Construct a script evaluator that processes the given script with the given return type, parameter names and types.
ScriptEvaluator(String script)
          Parse a script from a String and compile it.
ScriptEvaluator(String script, Class returnType)
          Parse a script from a String and compile it.
ScriptEvaluator(String script, Class returnType, String[] parameterNames, Class[] parameterTypes)
          Parse a script from a String and compile it.
ScriptEvaluator(String script, Class returnType, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions)
          Parse a script from a String and compile it.
ScriptEvaluator(String optionalFileName, InputStream is, Class returnType, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions, ClassLoader optionalParentClassLoader)
          Parse a script from an InputStream and compile it.
ScriptEvaluator(String optionalFileName, Reader reader, Class returnType, String[] parameterNames, Class[] parameterTypes, Class[] thrownExceptions, ClassLoader optionalParentClassLoader)
          Parse a script from a Reader and compile it.
 
Method Summary
static Object createFastScriptEvaluator(Scanner scanner, Class interfaceToImplement, String[] parameterNames, ClassLoader optionalParentClassLoader)
          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.
static Object createFastScriptEvaluator(Scanner scanner, String className, Class optionalExtendedType, Class interfaceToImplement, String[] parameterNames, ClassLoader optionalParentClassLoader)
          Like createFastScriptEvaluator(Scanner, Class, String[], ClassLoader), but gives you more control over the generated class (rarely needed in practice).
 Object evaluate(Object[] parameterValues)
          Evaluates a script with concrete parameter values.
 Method getMethod()
          If, for any reason, somebody needs the Method object...
 
Methods inherited from class org.codehaus.janino.EvaluatorBase
addClassMethodBlockDeclaration, addPackageMemberClassDeclaration, 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(String script)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException
Parse a script from a String and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(String script,
                       Class returnType)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException
Parse a script from a String and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(String script,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException
Parse a script from a String and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(String script,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException
Parse a script from a String and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(String optionalFileName,
                       InputStream is,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions,
                       ClassLoader optionalParentClassLoader)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       IOException
Parse a script from an InputStream and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(String optionalFileName,
                       Reader reader,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions,
                       ClassLoader optionalParentClassLoader)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       IOException
Parse a script from a Reader and compile it.

See Also:
ScriptEvaluator(Scanner, String, Class, Class[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions,
                       ClassLoader optionalParentClassLoader)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       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[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       Class optionalExtendedType,
                       Class[] implementedTypes,
                       Class returnType,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions,
                       ClassLoader optionalParentClassLoader)
                throws CompileException,
                       Parser.ParseException,
                       Scanner.ScanException,
                       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[], boolean, Class, String, String[], Class[], Class[], ClassLoader)

ScriptEvaluator

public ScriptEvaluator(Scanner scanner,
                       String className,
                       Class optionalExtendedType,
                       Class[] implementedTypes,
                       boolean staticMethod,
                       Class returnType,
                       String methodName,
                       String[] parameterNames,
                       Class[] parameterTypes,
                       Class[] thrownExceptions,
                       ClassLoader optionalParentClassLoader)
                throws Scanner.ScanException,
                       Parser.ParseException,
                       CompileException,
                       IOException
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 JavaTM 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 optionalParentClassLoader serves two purposes:

A null optionalParentClassLoader 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 Scanner.

Parameters:
scanner - Source of tokens to parse
className - Name of the temporary class (uncritical)
optionalExtendedType - Superclass of the temporary class or null
implementedTypes - The interfaces that the the generated object implements (all methods must be implemented by the optionalExtendedType)
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. IOException.class.
optionalParentClassLoader - Loads referenced classes
Method Detail

createFastScriptEvaluator

public static Object createFastScriptEvaluator(Scanner scanner,
                                               Class interfaceToImplement,
                                               String[] parameterNames,
                                               ClassLoader optionalParentClassLoader)
                                        throws CompileException,
                                               Parser.ParseException,
                                               Scanner.ScanException,
                                               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);
 }
 ...
 Foo f = (Foo) ScriptEvaluator.createFastScriptEvaluator(
     new Scanner(null, new StringReader("return a + b;")),
     Foo.class,
     new String[] { "a", "b" },
     (ClassLoader) null          // Use current thread's context class loader
 );
 System.out.println("1 + 2 = " + f.bar(1, 2));
 
Notice: The interfaceToImplement must either be declared public, or with package scope in the root package (i.e. "no" package).

Parameters:
scanner - Source of script tokens
interfaceToImplement - Must declare exactly one method
parameterNames -
optionalParentClassLoader -
Returns:
an object that implements the given interface
Throws:
CompileException
Parser.ParseException
Scanner.ScanException
IOException

createFastScriptEvaluator

public static Object createFastScriptEvaluator(Scanner scanner,
                                               String className,
                                               Class optionalExtendedType,
                                               Class interfaceToImplement,
                                               String[] parameterNames,
                                               ClassLoader optionalParentClassLoader)
                                        throws CompileException,
                                               Parser.ParseException,
                                               Scanner.ScanException,
                                               IOException
Like createFastScriptEvaluator(Scanner, Class, String[], ClassLoader), but gives you more control over the generated class (rarely needed in practice).

Notice: The interfaceToImplement must either be declared public, or with package scope in the same package as className.

Parameters:
scanner - Source of script tokens
className - Name of generated class
optionalExtendedType - Class to extend
interfaceToImplement - Must declare exactly the one method that defines the expression's signature
parameterNames - The expression references the parameters through these names
optionalParentClassLoader - Loads referenced classes
Returns:
an object that implements the given interface and extends the optionalExtendedType
Throws:
CompileException
Parser.ParseException
Scanner.ScanException
IOException

evaluate

public Object evaluate(Object[] parameterValues)
                throws 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.
Throws:
InvocationTargetException

getMethod

public Method getMethod()
If, for any reason, somebody needs the Method object...


Web Site