Class InterpreterBase

  • Direct Known Subclasses:
    Interpreter

    public abstract class InterpreterBase
    extends ParserVisitor
    The helper base of an interpreter of JEXL syntax.
    Since:
    3.0
    • Field Detail

      • EMPTY_PARAMS

        protected static final java.lang.Object[] EMPTY_PARAMS
        Empty parameters for method matching.
      • jexl

        protected final Engine jexl
        The JEXL engine.
      • logger

        protected final org.apache.commons.logging.Log logger
        The logger.
      • uberspect

        protected final JexlUberspect uberspect
        The uberspect.
      • arithmetic

        protected final JexlArithmetic arithmetic
        The arithmetic handler.
      • context

        protected final JexlContext context
        The context to store/retrieve variables.
      • options

        protected final JexlOptions options
        The options.
      • cache

        protected final boolean cache
        Cache executors.
      • cancelled

        protected final java.util.concurrent.atomic.AtomicBoolean cancelled
        Cancellation support.
      • operators

        protected final Operators operators
        The operators evaluation delegate.
      • functions

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

        protected java.util.Map<java.lang.String,​java.lang.Object> functors
        The map of dynamically created namespaces, NamespaceFunctor or duck-types of those.
    • Constructor Detail

      • InterpreterBase

        protected InterpreterBase​(Engine engine,
                                  JexlOptions opts,
                                  JexlContext aContext)
        Creates an interpreter base.
        Parameters:
        engine - the engine creating this interpreter
        opts - the evaluation options
        aContext - the evaluation context
      • InterpreterBase

        protected InterpreterBase​(InterpreterBase ii,
                                  JexlArithmetic jexla)
        Copy constructor.
        Parameters:
        ii - the base to copy
        jexla - the arithmetic instance to use (or null)
    • Method Detail

      • stringifyPropertyValue

        protected static java.lang.String stringifyPropertyValue​(JexlNode node)
        Pretty-prints a failing property value (de)reference.

        Used by calls to unsolvableProperty(...).

        Parameters:
        node - the property node
        Returns:
        the (pretty) string value
      • annotationError

        protected java.lang.Object annotationError​(JexlNode node,
                                                   java.lang.String annotation,
                                                   java.lang.Throwable cause)
        Triggered when an annotation processing fails.
        Parameters:
        node - the node where the error originated from
        annotation - the annotation name
        cause - the cause of error (if any)
        Returns:
        throws a JexlException if strict and not silent, null otherwise
      • callArguments

        protected java.lang.Object[] callArguments​(java.lang.Object target,
                                                   boolean narrow,
                                                   java.lang.Object[] args)
        Concatenate arguments in call(...).
        Parameters:
        target - the pseudo-method owner, first to-be argument
        narrow - whether we should attempt to narrow number arguments
        args - the other (non-null) arguments
        Returns:
        the arguments array
      • cancel

        protected boolean cancel()
        Cancels this evaluation, setting the cancel flag that will result in a JexlException.Cancel to be thrown.
        Returns:
        false if already cancelled, true otherwise
      • cancelCheck

        protected void cancelCheck​(JexlNode node)
        Throws a JexlException.Cancel if script execution was cancelled.
        Parameters:
        node - the node being evaluated
      • closeIfSupported

        protected void closeIfSupported​(java.lang.Object closeable)
        Attempt to call close() if supported.

        This is used when dealing with auto-closeable (duck-like) objects

        Parameters:
        closeable - the object we'd like to close
      • closeIfSupported

        protected void closeIfSupported​(java.util.Queue<java.lang.Object> closeables)
        Attempt to call close() if supported.

        This is used when dealing with auto-closeable (duck-like) objects

        Parameters:
        closeables - the object queue we'd like to close
      • constVariable

        protected java.lang.Object constVariable​(JexlNode node,
                                                 java.lang.String var)
        Triggered when a captured variable is const and assignment is attempted.
        Parameters:
        node - the node where the error originated from
        var - the variable name
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • defineVariable

        protected boolean defineVariable​(ASTVar var,
                                         LexicalFrame frame)
        Defines a variable.
        Parameters:
        var - the variable to define
        frame - the frame in which it will be defined
        Returns:
        true if definition succeeded, false otherwise
      • findNullOperand

        protected JexlNode findNullOperand​(JexlNode node,
                                           java.lang.Object left,
                                           java.lang.Object right)
        Finds the node causing a NPE for diadic operators.
        Parameters:
        node - the parent node
        left - the left argument
        right - the right argument
        Returns:
        the left, right or parent node
      • findNullOperand

        @Deprecated
        protected JexlNode findNullOperand​(java.lang.RuntimeException xrt,
                                           JexlNode node,
                                           java.lang.Object left,
                                           java.lang.Object right)
        Deprecated.
      • functionArgument

        protected java.lang.Object functionArgument​(boolean narrow,
                                                    java.lang.Object arg)
        Optionally narrows an argument for a function call.
        Parameters:
        narrow - whether narrowing should occur
        arg - the argument
        Returns:
        the narrowed argument
      • functionArguments

        protected java.lang.Object[] functionArguments​(java.lang.Object target,
                                                       boolean narrow,
                                                       java.lang.Object[] args)
        Concatenate arguments in call(...).

        When target == context, we are dealing with a global namespace function call

        Parameters:
        target - the pseudo-method owner, first to-be argument
        narrow - whether we should attempt to narrow number arguments
        args - the other (non-null) arguments
        Returns:
        the arguments array
      • getAttribute

        protected java.lang.Object getAttribute​(java.lang.Object object,
                                                java.lang.Object attribute,
                                                JexlNode node)
        Gets an attribute of an object.
        Parameters:
        object - to retrieve value from
        attribute - the attribute of the object, e.g. an index (1, 0, 2) or key for a map
        node - the node that evaluated as the object
        Returns:
        the attribute value
      • getVariable

        protected java.lang.Object getVariable​(Frame frame,
                                               LexicalScope block,
                                               ASTIdentifier identifier)
        Gets a value of a defined local variable or from the context.
        Parameters:
        frame - the local frame
        block - the lexical block if any
        identifier - the variable node
        Returns:
        the value
      • invocationException

        protected JexlException invocationException​(JexlNode node,
                                                    java.lang.String methodName,
                                                    java.lang.Throwable xany)
        Triggered when method, function or constructor invocation fails with an exception.
        Parameters:
        node - the node triggering the exception
        methodName - the method/function name
        xany - the cause
        Returns:
        a JexlException that will be thrown
      • isCancellable

        protected boolean isCancellable()
        Returns:
        true if interrupt throws a JexlException.Cancel.
      • isCancelled

        protected boolean isCancelled()
        Checks whether this interpreter execution was cancelled due to thread interruption.
        Returns:
        true if cancelled, false otherwise
      • isSafe

        protected boolean isSafe()
        Whether this interpreter ignores null in navigation expression as errors.
        Returns:
        true if safe, false otherwise
      • isSilent

        protected boolean isSilent()
        Whether this interpreter is currently evaluating with a silent mode.
        Returns:
        true if silent, false otherwise
      • isStrictEngine

        protected boolean isStrictEngine()
        Whether this interpreter is currently evaluating with a strict engine flag.
        Returns:
        true if strict engine, false otherwise
      • isStrictOperand

        protected boolean isStrictOperand​(JexlNode node)
        Parameters:
        node - the operand node
        Returns:
        true if this node is an operand of a strict operator, false otherwise
      • isTernaryProtected

        protected boolean isTernaryProtected​(JexlNode startNode)
        Check if a null evaluated expression is protected by a ternary expression.

        The rationale is that the ternary / elvis expressions are meant for the user to explicitly take control over the error generation; ie, ternaries can return null even if the engine in strict mode would normally throw an exception.

        Returns:
        true if nullable variable, false otherwise
      • isVariableDefined

        protected boolean isVariableDefined​(Frame frame,
                                            LexicalScope block,
                                            java.lang.String name)
        Checks whether a variable is defined.

        The var may be either a local variable declared in the frame and visible from the block or defined in the context.

        Parameters:
        frame - the frame
        block - the block
        name - the variable name
        Returns:
        true if variable is defined, false otherwise
      • operatorError

        protected java.lang.Object operatorError​(JexlNode node,
                                                 JexlOperator operator,
                                                 java.lang.Throwable cause)
        Triggered when an operator fails.
        Parameters:
        node - the node where the error originated from
        operator - the method name
        cause - the cause of error (if any)
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • redefinedVariable

        protected java.lang.Object redefinedVariable​(JexlNode node,
                                                     java.lang.String var)
        Triggered when a variable is lexically known as being redefined.
        Parameters:
        node - the node where the error originated from
        var - the variable name
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • resolveNamespace

        protected java.lang.Object resolveNamespace​(java.lang.String prefix,
                                                    JexlNode node)
        Resolves a namespace, eventually allocating an instance using context as constructor argument.

        The lifetime of such instances span the current expression or script evaluation.

        Parameters:
        prefix - the prefix name (can be null for global namespace)
        node - the AST node
        Returns:
        the namespace instance
      • setAttribute

        protected void setAttribute​(java.lang.Object object,
                                    java.lang.Object attribute,
                                    java.lang.Object value,
                                    JexlNode node)
        Sets an attribute of an object.
        Parameters:
        object - to set the value to
        attribute - the attribute of the object, e.g. an index (1, 0, 2) or key for a map
        value - the value to assign to the object's attribute
        node - the node that evaluated as the object
      • setContextVariable

        protected void setContextVariable​(JexlNode node,
                                          java.lang.String name,
                                          java.lang.Object value)
        Sets a variable in the global context.

        If interpretation applies lexical shade, the variable must exist (ie the context has(...) method returns true) otherwise an error occurs.

        Parameters:
        node - the node
        name - the variable name
        value - the variable value
      • stringifyProperty

        protected java.lang.String stringifyProperty​(JexlNode node)
        Pretty-prints a failing property (de)reference.

        Used by calls to unsolvableProperty(...).

        Parameters:
        node - the property node
        Returns:
        the (pretty) string
      • undefinedVariable

        protected java.lang.Object undefinedVariable​(JexlNode node,
                                                     java.lang.String var)
        Triggered when a variable is lexically known as undefined.
        Parameters:
        node - the node where the error originated from
        var - the variable name
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • unsolvableMethod

        protected java.lang.Object unsolvableMethod​(JexlNode node,
                                                    java.lang.String method)
        Triggered when a method can not be resolved.
        Parameters:
        node - the node where the error originated from
        method - the method name
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • unsolvableMethod

        protected java.lang.Object unsolvableMethod​(JexlNode node,
                                                    java.lang.String method,
                                                    java.lang.Object[] args)
        Triggered when a method can not be resolved.
        Parameters:
        node - the node where the error originated from
        method - the method name
        args - the method arguments
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • unsolvableProperty

        protected java.lang.Object unsolvableProperty​(JexlNode node,
                                                      java.lang.String property,
                                                      boolean undef,
                                                      java.lang.Throwable cause)
        Triggered when a property can not be resolved.
        Parameters:
        node - the node where the error originated from
        property - the property node
        cause - the cause if any
        undef - whether the property is undefined or null
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • unsolvableVariable

        protected java.lang.Object unsolvableVariable​(JexlNode node,
                                                      java.lang.String var,
                                                      boolean undef)
        Triggered when a variable can not be resolved.
        Parameters:
        node - the node where the error originated from
        var - the variable name
        undef - whether the variable is undefined or null
        Returns:
        throws JexlException if strict and not silent, null otherwise
      • variableError

        protected java.lang.Object variableError​(JexlNode node,
                                                 java.lang.String var,
                                                 JexlException.VariableIssue issue)
        Triggered when a variable generates an issue.
        Parameters:
        node - the node where the error originated from
        var - the variable name
        issue - the issue type
        Returns:
        throws JexlException if strict and not silent, null otherwise