Package org.codehaus.commons.compiler

Interface IScriptEvaluator

    • Field Detail

      • DEFAULT_METHOD_NAME

        static final java.lang.String DEFAULT_METHOD_NAME
        The name of the generated method(s), if no custom method name is configured with setMethodNames(String[]).

        The '*' in this string is replaced with the method index, starting at 0.

        See Also:
        Constant Field Values

      • DEFAULT_RETURN_TYPE

        static final java.lang.Class<?> DEFAULT_RETURN_TYPE
        The return type for any script for which no return type is explicitly configured.

    • Method Detail

      • setParentClassLoader

        void setParentClassLoader​(@Nullable
                          java.lang.ClassLoader parentClassLoader)
        The "parent class loader" is used to load referenced classes. Useful values are:
        System.getSystemClassLoader() The running JVM's class path
        Thread.currentThread().getContextClassLoader() or null The class loader effective for the invoking thread
        ClassLoaders.BOOTCLASSPATH_CLASS_LOADER The running JVM's boot class path

        The parent class loader defaults to the current thread's context class loader.

      • setDebuggingInformation

        void setDebuggingInformation​(boolean debugSource,
                             boolean debugLines,
                             boolean debugVars)
        Determines what kind of debugging information is included in the generates classes. The default is typically "-g:none".

      • setCompileErrorHandler

        void setCompileErrorHandler​(@Nullable
                            ErrorHandler compileErrorHandler)
        Installs an ErrorHandler which is invoked during compilation on each error. (By default, the compilation throws a CompileException on the first error and terminates.)

        If the given ErrorHandler throws a CompileException, then the compilation terminates and the exception is propagated.

        If the given ErrorHandler does not throw a CompileException but completes normally, then the compilation may or may not continue, depending on the error. Iff the compilation completes normally but errors were reported, then it will throw a CompileException indicating the number of errors.

        In other words: The ErrorHandler may throw a CompileException or not, but the compilation will definitely throw a CompileException if one or more compile errors have occurred.

        Parameters:
        compileErrorHandler - null to restore the default behavior (throwing a CompileException)

      • setWarningHandler

        void setWarningHandler​(@Nullable
                       WarningHandler warningHandler)
        By default, warnings are discarded, but an application my install a custom WarningHandler.
        Parameters:
        warningHandler - null to indicate that no warnings be issued

      • setDefaultReturnType

        void setDefaultReturnType​(java.lang.Class<?> defaultReturnType)
        When this IScriptEvaluator is coooked, then the defaultReturnType applies to all scripts for which no explicit return type was configured.

        The initial default return type (if you want, the "default-default" return type) is void.class.

        See Also:
        setReturnType(Class), setReturnTypes(Class[])

      • setOverrideMethod

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

      • setStaticMethod

        void setStaticMethod​(boolean staticMethod)
        Defines whether the generated method should be STATIC or not. Defaults to true.

      • setReturnType

        void setReturnType​(java.lang.Class<?> returnType)
        Defines the return type of the generated method. Value null means "use the default return type".
        See Also:
        setDefaultReturnType(Class)

      • setMethodName

        void setMethodName​(@Nullable
                   java.lang.String methodName)
        Defines the name of the generated method. Initially, the method name is "eval*".
        Parameters:
        methodName - null means reset to default name
        See Also:
        DEFAULT_METHOD_NAME

      • setParameters

        void setParameters​(java.lang.String[] names,
                   java.lang.Class<?>[] types)
        Defines the names and types of the parameters of the generated method.

        names.length and types.length must be equal. This invariant may be checked immediately, or later when the script is cooked.

        The parameters can be of primitive type, e.g. double.class.

        The default is to have zero parameters.

      • setThrownExceptions

        void setThrownExceptions​(java.lang.Class<?>[] thrownExceptions)
        Defines the exceptions that the generated method may throw.

      • evaluate

        @Nullable
java.lang.Object evaluate()
                   throws java.lang.reflect.InvocationTargetException
        Shorthand for evaluate(new Object[0]).
        Throws:
        java.lang.reflect.InvocationTargetException

      • evaluate

        @Nullable
java.lang.Object evaluate​(@Nullable
                          java.lang.Object[] arguments)
                   throws java.lang.reflect.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.

        Notice: In version 3.1.8, the arguments parameter was changed from Object[] to Object..., which turned out to be a really bad decision because it caused a very ugly invocation ambiguity with evaluate(int, Object[]). Thus, with version 3.1.10, the parameter was changed back to Object[].

        Parameters:
        arguments - The actual parameter values
        Throws:
        java.lang.IllegalStateException - This IScriptEvaluator is not yet cooked
        java.lang.reflect.InvocationTargetException

      • getMethod

        java.lang.reflect.Method getMethod()
        Returns:
        The generated and loaded Method
        Throws:
        java.lang.IllegalStateException - This IScriptEvaluator is not yet cooked

      • 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​(java.lang.Class<?>[] returnTypes)
        Configures the return types of the generated methods. If an element of the array is null, then use the "default return type" for that script.
        Parameters:
        returnTypes - The methods' return types; null elements mean "use the default return type"
        See Also:
        setDefaultReturnType(Class), getDefaultReturnType()

      • setMethodNames

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

      • setThrownExceptions

        void setThrownExceptions​(java.lang.Class<?>[][] thrownExceptions)
        Same as setThrownExceptions(Class[]), but for multiple scripts.

      • cook

        void cook​(java.lang.String[] fileNames,
          java.io.Reader[] readers)
   throws CompileException,
          java.io.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 fileNames parameter to distinguish between the individual token sources.

        Iff the number of scanners is one, then that single script may contain leading IMPORT directives.

        s
        Specified by:
        cook in interface IMultiCookable
        Throws:
        java.lang.IllegalStateException - if any of the preceding set...() had an array size different from that of scanners
        CompileException
        java.io.IOException

      • evaluate

        @Nullable
java.lang.Object evaluate​(int idx,
                          @Nullable
                          java.lang.Object[] arguments)
                   throws java.lang.reflect.InvocationTargetException
        Same as evaluate(Object[]), but for multiple scripts.
        Throws:
        java.lang.reflect.InvocationTargetException

      • getMethod

        java.lang.reflect.Method getMethod​(int idx)
        Same as getMethod(), but for multiple scripts.

      • createFastEvaluator

        <T> T createFastEvaluator​(java.io.Reader reader,
                          java.lang.Class<T> interfaceToImplement,
                          java.lang.String[] parameterNames)
                   throws CompileException,
                          java.io.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 setClassName(String)).

        s
        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
        java.io.IOException

      • getResult

        java.lang.reflect.Method[] getResult()
        Returns:
        The generated and loaded methods that implement the cooked scripts
        Throws:
        java.lang.IllegalStateException - This IScriptEvaluator is not yet cooked