Class ELEvaluator


  • public class ELEvaluator
    extends java.lang.Object

    This is the main class for evaluating expression Strings. An expression String is a String that may contain expressions of the form ${...}. Multiple expressions may appear in the same expression String. In such a case, the expression String's value is computed by concatenating the String values of those evaluated expressions and any intervening non-expression text, then converting the resulting String to the expected type using the PropertyEditor mechanism.

    In the special case where the expression String is a single expression, the value of the expression String is determined by evaluating the expression, without any intervening conversion to a String.

    The evaluator maintains a cache mapping expression Strings to their parsed results. For expression Strings containing no expression elements, it maintains a cache mapping ExpectedType/ExpressionString to parsed value, so that static expression Strings won't have to go through a conversion step every time they are used. All instances of the evaluator share the same cache. The cache may be bypassed by setting a flag on the evaluator's constructor.

    The evaluator must be passed a VariableResolver in its constructor. The VariableResolver is used to resolve variable names encountered in expressions, and can also be used to implement "implicit objects" that are always present in the namespace. Different applications will have different policies for variable lookups and implicit objects - these differences can be encapsulated in the VariableResolver passed to the evaluator's constructor.

    Most VariableResolvers will need to perform their resolution against some context. For example, a JSP environment needs a PageContext to resolve variables. The evaluate() method takes a generic Object context which is eventually passed to the VariableResolver - the VariableResolver is responsible for casting the context to the proper type.

    Once an evaluator instance has been constructed, it may be used multiple times, and may be used by multiple simultaneous Threads. In other words, an evaluator instance is well-suited for use as a singleton.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.String EXPR_CACHE_PARAM
      Name of configuration setting for maximum number of entries in the cached expression string map
      private static int MAX_SIZE
      Default maximum cache size
      (package private) boolean mBypassCache
      Flag if the cache should be bypassed *
      (package private) VariableResolver mResolver
      The VariableResolver *
      (package private) javax.servlet.jsp.PageContext pageContext
      The PageContext *
      (package private) static java.util.Map sCachedExpectedTypes
      The mapping from ExpectedType to Maps mapping literal String to parsed value *
      (package private) static java.util.Map sCachedExpressionStrings
      The mapping from expression String to its parsed form (String, Expression, or ExpressionString)
      (package private) static Logger sLogger
      The static Logger *
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static java.lang.String addEscapes​(java.lang.String str)
      Used to convert raw characters to their escaped version when these raw version cannot be used as part of an ASCII string literal.
      (package private) java.lang.Object convertStaticValueToExpectedType​(java.lang.String pValue, java.lang.Class pExpectedType, Logger pLogger)
      Converts the given String, specified as a static expression string, to the given expected type.
      (package private) java.lang.Object convertToExpectedType​(java.lang.Object pValue, java.lang.Class pExpectedType, Logger pLogger)
      Converts the given value to the specified expected type.
      private void createExpressionStringMap()
      Creates LRU map of expression strings.
      java.lang.Object evaluate​(java.lang.String pExpressionString, java.lang.Object pContext, java.lang.Class pExpectedType, java.util.Map functions, java.lang.String defaultPrefix)
      Evaluates the given expression String
      (package private) java.lang.Object evaluate​(java.lang.String pExpressionString, java.lang.Object pContext, java.lang.Class pExpectedType, java.util.Map functions, java.lang.String defaultPrefix, Logger pLogger)
      Evaluates the given expression string
      (package private) static java.lang.String formatParseException​(java.lang.String pExpressionString, ParseException pExc)
      Formats a ParseException into an error message suitable for displaying on a web page
      (package private) static java.util.Map getOrCreateExpectedTypeMap​(java.lang.Class pExpectedType)
      Creates or returns the Map that maps string literals to parsed values for the specified expected type.
      java.lang.String parseAndRender​(java.lang.String pExpressionString)
      Parses the given expression string, then converts it back to a String in its canonical form.
      java.lang.Object parseExpressionString​(java.lang.String pExpressionString)
      Gets the parsed form of the given expression string.
      void setBypassCache​(boolean pBypassCache)
      Enable cache bypass
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • EXPR_CACHE_PARAM

        private static final java.lang.String EXPR_CACHE_PARAM
        Name of configuration setting for maximum number of entries in the cached expression string map
        See Also:
        Constant Field Values
      • sCachedExpressionStrings

        static java.util.Map sCachedExpressionStrings
        The mapping from expression String to its parsed form (String, Expression, or ExpressionString)

        Using LRU Map with a maximum capacity to avoid out of bound map growth.

        NOTE: use LinkedHashmap if a dependency on J2SE 1.4+ is ok

      • sCachedExpectedTypes

        static java.util.Map sCachedExpectedTypes
        The mapping from ExpectedType to Maps mapping literal String to parsed value *
      • sLogger

        static Logger sLogger
        The static Logger *
      • mBypassCache

        boolean mBypassCache
        Flag if the cache should be bypassed *
      • pageContext

        javax.servlet.jsp.PageContext pageContext
        The PageContext *
    • Constructor Detail

      • ELEvaluator

        public ELEvaluator​(VariableResolver pResolver)
        Constructor
        Parameters:
        pResolver - the object that should be used to resolve variable names encountered in expressions. If null, all variable references will resolve to null.
    • Method Detail

      • setBypassCache

        public void setBypassCache​(boolean pBypassCache)
        Enable cache bypass
        Parameters:
        pBypassCache - flag indicating cache should be bypassed
      • evaluate

        public java.lang.Object evaluate​(java.lang.String pExpressionString,
                                         java.lang.Object pContext,
                                         java.lang.Class pExpectedType,
                                         java.util.Map functions,
                                         java.lang.String defaultPrefix)
                                  throws ELException
        Evaluates the given expression String
        Parameters:
        pExpressionString - the expression String to be evaluated
        pContext - the context passed to the VariableResolver for resolving variable names
        pExpectedType - the type to which the evaluated expression should be coerced
        Returns:
        the expression String evaluated to the given expected type
        Throws:
        ELException
      • evaluate

        java.lang.Object evaluate​(java.lang.String pExpressionString,
                                  java.lang.Object pContext,
                                  java.lang.Class pExpectedType,
                                  java.util.Map functions,
                                  java.lang.String defaultPrefix,
                                  Logger pLogger)
                           throws ELException
        Evaluates the given expression string
        Throws:
        ELException
      • parseExpressionString

        public java.lang.Object parseExpressionString​(java.lang.String pExpressionString)
                                               throws ELException
        Gets the parsed form of the given expression string. If the parsed form is cached (and caching is not bypassed), return the cached form, otherwise parse and cache the value. Returns either a String, Expression, or ExpressionString.
        Throws:
        ELException
      • convertToExpectedType

        java.lang.Object convertToExpectedType​(java.lang.Object pValue,
                                               java.lang.Class pExpectedType,
                                               Logger pLogger)
                                        throws ELException
        Converts the given value to the specified expected type.
        Throws:
        ELException
      • convertStaticValueToExpectedType

        java.lang.Object convertStaticValueToExpectedType​(java.lang.String pValue,
                                                          java.lang.Class pExpectedType,
                                                          Logger pLogger)
                                                   throws ELException
        Converts the given String, specified as a static expression string, to the given expected type. The conversion is cached.
        Throws:
        ELException
      • getOrCreateExpectedTypeMap

        static java.util.Map getOrCreateExpectedTypeMap​(java.lang.Class pExpectedType)
        Creates or returns the Map that maps string literals to parsed values for the specified expected type.
      • createExpressionStringMap

        private void createExpressionStringMap()
        Creates LRU map of expression strings. If context parameter specifying cache size is present use that as the maximum size of the LRU map otherwise use default.
      • formatParseException

        static java.lang.String formatParseException​(java.lang.String pExpressionString,
                                                     ParseException pExc)
        Formats a ParseException into an error message suitable for displaying on a web page
      • addEscapes

        static java.lang.String addEscapes​(java.lang.String str)
        Used to convert raw characters to their escaped version when these raw version cannot be used as part of an ASCII string literal.
      • parseAndRender

        public java.lang.String parseAndRender​(java.lang.String pExpressionString)
                                        throws ELException
        Parses the given expression string, then converts it back to a String in its canonical form. This is used to test parsing.
        Throws:
        ELException