Java Doc for ScriptEvaluator.java in  » Scripting » janino-2.5.11 » org » codehaus » janino » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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));
 

The script may complete abnormally, e.g. through a RETURN statement:

 if (a == null) {
 System.out.println("Oops!");
 return;
 }
 

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 ScriptEvaluator object, proceed as follows:

1. Create the ScriptEvaluator using ScriptEvaluator.ScriptEvaluator()
2. Configure the ScriptEvaluator by calling any of the following methods:
   • ScriptEvaluator.setReturnType(Class)
   • ScriptEvaluator.setParameters(String[],Class[])
   • ScriptEvaluator.setThrownExceptions(Class[])
   • org.codehaus.janino.SimpleCompiler.setParentClassLoader(ClassLoader)
   • org.codehaus.janino.ClassBodyEvaluator.setDefaultImports(String[])
3. Call any of the org.codehaus.janino.Cookable.cook(Scanner) methods to scan, parse, compile and load the script into the JVM.

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.

Alternatively, a number of "convenience constructors" exist that execute the steps described above instantly. Their use is discouraged.

If you want to compile many scripts at the same time, you have the option to cook an array of scripts in one ScriptEvaluator by using the following methods:

• ScriptEvaluator.setMethodNames(String[])
• ScriptEvaluator.setParameters(String[][],Class[][])
• ScriptEvaluator.setReturnTypes(Class[])
• ScriptEvaluator.setStaticMethod(boolean[])
• ScriptEvaluator.setThrownExceptions(Class[][])
• ScriptEvaluator.cook(Scanner[])
• ScriptEvaluator.evaluate(int,Object[])

Script evaluation is faster than through ScriptEvaluator.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));
 

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

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

The object returned has the class as specified through ScriptEvaluator.setReturnType(Class) .

This method is thread-safe.
Parameters:
  idx - The index of the script (0 ...

This method must only be called after ScriptEvaluator.cook(Scanner) .

This method must not be called for instances of derived classes.
Parameters:
  idx - The index of the script (0 ...

 ScriptEvaluator se = new ScriptEvaluator();
 se.cook(script);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.cook(script);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.cook(script);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.cook(script);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.setParentClassLoader(optionalParentClassLoader);
 se.cook(optionalFileName, is);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.setParentClassLoader(optionalParentClassLoader);
 se.cook(reader);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.setParentClassLoader(optionalParentClassLoader);
 se.cook(scanner);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setExtendedType(optionalExtendedType);
 se.setImplementedTypes(implementedTypes);
 se.setReturnType(returnType);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.setParentClassLoader(optionalParentClassLoader);
 se.cook(scanner);

 ScriptEvaluator se = new ScriptEvaluator();
 se.setClassName(className);
 se.setExtendedType(optionalExtendedType);
 se.setImplementedTypes(implementedTypes);
 se.setStaticMethod(staticMethod);
 se.setReturnType(returnType);
 se.setMethodName(methodName);
 se.setParameters(parameterNames, parameterTypes);
 se.setThrownExceptions(thrownExceptions);
 se.setParentClassLoader(optionalParentClassLoader);
 se.cook(scanner);

On a 2 GHz Intel Pentium Core Duo under Windows XP with an IBM 1.4.2 JDK, compiling 10000 expressions "a + b" (integer) takes about 4 seconds and 56 MB of main memory. The generated class file is 639203 bytes large.

The number and the complexity of the scripts is restricted by the Limitations of the Java Virtual Machine, where the most limiting factor is the 64K entries limit of the constant pool. Since every method with a distinct name requires one entry there, you can define at best 32K (very simple) scripts. If and only if the number of scanners is one, then that single script may contain leading IMPORT directives.
throws:
  IllegalStateException - if any of the preceeding set...() had an array size different from that of scanners

Script evaluation is faster than through ScriptEvaluator.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 same package as className.
Parameters:
  scanner - Source of script tokens
Parameters:
  className - Name of generated class
Parameters:
  optionalExtendedType - Class to extend
Parameters:
  interfaceToImplement - Must declare exactly the one method that defines the expression's signature
Parameters:
  parameterNames - The expression references the parameters through these names
Parameters:
  optionalParentClassLoader - Used to load referenced classes, defaults to the current thread's "context class loader" an object that implements the given interface and extends the optionalExtendedType

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

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

The object returned has the class as specified through ScriptEvaluator.setReturnType(Class) .

This method is thread-safe.
Parameters:
  parameterValues - The concrete parameter values.

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

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

The object returned has the class as specified through ScriptEvaluator.setReturnType(Class) .

This method is thread-safe.
Parameters:
  idx - The index of the script (0 ... scripts.length - 1)
Parameters:
  parameterValues - The concrete parameter values.

This method must only be called after ScriptEvaluator.cook(Scanner) .

This method must not be called for instances of derived classes.

This method must only be called after ScriptEvaluator.cook(Scanner) .

This method must not be called for instances of derived classes.
Parameters:
  idx - The index of the script (0 ... scripts.length - 1)

• A public method declaration with the given return type, name, parameter names and values and thrown exceptions
• A block

If two scripts have the same name, then they must have different parameter types (see ScriptEvaluator.setParameters(String[][],Class[][]) ).