Package org.mvel2

Class MVEL

  • public class MVEL
extends Object
    The MVEL convienence class is a collection of static methods that provides a set of easy integration points for MVEL. The vast majority of MVEL's core functionality can be directly accessed through methods in this class.

    • Field Detail

      • INVOKED_METHOD_EXCEPTIONS_BUBBLE

        public static boolean INVOKED_METHOD_EXCEPTIONS_BUBBLE

      • COMPILER_OPT_ALLOW_NAKED_METH_CALL

        public static boolean COMPILER_OPT_ALLOW_NAKED_METH_CALL

      • COMPILER_OPT_ALLOW_OVERRIDE_ALL_PROPHANDLING

        public static boolean COMPILER_OPT_ALLOW_OVERRIDE_ALL_PROPHANDLING

      • COMPILER_OPT_ALLOW_RESOLVE_INNERCLASSES_WITH_DOTNOTATION

        public static boolean COMPILER_OPT_ALLOW_RESOLVE_INNERCLASSES_WITH_DOTNOTATION

      • COMPILER_OPT_SUPPORT_JAVA_STYLE_CLASS_LITERALS

        public static boolean COMPILER_OPT_SUPPORT_JAVA_STYLE_CLASS_LITERALS

      • COMPILER_OPT_ALLOCATE_TYPE_LITERALS_TO_SHARED_SYMBOL_TABLE

        public static boolean COMPILER_OPT_ALLOCATE_TYPE_LITERALS_TO_SHARED_SYMBOL_TABLE

      • RUNTIME_OPT_THREAD_UNSAFE

        public static boolean RUNTIME_OPT_THREAD_UNSAFE

    • Method Detail

      • isAdvancedDebugging

        public static boolean isAdvancedDebugging()

      • getDebuggingOutputFileName

        public static String getDebuggingOutputFileName()

      • isFileDebugging

        public static boolean isFileDebugging()

      • eval

        public static Object eval​(String expression)
        Evaluate an expression and return the value.
        Parameters:
        expression - A String containing the expression to be evaluated.
        Returns:
        the resultant value

      • eval

        public static Object eval​(String expression,
                          Object ctx)
        Evaluate an expression against a context object. Expressions evaluated against a context object are designed to treat members of that context object as variables in the expression. For example: 
        
 MVEL.eval("foo == 1", ctx);
        In this case, the identifier foo would be resolved against the ctx object. So it would have the equivalent of: ctc.getFoo() == 1 in Java.
        Parameters:
        expression - A String containing the expression to be evaluated.
        ctx - The context object to evaluate against.
        Returns:
        The resultant value

      • eval

        public static Object eval​(String expression,
                          VariableResolverFactory resolverFactory)
        Evaluate an expression with externally injected variables via a VariableResolverFactory. A factory provides the means by which MVEL can resolve external variables. MVEL contains a straight-forward implementation for wrapping Maps: MapVariableResolverFactory, which is used implicitly when calling overloaded methods in this class that use Maps. An example: 
        
 Map varsMap = new HashMap();
 varsMap.put("x", 5);
 varsMap.put("y", 2);

 VariableResolverFactory factory = new MapVariableResolverFactory(varsMap);

 Integer i = (Integer) MVEL.eval("x * y", factory);

 assert i == 10;
        Parameters:
        expression - A String containing the expression to be evaluated.
        resolverFactory - The instance of the VariableResolverFactory to be used.
        Returns:
        The resultant value.

      • eval

        public static Object eval​(String expression,
                          Object ctx,
                          Map<String,​Object> vars)
        Evaluates an expression against a context object and externally injected variables. This is a wrapper convenience method which wraps the provided Map of vars in a MapVariableResolverFactory
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context object to evaluate against.
        vars - A map of vars to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, VariableResolverFactory)

      • eval

        public static <T> T eval​(String expression,
                         Class<T> toType)
        Evaluates an expression and, if necessary, coerces the resultant value to the specified type. Example: 
        
 Float output = MVEL.eval("5 + 5", Float.class);
        This converts an expression that would otherwise return an Integer to a Float.
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated.
        toType - The target type that the resultant value will be converted to, if necessary.
        Returns:
        The resultant value.

      • eval

        public static <T> T eval​(String expression,
                         Object ctx,
                         Class<T> toType)
        Evaluates an expression against a context object and, if necessary, coerces the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context object to evaluate against.
        toType - The target type that the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, Class)

      • eval

        public static <T> T eval​(String expression,
                         VariableResolverFactory vars,
                         Class<T> toType)
        Evaluates an expression against externally injected variables and, if necessary, coerces the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated
        vars - The variables to be injected
        toType - The target type that the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, VariableResolverFactory), eval(String, Class)

      • eval

        public static <T> T eval​(String expression,
                         Map<String,​Object> vars,
                         Class<T> toType)
        Evaluates an expression against externally injected variables. The resultant value is coerced to the specified type if necessary. This is a wrapper convenience method which wraps the provided Map of vars in aMapVariableResolverFactory
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated.
        vars - A map of vars to be injected
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, org.mvel2.integration.VariableResolverFactory)

      • eval

        public static <T> T eval​(String expression,
                         Object ctx,
                         VariableResolverFactory vars,
                         Class<T> toType)
        Evaluates an expression against a context object and externally injected variables. If necessary, the resultant value is coerced to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - The vars to be injected
        toType - The target type that the resultant value will be converted to, if necessary.
        Returns:
        The resultant value.
        See Also:
        eval(String, Object, VariableResolverFactory), eval(String, Class)

      • eval

        public static <T> T eval​(String expression,
                         Object ctx,
                         Map<String,​Object> vars,
                         Class<T> toType)
        Evaluates an expression against a context object and externally injected variables. If necessary, the resultant value is coerced to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - A Map of variables to be injected.
        toType - The target type that the resultant value will be converted to, if necessary.
        Returns:
        The resultant value.
        See Also:
        eval(String, Object, VariableResolverFactory), eval(String, Class)

      • evalToString

        public static String evalToString​(String expression)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        Returns:
        The resultant value

      • evalToString

        public static String evalToString​(String expression,
                                  Object ctx)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        ctx - The context object to evaluate against
        Returns:
        The resultant value
        See Also:
        eval(String, Object)

      • evalToString

        public static String evalToString​(String expression,
                                  VariableResolverFactory vars)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        vars - The variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, VariableResolverFactory)

      • evalToString

        public static String evalToString​(String expression,
                                  Map vars)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        vars - A Map of variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, Map)

      • evalToString

        public static String evalToString​(String expression,
                                  Object ctx,
                                  VariableResolverFactory vars)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        ctx - The context object to evaluate against.
        vars - The variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, Map)

      • evalToString

        public static String evalToString​(String expression,
                                  Object ctx,
                                  Map vars)
        Evaluates an expression and returns the resultant value as a String.
        Parameters:
        expression - A string containing the expressino to be evaluated.
        ctx - The context object to evaluate against.
        vars - A Map of variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, Map)

      • eval

        public static Object eval​(char[] expression)
        Evaluate an expression and return the value.
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        Returns:
        The resultant value
        See Also:
        eval(String)

      • eval

        public static Object eval​(char[] expression,
                          Object ctx)
        Evaluate an expression against a context object and return the value
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        Returns:
        The resultant value
        See Also:
        eval(String, Object)

      • eval

        public static <T> T eval​(char[] expression,
                         Class<T> type)

      • eval

        public static Object eval​(char[] expression,
                          Object ctx,
                          VariableResolverFactory vars)
        Evaluate an expression against a context object and return the value
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - The variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, Object, VariableResolverFactory)

      • eval

        public static Object eval​(char[] expression,
                          Object ctx,
                          Map vars)
        Evaluate an expression against a context object and return the value
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - A Map of variables to be injected
        Returns:
        The resultant value
        See Also:
        eval(String, Object, Map)

      • eval

        public static <T> T eval​(char[] expression,
                         Object ctx,
                         Map<String,​Object> vars,
                         Class<T> toType)
        Evaluate an expression with a context object and injected variables and return the value. If necessary convert the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - A Map of variables to be injected
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, Object, Map, Class)

      • eval

        public static <T> T eval​(char[] expression,
                         Object ctx,
                         Class<T> toType)
        Evaluate an expression with a context object and return the value. If necessary convert the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, Object, Class)

      • eval

        public static <T> T eval​(char[] expression,
                         Object ctx,
                         VariableResolverFactory vars,
                         Class<T> toType)
        Evaluate an expression with a context object and injected variables and return the value. If necessary convert the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        ctx - The context object to evaluate against
        vars - The variables to be injected
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, Object, VariableResolverFactory, Class)

      • eval

        public static <T> T eval​(char[] expression,
                         VariableResolverFactory vars,
                         Class<T> toType)
        Evaluate an expression with injected variables and return the value. If necessary convert the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        vars - The variables to be injected
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, VariableResolverFactory, Class)

      • eval

        public static <T> T eval​(char[] expression,
                         Map<String,​Object> vars,
                         Class<T> toType)
        Evaluate an expression with injected variables and return the resultant value. If necessary convert the resultant value to the specified type.
        Type Parameters:
        T - type
        Parameters:
        expression - A char[] containing the expression to be evaluated.
        vars - The variables to be injected
        toType - The target type the resultant value will be converted to, if necessary.
        Returns:
        The resultant value
        See Also:
        eval(String, Map, Class)

      • evalFile

        public static Object evalFile​(File file)
                       throws IOException
        Evaluate a script from a file and return the resultant value.
        Parameters:
        file - The file to process
        Returns:
        The resultant value
        Throws:
        IOException - Exception thrown if there is an IO problem accessing the file.

      • evalFile

        public static Object evalFile​(File file,
                              Object ctx)
                       throws IOException
        Evaluate a script from a file, against a context object and return the resultant value.
        Parameters:
        file - The file to process
        ctx - The context to evaluate the script against.
        Returns:
        The resultant value
        Throws:
        IOException - Exception thrown if there is an IO problem accessing the file.

      • evalFile

        public static Object evalFile​(File file,
                              Map<String,​Object> vars)
                       throws IOException
        Evaluate a script from a file with injected variables and return the resultant value.
        Parameters:
        file - The file to process
        vars - Variables to be injected
        Returns:
        The resultant value
        Throws:
        IOException - Exception thrown if there is an IO problem accessing the file.

      • evalFile

        public static Object evalFile​(File file,
                              Object ctx,
                              Map<String,​Object> vars)
                       throws IOException
        Evaluate a script from a file with injected variables and a context object, then return the resultant value.
        Parameters:
        file - The file to process
        ctx - The context to evaluate the script against.
        vars - Variables to be injected
        Returns:
        The resultant value
        Throws:
        IOException - Exception thrown if there is an IO problem accessing the file.

      • evalFile

        public static Object evalFile​(File file,
                              Object ctx,
                              VariableResolverFactory vars)
                       throws IOException
        Evaluate a script from a file with injected variables and a context object, then return the resultant value.
        Parameters:
        file - The file to process
        ctx - The context to evaluate the script against.
        vars - Variables to be injected
        Returns:
        The resultant value
        Throws:
        IOException - Exception thrown if there is an IO problem accessing the file.

      • evalToBoolean

        public static Boolean evalToBoolean​(String expression,
                                    Object ctx,
                                    Map<String,​Object> vars)
        Evaluate an expression in Boolean-only mode against a root context object and injected variables.
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context against which to evaluate the expression
        vars - The variables to be injected
        Returns:
        The resultant value as a Boolean

      • evalToBoolean

        public static Boolean evalToBoolean​(String expression,
                                    Object ctx)
        Evaluate an expression in Boolean-only mode against a root context object.
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context against which to evaluate the expression
        Returns:
        The resultant value as a Boolean

      • evalToBoolean

        public static Boolean evalToBoolean​(String expression,
                                    Object ctx,
                                    VariableResolverFactory vars)
        Evaluate an expression in Boolean-only mode against a root context object and injected variables.
        Parameters:
        expression - A string containing the expression to be evaluated.
        ctx - The context against which to evaluate the expression
        vars - The variables to be injected
        Returns:
        The resultant value as a Boolean

      • evalToBoolean

        public static Boolean evalToBoolean​(String expression,
                                    VariableResolverFactory vars)
        Evaluate an expression in Boolean-only with injected variables.
        Parameters:
        expression - A string containing the expression to be evaluated.
        vars - The variables to be injected
        Returns:
        The resultant value as a Boolean

      • evalToBoolean

        public static Boolean evalToBoolean​(String expression,
                                    Map<String,​Object> vars)
        Evaluate an expression in Boolean-only with injected variables.
        Parameters:
        expression - A string containing the expression to be evaluated.
        vars - The variables to be injected
        Returns:
        The resultant value as a Boolean

      • analysisCompile

        public static void analysisCompile​(char[] expression,
                                   ParserContext ctx)
        Performs an analysis compileShared, which will populate the ParserContext with type, input and variable information, but will not produce a payload.
        Parameters:
        expression - - the expression to analyze
        ctx - - the parser context

      • analysisCompile

        public static void analysisCompile​(String expression,
                                   ParserContext ctx)

      • compileExpression

        public static Serializable compileExpression​(String expression)
        Compiles an expression and returns a Serializable object containing the compiled expression. The returned value can be reused for higher-performance evaluation of the expression. It is used in a straight forward way: 
        

 // Compile the expression
 Serializable compiled = MVEL.compileExpression("x * 10");

 // Create a Map to hold the variables.
 Map vars = new HashMap();

 // Create a factory to envelop the variable map
 VariableResolverFactory factory = new MapVariableResolverFactory(vars);

 int total = 0;
 for (int i = 0; i < 100; i++) {
 // Update the 'x' variable.
 vars.put("x", i);

 // Execute the expression against the compiled payload and factory, and add the result to the total variable.
 total += (Integer) MVEL.executeExpression(compiled, factory);
 }

 // Total should be 49500
 assert total == 49500;
        The above example demonstrates a compiled expression being reused ina tight, closed, loop. Doing this greatly improves performance as re-parsing of the expression is not required, and the runtime can dynamically compileShared the expression to bytecode of necessary.
        Parameters:
        expression - A String contaiing the expression to be compiled.
        Returns:
        The cacheable compiled payload.

      • compileExpression

        public static Serializable compileExpression​(String expression,
                                             Map<String,​Object> imports)
        Compiles an expression and returns a Serializable object containing the compiled expression. This method also accept a Map of imports. The Map's keys are String's representing the imported, short-form name of the Classes or Methods imported. An import of a Method is essentially a static import. This is a substitute for needing to declare import statements within the actual script. 
        
 Map imports = new HashMap();
 imports.put("HashMap", java.util.HashMap.class); // import a class
 imports.put("time", MVEL.getStaticMethod(System.class, "currentTimeMillis", new Class[0])); // import a static method

 // Compile the expression
 Serializable compiled = MVEL.compileExpression("map = new HashMap(); map.put('time', time()); map.time");

 // Execute with a blank Map to allow vars to be declared.
 Long val = (Long) MVEL.executeExpression(compiled, new HashMap());

 assert val > 0;
        Parameters:
        expression - A String contaiing the expression to be compiled.
        imports - A String-Class/String-Method pair Map containing imports for the compiler.
        Returns:
        The cacheable compiled payload.

      • compileExpression

        public static Serializable compileExpression​(String expression,
                                             Map<String,​Object> imports,
                                             Map<String,​Interceptor> interceptors)
        Compiles an expression and returns a Serializable object containing the compiled expression. This method accepts a Map of imports and Interceptors. See compileExpression(String, Map) for information on imports. The imports parameter in this method is optional and it is safe to pass a null value. Interceptors are markers within an expression that allow external hooks to be tied into the expression. 
        
 // Create a Map to hold the interceptors.
 Map interceptors = new HashMap();

 // Create a simple interceptor.
 Interceptor logInterceptor = new Interceptor() {
 public int doBefore(ASTNode node, VariableResolverFactory factory) {
 System.out.println("Interceptor called before!");
 }

 public int doAfter(Object exitValue, ASTNode node, VariableResolverFactory factory) {
 System.out.println("Interceptor called after!");
 }
 };

 // Add the interceptor to the Map.
 interceptors.put("log", logInterceptor);

 // Create an expression
 String expr = "list = [1,2,3,4,5]; @log for (item : list) { System.out.println(item); };

 Serializable compiled = MVEL.compileExpression(expr, null, interceptors);

 // Execute expression with a blank Map to allow vars to be declared.
 MVEL.executeExpression(compiled, new HashMap());
        The above example demonstrates inserting an interceptor into a piece of code. The @log interceptor wraps the subsequent statement. In this case, the interceptor is fired before the for loop and after the for loop finishes.
        Parameters:
        expression - A String containing the expression to be evaluated.
        imports - A String-Class/String-Method pair Map containing imports for the compiler.
        interceptors - A Map of registered interceptors.
        Returns:
        A cacheable compiled payload.

      • compileExpression

        public static Serializable compileExpression​(String expression,
                                             ParserContext ctx)
        Compiles an expression, and accepts a ParserContext instance. The ParserContext object is the fine-grained configuration object for the MVEL parser and compiler.
        Parameters:
        expression - A string containing the expression to be compiled.
        ctx - The parser context
        Returns:
        A cacheable compiled payload.

      • compileExpression

        public static Serializable compileExpression​(char[] expression,
                                             int start,
                                             int offset,
                                             ParserContext ctx)

      • compileExpression

        public static Serializable compileExpression​(char[] expression,
                                             Map<String,​Object> imports,
                                             Map<String,​Interceptor> interceptors,
                                             String sourceName)
        Compiles an expression and returns a Serializable object containing the compiled expression.
        Parameters:
        expression - The expression to be compiled
        imports - Imported classes
        interceptors - Map of named interceptos
        sourceName - The name of the source file being evaluated (optional)
        Returns:
        The cacheable compiled payload

      • compileExpression

        public static Serializable compileExpression​(char[] expression)

      • compileGetExpression

        public static Serializable compileGetExpression​(String expression)

      • compileGetExpression

        public static Serializable compileGetExpression​(char[] expression)

      • compileSetExpression

        public static Serializable compileSetExpression​(String expression)

      • compileSetExpression

        public static Serializable compileSetExpression​(char[] expression)

      • compileSetExpression

        public static Serializable compileSetExpression​(char[] expression,
                                                int start,
                                                int offset,
                                                ParserContext ctx)

      • executeSetExpression

        public static void executeSetExpression​(Serializable compiledSet,
                                        Object ctx,
                                        Object value)

      • executeExpression

        public static Object executeExpression​(Object compiledExpression)

      • executeExpression

        public static Object executeExpression​(Object compiledExpression,
                                       Object ctx,
                                       Map vars)
        Executes a compiled expression.
        Parameters:
        compiledExpression - -
        ctx - -
        vars - -
        Returns:
        -
        See Also:
        compileExpression(String)

      • executeExpression

        public static Object executeExpression​(Object compiledExpression,
                                       Object ctx)
        Executes a compiled expression.
        Parameters:
        compiledExpression - -
        ctx - -
        Returns:
        -
        See Also:
        compileExpression(String)

      • executeExpression

        public static Object executeExpression​(Object compiledExpression,
                                       Map vars)
        Executes a compiled expression.
        Parameters:
        compiledExpression - -
        vars - -
        Returns:
        -
        See Also:
        compileExpression(String)

      • executeExpression

        public static <T> T executeExpression​(Object compiledExpression,
                                      Object ctx,
                                      Map vars,
                                      Class<T> toType)
        Execute a compiled expression and convert the result to a type
        Type Parameters:
        T - type
        Parameters:
        compiledExpression - -
        ctx - -
        vars - -
        toType - -
        Returns:
        -

      • executeExpression

        public static <T> T executeExpression​(Object compiledExpression,
                                      Map vars,
                                      Class<T> toType)
        Execute a compiled expression and convert the result to a type
        Type Parameters:
        T - type
        Parameters:
        compiledExpression - -
        vars - -
        toType - -
        Returns:
        -

      • executeExpression

        public static <T> T executeExpression​(Object compiledExpression,
                                      Object ctx,
                                      Class<T> toType)
        Execute a compiled expression and convert the result to a type.
        Type Parameters:
        T - type
        Parameters:
        compiledExpression - -
        ctx - -
        toType - -
        Returns:
        -

      • preprocess

        public static String preprocess​(char[] input,
                                PreProcessor[] preprocessors)

      • setProperty

        public static void setProperty​(Object ctx,
                               String property,
                               Object value)

      • getStaticMethod

        public static Method getStaticMethod​(Class cls,
                                     String methodName,
                                     Class[] signature)
        A simple utility method to get a static method from a class with no checked exception. With throw a RuntimeException if the method is not found or is not a static method.
        Parameters:
        cls - The class containing the static method
        methodName - The method name
        signature - The signature of the method
        Returns:
        An instance of the Method