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 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 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:
  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 ClassLoader 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:

Notice that these methods have array parameters in contrast to their one-script brethren.
  • Method Details

    • setOverrideMethod

      void setOverrideMethod(boolean overrideMethod)
      Defines whether the generated method overrides a methods declared in a supertype.
    • setStaticMethod

      void setStaticMethod(boolean staticMethod)
      Define whether the generated method should be STATIC or not. Defaults to true.
    • setReturnType

      void setReturnType(Class returnType)
      Defines the return type of the generated method. The meaning of a null value is implementation-dependent.
    • setMethodName

      void setMethodName(String methodName)
      Define the name of the generated method. Defaults to an unspecified name.
    • setParameters

      void setParameters(String[] names, Class[] 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.

    • setThrownExceptions

      void setThrownExceptions(Class[] thrownExceptions)
      Define the exceptions that the generated method may throw.
    • evaluate

      Object evaluate(Object[] arguments) throws InvocationTargetException
      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:
      InvocationTargetException
    • getMethod

      Method getMethod()
      Returns the loaded Method.

      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(Class[] returnTypes)
      Defines the return types of the generated methods. The meaning of null values is implementation-dependent.
    • setMethodNames

      void setMethodNames(String[] 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(String[][] names, Class[][] types)
      Same as setParameters(String[], Class[]), but for multiple scripts.
    • setThrownExceptions

      void setThrownExceptions(Class[][] thrownExceptions)
      Same as setThrownExceptions(Class[]), but for multiple scripts.
    • cook

      void cook(Reader[] readers) throws CompileException, IOException
      Same as ICookable.cook(Reader), but for multiple scripts.
      Throws:
      CompileException
      IOException
    • cook

      void cook(String[] optionalFileNames, Reader[] readers) throws CompileException, IOException
      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:
      IllegalStateException - if any of the preceding set...() had an array size different from that of scanners
      CompileException
      IOException
    • cook

      void cook(String[] strings) throws CompileException
      Same as ICookable.cook(String), but for multiple scripts.
      Throws:
      CompileException
    • cook

      void cook(String[] optionalFileNames, String[] strings) throws CompileException
      Same as ICookable.cook(String, String), but for multiple scripts.
      Throws:
      CompileException
    • evaluate

      Object evaluate(int idx, Object[] arguments) throws InvocationTargetException
      Same as evaluate(Object[]), but for multiple scripts.
      Throws:
      InvocationTargetException
    • getMethod

      Method getMethod(int idx)
      Same as getMethod(), but for multiple scripts.
    • createFastEvaluator

      Object createFastEvaluator(String script, Class interfaceToImplement, String[] parameterNames) throws CompileException
      Parameters:
      script - Contains the sequence of script tokens
      Throws:
      CompileException
      See Also:
    • createFastEvaluator

      Object createFastEvaluator(Reader reader, Class interfaceToImplement, String[] parameterNames) throws CompileException, 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);
       }
       ...
       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
      IOException