Class Engine

  • Direct Known Subclasses:
    Engine32

    public class Engine
    extends JexlEngine
    A JexlEngine implementation.
    Since:
    2.0
    • Field Detail

      • PROPERTY_FEATURES

        protected static final JexlFeatures PROPERTY_FEATURES
        The features allowed for property set/get methods.
      • logger

        protected final org.apache.commons.logging.Log logger
        The Log to which all JexlEngine messages will be logged.
      • uberspect

        protected final JexlUberspect uberspect
        The JexlUberspect instance.
      • functions

        protected final java.util.Map<java.lang.String,​java.lang.Object> functions
        The map of 'prefix:function' to object implementing the namespaces.
      • classNameSolver

        protected final FqcnResolver classNameSolver
        The default class name resolver.
      • stackOverflow

        protected final int stackOverflow
        The maximum stack height.
      • strict

        protected final boolean strict
        Whether this engine considers unknown variables, methods and constructors as errors.
      • safe

        protected final boolean safe
        Whether this engine considers null in navigation expression as errors.
      • silent

        protected final boolean silent
        Whether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors. Default is false.
      • cancellable

        protected final boolean cancellable
        Whether expressions evaluated by this engine will throw JexlException.Cancel (true) or return null (false) when interrupted. Default is true when not silent and strict.
      • debug

        protected final boolean debug
        Whether error messages will carry debugging information.
      • scriptFeatures

        protected final JexlFeatures scriptFeatures
        The set of default script parsing features.
      • expressionFeatures

        protected final JexlFeatures expressionFeatures
        The set of default expression parsing features.
      • charset

        protected final java.nio.charset.Charset charset
        The default charset.
      • parsing

        protected final java.util.concurrent.atomic.AtomicBoolean parsing
        The atomic parsing flag; true whilst parsing.
      • parser

        protected final Parser parser
        The Parser; when parsing expressions, this engine uses the parser if it is not already in use otherwise it will create a new temporary one.
      • cacheThreshold

        protected final int cacheThreshold
        The expression max length to hit the cache.
      • jxlt

        protected volatile TemplateEngine jxlt
        The default jxlt engine.
      • collectMode

        protected final int collectMode
        Collect all or only dot references.
      • options

        protected final JexlOptions options
        A cached version of the options.
      • cacheFactory

        protected final java.util.function.IntFunction<JexlCache<?,​?>> cacheFactory
        The cache factory method.
    • Constructor Detail

      • Engine

        public Engine()
        Creates an engine with default arguments.
      • Engine

        public Engine​(JexlBuilder conf)
        Creates a JEXL engine using the provided JexlBuilder.
        Parameters:
        conf - the builder
    • Method Detail

      • getUberspect

        public static Uberspect getUberspect​(org.apache.commons.logging.Log logger,
                                             JexlUberspect.ResolverStrategy strategy,
                                             JexlPermissions permissions)
        Gets the default instance of Uberspect.

        This is lazily initialized to avoid building a default instance if there is no use for it. The main reason for not using the default Uberspect instance is to be able to use a (low level) introspector created with a given logger instead of the default one and even more so for with a different (restricted) set of permissions.

        Parameters:
        logger - the logger to use for the underlying Uberspect
        strategy - the property resolver strategy
        permissions - the introspection permissions
        Returns:
        Uberspect the default uberspector instance.
        Since:
        3.3
      • option

        private static <T> T option​(T conf,
                                    T def)
        Solves an optional option.
        Type Parameters:
        T - the option type
        Parameters:
        conf - the option as configured, may be null
        def - the default value if null, shall not be null
        Returns:
        conf or def
      • clearCache

        public void clearCache()
        Description copied from class: JexlEngine
        Clears the expression cache.
        Specified by:
        clearCache in class JexlEngine
      • createExpression

        public Script createExpression​(JexlInfo info,
                                       java.lang.String expression)
        Description copied from class: JexlEngine
        Creates an JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
        Specified by:
        createExpression in class JexlEngine
        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
      • createInterpreter

        protected Interpreter createInterpreter​(JexlContext context,
                                                Frame frame,
                                                JexlOptions opts)
        Creates an interpreter.
        Parameters:
        context - a JexlContext; if null, the empty context is used instead.
        frame - the interpreter frame
        opts - the evaluation options
        Returns:
        an Interpreter
      • createJxltEngine

        public TemplateEngine createJxltEngine​(boolean noScript,
                                               int cacheSize,
                                               char immediate,
                                               char deferred)
        Description copied from class: JexlEngine
        Creates a new instance of JxltEngine using this engine.
        Specified by:
        createJxltEngine in class JexlEngine
        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 Script createScript​(JexlFeatures features,
                                   JexlInfo info,
                                   java.lang.String scriptText,
                                   java.lang.String... names)
        Description copied from class: JexlEngine
        Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
        Specified by:
        createScript in class JexlEngine
        Parameters:
        features - A set of features that will be enforced during parsing
        info - An info structure to carry debugging information if needed
        scriptText - 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
      • createTemplateInterpreter

        protected Interpreter createTemplateInterpreter​(TemplateInterpreter.Arguments args)
        Creates a template interpreter.
        Parameters:
        args - the template interpreter arguments
      • doCreateInstance

        protected java.lang.Object doCreateInstance​(java.lang.Object clazz,
                                                    java.lang.Object... args)
        Creates a new instance of an object using the most appropriate constructor based on the arguments.
        Parameters:
        clazz - the class to instantiate
        args - the constructor arguments
        Returns:
        the created object instance or null on failure when silent
      • evalOptions

        protected JexlOptions evalOptions​(ASTJexlScript script,
                                          JexlContext context)
        Compute a script options for evaluation.

        This calls processPragma(...).

        Parameters:
        script - the script
        context - the context
        Returns:
        the options
      • evalOptions

        protected JexlOptions evalOptions​(JexlContext context)
        Extracts the engine evaluation options from context if available, the engine options otherwise.

        If the context is an options handle and the handled options shared instance flag is false, this method creates a copy of the options making them immutable during execution.

        Parameters:
        context - the context
        Returns:
        the options if any
      • evalOptions

        private JexlOptions evalOptions​(JexlEngine.Options opts)
        Obsolete version of options evaluation.
        Parameters:
        opts - the obsolete instance of options
        Returns:
        the newer class of options
      • getCharset

        public java.nio.charset.Charset getCharset()
        Description copied from class: JexlEngine
        Gets the charset used for parsing.
        Specified by:
        getCharset in class JexlEngine
        Returns:
        the charset
      • getLocalVariables

        protected java.lang.String[] getLocalVariables​(JexlScript script)
        Gets the array of local variable from a script.
        Parameters:
        script - the script
        Returns:
        the local variables array which may be empty (but not null) if no local variables were defined
        Since:
        3.0
      • getNamespace

        final java.lang.Object getNamespace​(java.lang.String name)
        Solves a namespace using this engine map of functions.
        Parameters:
        name - the namespoce name
        Returns:
        the object associated
      • getParameters

        protected java.lang.String[] getParameters​(JexlScript script)
        Gets the array of parameters from a script.
        Parameters:
        script - the script
        Returns:
        the parameters which may be empty (but not null) if no parameters were defined
        Since:
        3.0
      • getProperty

        public java.lang.Object getProperty​(JexlContext context,
                                            java.lang.Object bean,
                                            java.lang.String expr)
        Description copied from class: JexlEngine
        Accesses properties of a bean using an expression.

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

        Specified by:
        getProperty in class JexlEngine
        Parameters:
        context - the evaluation context
        bean - the bean to get properties from
        expr - the property expression
        Returns:
        the value of the property
      • getProperty

        public java.lang.Object getProperty​(java.lang.Object bean,
                                            java.lang.String expr)
        Description copied from class: JexlEngine
        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.

        Specified by:
        getProperty in class JexlEngine
        Parameters:
        bean - the bean to get properties from
        expr - the property expression
        Returns:
        the value of the property
      • getVariables

        protected java.util.Set<java.util.List<java.lang.String>> getVariables​(ASTJexlScript script)
        Gets the list of variables accessed by a script.

        This method will visit all nodes of a script and extract all variables whether they are written in 'dot' or 'bracketed' notation. (a.b is equivalent to a['b']).

        Parameters:
        script - the script
        Returns:
        the set of variables, each as a list of strings (ant-ish variables use more than 1 string) or the empty set if no variables are used
      • getVariables

        protected void getVariables​(ASTJexlScript script,
                                    JexlNode node,
                                    Engine.VarCollector collector)
        Fills up the list of variables accessed by a node.
        Parameters:
        script - the owning script
        node - the node
        collector - the variable collector
      • invokeMethod

        public java.lang.Object invokeMethod​(java.lang.Object obj,
                                             java.lang.String meth,
                                             java.lang.Object... args)
        Description copied from class: JexlEngine
        Invokes an object's method by name and arguments.
        Specified by:
        invokeMethod in class JexlEngine
        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
      • isCancellable

        public boolean isCancellable()
        Description copied from class: JexlEngine
        Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
        Specified by:
        isCancellable in class JexlEngine
        Returns:
        true if cancellable, false otherwise
      • isDebug

        public boolean isDebug()
        Description copied from class: JexlEngine
        Checks whether this engine is in debug mode.
        Specified by:
        isDebug in class JexlEngine
        Returns:
        true if debug is on, false otherwise
      • isSilent

        public boolean isSilent()
        Description copied from class: JexlEngine
        Checks whether this engine throws JexlException during evaluation.
        Specified by:
        isSilent in class JexlEngine
        Returns:
        true if silent, false (default) otherwise
      • isStrict

        public boolean isStrict()
        Description copied from class: JexlEngine
        Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
        Specified by:
        isStrict in class JexlEngine
        Returns:
        true if strict, false otherwise
      • jxlt

        protected TemplateEngine jxlt()
        Gets and/or creates a default template engine.
        Returns:
        a template engine
      • newInstance

        public <T> T newInstance​(java.lang.Class<? extends T> clazz,
                                 java.lang.Object... args)
        Description copied from class: JexlEngine
        Creates a new instance of an object using the most appropriate constructor based on the arguments.
        Specified by:
        newInstance in class JexlEngine
        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 java.lang.Object newInstance​(java.lang.String clazz,
                                            java.lang.Object... args)
        Description copied from class: JexlEngine
        Creates a new instance of an object using the most appropriate constructor based on the arguments.
        Specified by:
        newInstance in class JexlEngine
        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
      • optionsSet

        public JexlOptions optionsSet​(JexlOptions opts)
        Sets options from this engine options.
        Parameters:
        opts - the options to set
        Returns:
        the options
      • parse

        protected ASTJexlScript parse​(JexlInfo info,
                                      boolean expr,
                                      java.lang.String src,
                                      Scope scope)
        Parses an expression.
        Parameters:
        info - information structure
        expr - whether we parse an expression or a feature
        src - the expression to parse
        scope - the script frame
        Returns:
        the parsed tree
        Throws:
        JexlException - if any error occurred during parsing
      • parse

        protected ASTJexlScript parse​(JexlInfo info,
                                      JexlFeatures parsingf,
                                      java.lang.String src,
                                      Scope scope)
        Parses an expression.
        Parameters:
        info - information structure
        parsingf - the set of parsing features
        src - the expression to parse
        scope - the script frame
        Returns:
        the parsed tree
        Throws:
        JexlException - if any error occurred during parsing
      • processPragmaModule

        private void processPragmaModule​(java.util.Map<java.lang.String,​java.lang.Object> ns,
                                         java.lang.String key,
                                         java.lang.Object value,
                                         JexlInfo info,
                                         JexlContext context)
        Processes jexl.module.ns pragma.

        If the value is empty, the namespace will be cleared which may be useful to debug and force unload the object bound to the namespace.

        Parameters:
        ns - the namespace map
        key - the key the namespace
        value - the value, ie the expression to evaluate and its result bound to the namespace
        info - the expression info
        context - the value-as-expression evaluation context
      • processPragmaNamespace

        private void processPragmaNamespace​(java.util.Map<java.lang.String,​java.lang.Object> ns,
                                            java.lang.String key,
                                            java.lang.Object value)
        Processes jexl.namespace.ns pragma.
        Parameters:
        ns - the namespace map
        key - the key
        value - the value, ie the class
      • processPragmas

        protected void processPragmas​(ASTJexlScript script,
                                      JexlContext context,
                                      JexlOptions opts)
        Processes a script pragmas.

        Only called from options(...)

        Parameters:
        script - the script
        context - the context
        opts - the options
      • putThreadEngine

        protected JexlEngine putThreadEngine​(JexlEngine jexl)
        Swaps the current thread local engine.
        Parameters:
        jexl - the engine or null
        Returns:
        the previous thread local engine
      • setClassLoader

        public void setClassLoader​(java.lang.ClassLoader loader)
        Description copied from class: JexlEngine
        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.

        Specified by:
        setClassLoader in class JexlEngine
        Parameters:
        loader - the class loader to use
      • setProperty

        public void setProperty​(JexlContext context,
                                java.lang.Object bean,
                                java.lang.String expr,
                                java.lang.Object value)
        Description copied from class: JexlEngine
        Assign properties of a bean using an expression.

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

        Specified by:
        setProperty in class JexlEngine
        Parameters:
        context - the evaluation context
        bean - the bean to set properties in
        expr - the property expression
        value - the value of the property
      • setProperty

        public void setProperty​(java.lang.Object bean,
                                java.lang.String expr,
                                java.lang.Object value)
        Description copied from class: JexlEngine
        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.

        Specified by:
        setProperty in class JexlEngine
        Parameters:
        bean - the bean to set properties in
        expr - the property expression
        value - the value of the property
      • trimSource

        protected java.lang.String trimSource​(java.lang.CharSequence str)
        Trims the source from front and ending spaces.
        Parameters:
        str - expression to clean
        Returns:
        trimmed expression ending in a semicolon
      • varCollector

        protected Engine.VarCollector varCollector()
        Creates a collector instance.
        Returns:
        a collector instance
      • withValueSet

        private void withValueSet​(java.lang.Object value,
                                  java.util.function.Consumer<java.lang.Object> consumer)
        Utility to deal with single value or set of values.
        Parameters:
        value - the value or the set
        consumer - the consumer of values