Package org.apache.commons.jexl3.internal

Class Engine

java.lang.Object
org.apache.commons.jexl3.JexlEngine
org.apache.commons.jexl3.internal.Engine
Direct Known Subclasses:
Engine32
public class Engine extends JexlEngine
A JexlEngine implementation.
Since:
2.0

  • Field Details

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

    • arithmetic

      protected final JexlArithmetic arithmetic
      The JexlArithmetic instance.

    • functions

      protected final Map<String,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 Charset charset
      The default charset.

    • parsing

      protected final 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.

    • cache

      protected final SoftCache<Source,ASTJexlScript> cache
      The expression 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.

    • PROPERTY_FEATURES

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

  • Constructor Details

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

    • 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

    • getUberspect

      @Deprecated public static Uberspect getUberspect(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy)
      Deprecated.
      3.3
      Use getUberspect(Log, JexlUberspect.ResolverStrategy, JexlPermissions).
      Parameters:
      logger - the logger
      strategy - the strategy
      Returns:
      an Uberspect instance

    • getUberspect

      public JexlUberspect getUberspect()
      Description copied from class: JexlEngine
      Gets this engine underlying JexlUberspect.
      Specified by:
      getUberspect in class JexlEngine
      Returns:
      the uberspect

    • getArithmetic

      public JexlArithmetic getArithmetic()
      Description copied from class: JexlEngine
      Gets this engine underlying JexlArithmetic.
      Specified by:
      getArithmetic in class JexlEngine
      Returns:
      the arithmetic

    • 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

    • 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

    • setClassLoader

      public void setClassLoader(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

    • getCharset

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

    • getNamespace

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

    • 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

    • 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

    • 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

    • 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

    • withValueSet

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

    • processPragmaNamespace

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

    • processPragmaModule

      private void processPragmaModule(Map<String,Object> ns, String key, 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

    • optionsSet

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

    • 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

    • clearCache

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

    • 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

    • createTemplateInterpreter

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

    • createExpression

      public Script createExpression(JexlInfo info, 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

    • createScript

      public Script createScript(JexlFeatures features, JexlInfo info, String scriptText, 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

    • getProperty

      public Object getProperty(Object bean, 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

    • getProperty

      public Object getProperty(JexlContext context, Object bean, 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

    • setProperty

      public void setProperty(Object bean, String expr, 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

    • setProperty

      public void setProperty(JexlContext context, Object bean, String expr, 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

    • invokeMethod

      public Object invokeMethod(Object obj, String meth, 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

    • newInstance

      public <T> T newInstance(Class<? extends T> clazz, 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 Object newInstance(String clazz, 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

    • doCreateInstance

      protected Object doCreateInstance(Object clazz, 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

    • putThreadLocal

      protected JexlContext.ThreadLocal putThreadLocal(JexlContext.ThreadLocal tls)
      Swaps the current thread local context.
      Parameters:
      tls - the context or null
      Returns:
      the previous thread local context

    • putThreadEngine

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

    • getVariables

      protected Set<List<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

    • varCollector

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

    • 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

    • getParameters

      protected 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

    • getLocalVariables

      protected 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

    • parse

      protected ASTJexlScript parse(JexlInfo info, boolean expr, 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, 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

    • trimSource

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

    • jxlt

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