Interface JxltEngine.Expression

  • All Known Implementing Classes:
    TemplateEngine.CompositeExpression, TemplateEngine.ConstantExpression, TemplateEngine.DeferredExpression, TemplateEngine.ImmediateExpression, TemplateEngine.JexlBasedExpression, TemplateEngine.NestedExpression, TemplateEngine.TemplateExpression
    Enclosing class:
    JxltEngine

    public static interface JxltEngine.Expression
    A unified expression that can mix immediate, deferred and nested sub-expressions as well as string constants;
    • The "immediate" syntax is of the form "...${jexl-expr}..."
    • The "deferred" syntax is of the form "...#{jexl-expr}..."
    • The "nested" syntax is of the form "...#{...${jexl-expr0}...}..."
    • The "composite" syntax is of the form "...${jexl-expr0}... #{jexl-expr1}..."

    Deferred and immediate expression carry different intentions:

    • An immediate expression indicate that evaluation is intended to be performed close to the definition/parsing point.
    • A deferred expression indicate that evaluation is intended to occur at a later stage.

    For instance: "Hello ${name}, now is #{time}" is a composite "deferred" expression since one of its subexpressions is deferred. Furthermore, this (composite) expression intent is to perform two evaluations; one close to its definition and another one in a later phase.

    The API reflects this feature in 2 methods, prepare and evaluate. The prepare method will evaluate the immediate subexpression and return an expression that contains only the deferred subexpressions (and constants), a prepared expression. Such a prepared expression is suitable for a later phase evaluation that may occur with a different JexlContext. Note that it is valid to call evaluate without prepare in which case the same JexlContext is used for the 2 evaluation phases.

    In the most common use-case where deferred expressions are to be kept around as properties of objects, one should createExpression and prepare an expression before storing it and evaluate it each time the property storing it is accessed.

    Note that nested expression use the JEXL syntax as in:

    "#{${bar}+'.charAt(2)'}"

    The most common mistake leading to an invalid expression being the following:

    "#{${bar}charAt(2)}"

    Also note that methods that createExpression evaluate expressions may throw unchecked exceptions; The JxltEngine.Exception are thrown when the engine instance is in "non-silent" mode but since these are RuntimeException, user-code should catch them where appropriate.

    Since:
    2.0
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String asString()
      Generates this expression's string representation.
      java.lang.StringBuilder asString​(java.lang.StringBuilder strb)
      Adds this expression's string representation to a StringBuilder.
      java.lang.Object evaluate​(JexlContext context)
      Evaluates this expression.
      JxltEngine.Expression getSource()
      Retrieves this expression's source expression.
      java.util.Set<java.util.List<java.lang.String>> getVariables()
      Gets the list of variables accessed by this expression.
      boolean isDeferred()
      Checks whether this expression is deferred.
      boolean isImmediate()
      Checks whether this expression is immediate.
      JxltEngine.Expression prepare​(JexlContext context)
      Evaluates the immediate sub-expressions.
      java.lang.String toString()
      Formats this expression, adding its source string representation in comments if available: 'expression /*= source *\/'' .
    • Method Detail

      • asString

        java.lang.String asString()
        Generates this expression's string representation.
        Returns:
        the string representation
      • asString

        java.lang.StringBuilder asString​(java.lang.StringBuilder strb)
        Adds this expression's string representation to a StringBuilder.
        Parameters:
        strb - the builder to fill
        Returns:
        the builder argument
      • evaluate

        java.lang.Object evaluate​(JexlContext context)
        Evaluates this expression.

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

        Parameters:
        context - the variable context
        Returns:
        the result of this expression evaluation or null if an error occurs and the JexlEngine is running in silent mode
        Throws:
        JxltEngine.Exception - if an error occurs and the JexlEngine is not silent
      • getSource

        JxltEngine.Expression getSource()
        Retrieves this expression's source expression.

        If this expression was prepared, this allows to retrieve the original expression that lead to it.

        Other expressions return themselves.

        Returns:
        the source expression
      • getVariables

        java.util.Set<java.util.List<java.lang.String>> getVariables()
        Gets the list of variables accessed by this expression.

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

        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
      • isDeferred

        boolean isDeferred()
        Checks whether this expression is deferred.
        Returns:
        true if deferred, false otherwise
      • isImmediate

        boolean isImmediate()
        Checks whether this expression is immediate.
        Returns:
        true if immediate, false otherwise
      • prepare

        JxltEngine.Expression prepare​(JexlContext context)
        Evaluates the immediate sub-expressions.

        When the expression is dependant upon immediate and deferred sub-expressions, evaluates the immediate sub-expressions with the context passed as parameter and returns this expression deferred form.

        In effect, this binds the result of the immediate sub-expressions evaluation in the context, allowing to differ evaluation of the remaining (deferred) expression within another context. This only has an effect to nested and composite expressions that contain differed and immediate sub-expressions.

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

        Parameters:
        context - the context to use for immediate expression evaluations
        Returns:
        an JxltEngine.Expression or null if an error occurs and the JexlEngine is running in silent mode
        Throws:
        JxltEngine.Exception - if an error occurs and the JexlEngine is not in silent mode
      • toString

        java.lang.String toString()
        Formats this expression, adding its source string representation in comments if available: 'expression /*= source *\/'' .
        Overrides:
        toString in class java.lang.Object
        Returns:
        the formatted expression string