Package org.apache.commons.jexl3

Class JexlEngine

  • Direct Known Subclasses:
    Engine
    public abstract class JexlEngine
extends java.lang.Object
    Creates and evaluates JexlExpression and JexlScript objects. Determines the behavior of expressions and scripts during their evaluation with respect to:

    Note that methods that evaluate expressions may throw unchecked exceptions; The JexlException are thrown in "non-silent" mode but since these are RuntimeException, user-code should catch them wherever most appropriate.

    Since:
    2.0

    • Constructor Summary

      Constructors 
      Constructor Description
      JexlEngine()
      Default constructor

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void clearCache()
      Clears the expression cache.
      JexlExpression createExpression​(java.lang.String expression)
      Creates a JexlExpression from a String containing valid JEXL syntax.
      abstract JexlExpression createExpression​(JexlInfo info, java.lang.String expression)
      Creates an JexlExpression from a String containing valid JEXL syntax.
      JexlInfo createInfo()
      Create an information structure for dynamic set/get/invoke/new.
      JexlInfo createInfo​(java.lang.String fn, int l, int c)
      Creates a JexlInfo instance.
      JxltEngine createJxltEngine()
      Creates a new JxltEngine instance using this engine.
      JxltEngine createJxltEngine​(boolean noScript)
      Creates a new JxltEngine instance using this engine.
      abstract JxltEngine createJxltEngine​(boolean noScript, int cacheSize, char immediate, char deferred)
      Creates a new instance of JxltEngine using this engine.
      JexlScript createScript​(java.io.File scriptFile)
      Creates a Script from a File containing valid JEXL syntax.
      JexlScript createScript​(java.io.File scriptFile, java.lang.String... names)
      Creates a Script from a File containing valid JEXL syntax.
      JexlScript createScript​(java.lang.String scriptText)
      Creates a Script from a String containing valid JEXL syntax.
      JexlScript createScript​(java.lang.String source, java.lang.String... names)
      Creates a Script from a String containing valid JEXL syntax.
      JexlScript createScript​(java.net.URL scriptUrl)
      Creates a Script from a URL containing valid JEXL syntax.
      JexlScript createScript​(java.net.URL scriptUrl, java.lang.String... names)
      Creates a Script from a URL containing valid JEXL syntax.
      abstract JexlScript createScript​(JexlFeatures features, JexlInfo info, java.lang.String source, java.lang.String... names)
      Creates a JexlScript from a String containing valid JEXL syntax.
      JexlScript createScript​(JexlInfo info, java.io.File scriptFile, java.lang.String... names)
      Creates a Script from a File containing valid JEXL syntax.
      JexlScript createScript​(JexlInfo info, java.lang.String source, java.lang.String... names)
      Creates a JexlScript from a String containing valid JEXL syntax.
      JexlScript createScript​(JexlInfo info, java.net.URL scriptUrl, java.lang.String... names)
      Creates a Script from a URL containing valid JEXL syntax.
      abstract JexlArithmetic getArithmetic()
      Gets this engine underlying JexlArithmetic.
      abstract java.nio.charset.Charset getCharset()
      Gets the charset used for parsing.
      abstract java.lang.Object getProperty​(java.lang.Object bean, java.lang.String expr)
      Accesses properties of a bean using an expression.
      abstract java.lang.Object getProperty​(JexlContext context, java.lang.Object bean, java.lang.String expr)
      Accesses properties of a bean using an expression.
      static JexlContext.ThreadLocal getThreadContext()
      Accesses the current thread local context.
      static JexlEngine getThreadEngine()
      Accesses the current thread local engine.
      abstract JexlUberspect getUberspect()
      Gets this engine underlying JexlUberspect.
      abstract java.lang.Object invokeMethod​(java.lang.Object obj, java.lang.String meth, java.lang.Object... args)
      Invokes an object's method by name and arguments.
      abstract boolean isCancellable()
      Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
      abstract boolean isDebug()
      Checks whether this engine is in debug mode.
      abstract boolean isSilent()
      Checks whether this engine throws JexlException during evaluation.
      abstract boolean isStrict()
      Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
      abstract <T> T newInstance​(java.lang.Class<? extends T> clazz, java.lang.Object... args)
      Creates a new instance of an object using the most appropriate constructor based on the arguments.
      abstract java.lang.Object newInstance​(java.lang.String clazz, java.lang.Object... args)
      Creates a new instance of an object using the most appropriate constructor based on the arguments.
      protected java.lang.String readSource​(java.io.File file)
      Reads a JEXL source from a File.
      protected java.lang.String readSource​(java.net.URL url)
      Reads a JEXL source from an URL.
      abstract void setClassLoader​(java.lang.ClassLoader loader)
      Sets the class loader used to discover classes in 'new' expressions.
      abstract void setProperty​(java.lang.Object bean, java.lang.String expr, java.lang.Object value)
      Assign properties of a bean using an expression.
      abstract void setProperty​(JexlContext context, java.lang.Object bean, java.lang.String expr, java.lang.Object value)
      Assign properties of a bean using an expression.
      static void setThreadContext​(JexlContext.ThreadLocal tls)
      Sets the current thread local context.
      protected static java.lang.String toString​(java.io.BufferedReader reader)
      Creates a string from a reader.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • TRY_FAILED

        public static final java.lang.Object TRY_FAILED
        A marker singleton for invocation failures in tryInvoke.

      • ENGINE

        protected static final java.lang.ThreadLocal<JexlEngine> ENGINE
        The thread local engine.

      • DEFAULT_FEATURES

        public static final JexlFeatures DEFAULT_FEATURES
        Default features.

      • EMPTY_CONTEXT

        public static final JexlContext EMPTY_CONTEXT
        An empty/static/non-mutable JexlContext singleton used instead of null context.

      • EMPTY_NS

        public static final JexlContext.NamespaceResolver EMPTY_NS
        An empty/static/non-mutable JexlNamespace singleton used instead of null namespace.

      • JXLT_CACHE_SIZE

        private static final int JXLT_CACHE_SIZE
        The default Jxlt cache size.
        See Also:
        Constant Field Values

    • Constructor Detail

      • JexlEngine

        public JexlEngine()
        Default constructor

    • Method Detail

      • getThreadContext

        public static JexlContext.ThreadLocal getThreadContext()
        Accesses the current thread local context.
        Returns:
        the context or null

      • getThreadEngine

        public static JexlEngine getThreadEngine()
        Accesses the current thread local engine.

        Advanced: you should only use this to retrieve the engine within a method/ctor called through the evaluation of a script/expression.

        Returns:
        the engine or null

      • setThreadContext

        public static void setThreadContext​(JexlContext.ThreadLocal tls)
        Sets the current thread local context.

        This should only be used carefully, for instance when re-evaluating a "stored" script that requires a given Namespace resolver. Remember to synchronize access if context is shared between threads.

        Parameters:
        tls - the thread local context to set

      • toString

        protected static java.lang.String toString​(java.io.BufferedReader reader)
                                    throws java.io.IOException
        Creates a string from a reader.
        Parameters:
        reader - to be read.
        Returns:
        the contents of the reader as a String.
        Throws:
        java.io.IOException - on any error reading the reader.

      • clearCache

        public abstract void clearCache()
        Clears the expression cache.

      • createExpression

        public abstract JexlExpression createExpression​(JexlInfo info,
                                                java.lang.String expression)
        Creates an JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
        Parameters:
        info - An info structure to carry debugging information if needed
        expression - A String containing valid JEXL syntax
        Returns:
        An JexlExpression which can be evaluated using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script

      • createExpression

        public final JexlExpression createExpression​(java.lang.String expression)
        Creates a JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
        Parameters:
        expression - A String containing valid JEXL syntax
        Returns:
        An JexlExpression which can be evaluated using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script

      • createInfo

        public JexlInfo createInfo()
        Create an information structure for dynamic set/get/invoke/new.

        This gathers the class, method and line number of the first calling method outside of o.a.c.jexl3.

        Returns:
        a JexlInfo instance

      • createInfo

        public JexlInfo createInfo​(java.lang.String fn,
                           int l,
                           int c)
        Creates a JexlInfo instance.
        Parameters:
        fn - url/file/template/script user given name
        l - line number
        c - column number
        Returns:
        a JexlInfo instance

      • createJxltEngine

        public JxltEngine createJxltEngine()
        Creates a new JxltEngine instance using this engine.
        Returns:
        a JEXL Template engine

      • createJxltEngine

        public JxltEngine createJxltEngine​(boolean noScript)
        Creates a new JxltEngine instance using this engine.
        Parameters:
        noScript - whether the JxltEngine only allows Jexl expressions or scripts
        Returns:
        a JEXL Template engine

      • createJxltEngine

        public abstract JxltEngine createJxltEngine​(boolean noScript,
                                            int cacheSize,
                                            char immediate,
                                            char deferred)
        Creates a new instance of JxltEngine using this engine.
        Parameters:
        noScript - whether the JxltEngine only allows JEXL expressions or scripts
        cacheSize - the number of expressions in this cache, default is 256
        immediate - the immediate template expression character, default is '$'
        deferred - the deferred template expression character, default is '#'
        Returns:
        a JEXL Template engine

      • createScript

        public final JexlScript createScript​(java.io.File scriptFile)
        Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • createScript

        public final JexlScript createScript​(java.io.File scriptFile,
                                     java.lang.String... names)
        Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • createScript

        public abstract JexlScript createScript​(JexlFeatures features,
                                        JexlInfo info,
                                        java.lang.String source,
                                        java.lang.String... names)
        Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        features - A set of features that will be enforced during parsing
        info - An info structure to carry debugging information if needed
        source - A string containing valid JEXL syntax
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
        Returns:
        A JexlScript which can be executed using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script

      • createScript

        public final JexlScript createScript​(JexlInfo info,
                                     java.io.File scriptFile,
                                     java.lang.String... names)
        Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        info - An info structure to carry debugging information if needed
        scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • createScript

        public final JexlScript createScript​(JexlInfo info,
                                     java.lang.String source,
                                     java.lang.String... names)
        Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        info - An info structure to carry debugging information if needed
        source - A string containing valid JEXL syntax
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
        Returns:
        A JexlScript which can be executed using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script

      • createScript

        public final JexlScript createScript​(JexlInfo info,
                                     java.net.URL scriptUrl,
                                     java.lang.String... names)
        Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        info - An info structure to carry debugging information if needed
        scriptUrl - A URL containing valid JEXL syntax. Must not be null.
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • createScript

        public final JexlScript createScript​(java.lang.String scriptText)
        Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        scriptText - A String containing valid JEXL syntax
        Returns:
        A JexlScript which can be executed using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script.

      • createScript

        public final JexlScript createScript​(java.lang.String source,
                                     java.lang.String... names)
        Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        source - A String containing valid JEXL syntax
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
        Returns:
        A JexlScript which can be executed using a JexlContext
        Throws:
        JexlException - if there is a problem parsing the script

      • createScript

        public final JexlScript createScript​(java.net.URL scriptUrl)
        Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        scriptUrl - A URL containing valid JEXL syntax. Must not be null.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • createScript

        public final JexlScript createScript​(java.net.URL scriptUrl,
                                     java.lang.String... names)
        Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
        Parameters:
        scriptUrl - A URL containing valid JEXL syntax. Must not be null.
        names - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
        Returns:
        A JexlScript which can be executed with a JexlContext.
        Throws:
        JexlException - if there is a problem reading or parsing the script.

      • getCharset

        public abstract java.nio.charset.Charset getCharset()
        Gets the charset used for parsing.
        Returns:
        the charset

      • getProperty

        public abstract java.lang.Object getProperty​(JexlContext context,
                                             java.lang.Object bean,
                                             java.lang.String expr)
        Accesses properties of a bean using an expression.

        If the JEXL engine is silent, errors will be logged through its logger as warning.

        Parameters:
        context - the evaluation context
        bean - the bean to get properties from
        expr - the property expression
        Returns:
        the value of the property
        Throws:
        JexlException - if there is an error parsing the expression or during evaluation

      • getProperty

        public abstract java.lang.Object getProperty​(java.lang.Object bean,
                                             java.lang.String expr)
        Accesses properties of a bean using an expression.

        jexl.get(myobject, "foo.bar"); should equate to myobject.getFoo().getBar(); (or myobject.getFoo().get("bar"))

        If the JEXL engine is silent, errors will be logged through its logger as warning.

        Parameters:
        bean - the bean to get properties from
        expr - the property expression
        Returns:
        the value of the property
        Throws:
        JexlException - if there is an error parsing the expression or during evaluation

      • invokeMethod

        public abstract java.lang.Object invokeMethod​(java.lang.Object obj,
                                              java.lang.String meth,
                                              java.lang.Object... args)
        Invokes an object's method by name and arguments.
        Parameters:
        obj - the method's invoker object
        meth - the method's name
        args - the method's arguments
        Returns:
        the method returned value or null if it failed and engine is silent
        Throws:
        JexlException - if method could not be found or failed and engine is not silent

      • isCancellable

        public abstract boolean isCancellable()
        Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
        Returns:
        true if cancellable, false otherwise

      • isSilent

        public abstract boolean isSilent()
        Checks whether this engine throws JexlException during evaluation.
        Returns:
        true if silent, false (default) otherwise

      • isStrict

        public abstract boolean isStrict()
        Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
        Returns:
        true if strict, false otherwise

      • newInstance

        public abstract <T> T newInstance​(java.lang.Class<? extends T> clazz,
                                  java.lang.Object... args)
        Creates a new instance of an object using the most appropriate constructor based on the arguments.
        Type Parameters:
        T - the type of object
        Parameters:
        clazz - the class to instantiate
        args - the constructor arguments
        Returns:
        the created object instance or null on failure when silent

      • newInstance

        public abstract java.lang.Object newInstance​(java.lang.String clazz,
                                             java.lang.Object... args)
        Creates a new instance of an object using the most appropriate constructor based on the arguments.
        Parameters:
        clazz - the name of the class to instantiate resolved through this engine's class loader
        args - the constructor arguments
        Returns:
        the created object instance or null on failure when silent

      • readSource

        protected java.lang.String readSource​(java.io.File file)
        Reads a JEXL source from a File.
        Parameters:
        file - the script file
        Returns:
        the source

      • readSource

        protected java.lang.String readSource​(java.net.URL url)
        Reads a JEXL source from an URL.
        Parameters:
        url - the script url
        Returns:
        the source

      • setClassLoader

        public abstract void setClassLoader​(java.lang.ClassLoader loader)
        Sets the class loader used to discover classes in 'new' expressions.

        This method is not thread safe; it may be called after JexlEngine initialization and allow scripts to use new classes definitions.

        Parameters:
        loader - the class loader to use

      • setProperty

        public abstract void setProperty​(JexlContext context,
                                 java.lang.Object bean,
                                 java.lang.String expr,
                                 java.lang.Object value)
        Assign properties of a bean using an expression.

        If the JEXL engine is silent, errors will be logged through its logger as warning.

        Parameters:
        context - the evaluation context
        bean - the bean to set properties in
        expr - the property expression
        value - the value of the property
        Throws:
        JexlException - if there is an error parsing the expression or during evaluation

      • setProperty

        public abstract void setProperty​(java.lang.Object bean,
                                 java.lang.String expr,
                                 java.lang.Object value)
        Assign properties of a bean using an expression.

        jexl.set(myobject, "foo.bar", 10); should equate to myobject.getFoo().setBar(10); (or myobject.getFoo().put("bar", 10) )

        If the JEXL engine is silent, errors will be logged through its logger as warning.

        Parameters:
        bean - the bean to set properties in
        expr - the property expression
        value - the value of the property
        Throws:
        JexlException - if there is an error parsing the expression or during evaluation