Java Doc for ExpressionEvaluator.java in  » Scripting » jacl » org » codehaus » janino » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The syntax of the expression to compile is that of a Java^TM expression, as defined in the Java Language Specification, 2nd edition, section 15. Notice that a Java^TM expression does not have a concluding semicolon.

Example:

 a + 7 * b

The expression may optionally be preceeded with a sequence of import directives like

 import java.text.*;
 new DecimalFormat("####,###.##").format(10200020.345345)
 

The expression evaluator is implemented by creating and compiling a temporary compilation unit defining one class with one static method with one return statement.

To set up an ExpressionEvaluator object, proceed as follows:

1. Create the ExpressionEvaluator using ExpressionEvaluator.ExpressionEvaluator()
2. Configure the ExpressionEvaluator by calling any of the following methods:
   • ExpressionEvaluator.setExpressionType(Class)
   • org.codehaus.janino.ScriptEvaluator.setParameters(String[]Class[])
   • org.codehaus.janino.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 expression into the JVM.

After the ExpressionEvaluator object is set up, the expression can be evaluated as often with different parameter values (see ExpressionEvaluator.evaluate(Object[]) ). This evaluation is very fast, compared to the setup.

Notice that for functionally identical ExpressionEvaluator s, java.lang.Object.equals(java.lang.Object) will return true. E.g. "a+b" and "c + d" are functionally identical if "a" and "c" have the same type, and so do "b" and "d".

If the parameter and return types of the expression are known at compile time, then a "fast" expression evaluator can be instantiated through ExpressionEvaluator.createFastExpressionEvaluator(String,Class,String[],ClassLoader) . Expression evaluation is faster than through ExpressionEvaluator.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) ExpressionEvaluator.createFastExpressionEvaluator(
 "a + b",                    // expression to evaluate
 Foo.class,                  // interface that describes the expression's signature
 new String[] { "a", "b" },  // the parameters' names
 (ClassLoader) null          // Use current thread's context class loader
 );
 System.out.println("1 + 2 = " + f.bar(1, 2)); // Evaluate the expression
 

On my system (Intel P4, 2 GHz, MS Windows XP, JDK 1.4.1), expression "x + 1" evaluates as follows:

	Server JVM	Client JVM
Normal EE	23.7 ns	64.0 ns
Fast EE	31.2 ns	42.2 ns

(How can it be that interface method invocation is slower than reflection for the server JVM?)

The expression may refer to a set of parameters with the given parameterNames and parameterTypes.

parameterNames and parameterTypes must have the same number of elements.

The parameters and/or the return value can be of primitive type, e.g. Double.TYPE .

The optionalClassLoader 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 ByteArrayClassLoader , or by creation of a temporary ByteArrayClassLoader if not.

A number of constructors exist that provide useful default values for the various parameters, or parse their script from a String instead of a Scanner . (You hardly want to use a scanner other than the default scanner.)

If the type of the expression is not fixed, you can pass a null optionalExpressionType argument; in this case, references are returned as Object s, and primitive values are wrapped in their wrapper classes.

If optionalExpressionType is Void.TYPE , then the expression must be an invocation of a void method.

See the class description for an explanation of the "fast expression evaluator" concept.

Notice: The interfaceToImplement must either be declared public, or with package scope in the same package as className.
Parameters:
  scanner - Source of expression tokens
Parameters:
  optionalDefaultImports - Default imports, e.g.

 ExpressionEvaluator ee = new ExpressionEvaluator();
 ee.setExpressionType(expressionType);
 ee.setParameters(parameterNames, parameterTypes);
 ee.cook(expression);

 ExpressionEvaluator ee = new ExpressionEvaluator();
 ee.setExpressionType(expressionType);
 ee.setParameters(parameterNames, parameterTypes);
 ee.setThrownExceptions(thrownExceptions);
 ee.setParentClassLoader(optionalParentClassLoader);
 ee.cook(expression);

 ExpressionEvaluator ee = new ExpressionEvaluator();
 ee.setExpressionType(expressionType);
 ee.setParameters(parameterNames, parameterTypes);
 ee.setThrownExceptions(thrownExceptions);
 ee.setExtendedType(optionalExtendedType);
 ee.setImplementedTypes(implementedTypes);
 ee.setParentClassLoader(optionalParentClassLoader);
 ee.cook(expression);

 ExpressionEvaluator ee = new ExpressionEvaluator();
 ee.setClassName(className);
 ee.setExtendedType(optionalExtendedType);
 ee.setImplementedTypes(implementedTypes);
 ee.setStaticMethod(staticMethod);
 ee.setExpressionType(expressionType);
 ee.setMethodName(methodName);
 ee.setParameters(parameterNames, parameterTypes);
 ee.setThrownExceptions(thrownExceptions);
 ee.setParentClassLoader(optionalParentClassLoader);
 ee.cook(scanner);

See Also:   ExpressionEvaluator.ExpressionEvaluator()
See Also:   ClassBodyEvaluator.setClassName(String)
See Also:   ClassBodyEvaluator.setExtendedType(Class)
See Also:   ClassBodyEvaluator.setImplementedTypes(Class[])
See Also:   ScriptEvaluator.setStaticMethod(boolean)
See Also:   ExpressionEvaluator.setExpressionType(Class)
See Also:   ScriptEvaluator.setMethodName(String)
See Also:   ScriptEvaluator.setParameters(String[]Class[])
See Also:   ScriptEvaluator.setThrownExceptions(Class[])
See Also:   SimpleCompiler.setParentClassLoader(ClassLoader)
See Also:   Cookable.cook(Scanner)

See the class description for an explanation of the "fast expression evaluator" concept.
See Also:   ExpressionEvaluator.createFastExpressionEvaluator(Scanner,String[],String,Class,Class,String[],ClassLoader)
See Also:   ExpressionEvaluator

See the class description for an explanation of the "fast expression evaluator" concept.
See Also:   ExpressionEvaluator.createFastExpressionEvaluator(Scanner,String[],String,Class,Class,String[],ClassLoader)
See Also:   ExpressionEvaluator

See the class description for an explanation of the "fast expression evaluator" concept.

Notice: The interfaceToImplement must either be declared public, or with package scope in the same package as className.
Parameters:
  scanner - Source of expression tokens
Parameters:
  optionalDefaultImports - Default imports, e.g. { "java.util.Map", "java.io.*" }
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
See Also:   ExpressionEvaluator

Defaults to ExpressionEvaluator.ANY_TYPE .