org.apache.commons.jexl3.internal

## Class Engine

- java.lang.Object
- - org.apache.commons.jexl3.JexlEngine
  - - org.apache.commons.jexl3.internal.Engine

-     public class Engine
      extends JexlEngine

  A JexlEngine implementation.
  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `Engine.SoftCache<K,V>` A soft referenced cache.
    `protected static class` | `Engine.VarCollector` Utility class to collect variables.

    - ### Nested classes/interfaces inherited from class org.apache.commons.jexl3.JexlEngine

      `JexlEngine.Options`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected JexlArithmetic` | `arithmetic` The `JexlArithmetic` instance.
    `protected Engine.SoftCache<String,ASTJexlScript>` | `cache` The expression cache.
    `protected int` | `cacheThreshold` The expression max length to hit the cache.
    `protected Charset` | `charset` The default charset.
    `protected boolean` | `debug` Whether error messages will carry debugging information.
    `protected Map<String,Object>` | `functions` The map of 'prefix:function' to object implementing the namespaces.
    `protected TemplateEngine` | `jxlt` The default jxlt engine.
    `protected org.apache.commons.logging.Log` | `logger` The Log to which all JexlEngine messages will be logged.
    `protected Parser` | `parser` The `Parser`; when parsing expressions, this engine synchronizes on the parser.
    `protected boolean` | `silent` Whether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors.
    `protected boolean` | `strict` Whether this engine considers unknown variables, methods and constructors as errors.
    `protected JexlUberspect` | `uberspect` The JexlUberspect instance.

    - ### Fields inherited from class org.apache.commons.jexl3.JexlEngine

      `CONTEXT, EMPTY_CONTEXT, EMPTY_NS, TRY_FAILED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Engine()` Creates an engine with default arguments.
    `Engine(JexlBuilder conf)` Creates a JEXL engine using the provided `JexlBuilder`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearCache()` Clears the expression cache.
    `protected <K,V> Map<K,V>` | `createCache(int cacheSize)` Creates a cache.
    `Script` | `createExpression(JexlInfo info, String expression)` Creates an JexlExpression from a String containing valid JEXL syntax.
    `protected Interpreter` | `createInterpreter(JexlContext context, Scope.Frame frame)` Creates an interpreter.
    `TemplateEngine` | `createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred)` Creates a new instance of `JxltEngine` using this engine.
    `Script` | `createScript(JexlInfo info, String scriptText, String[] names)` Creates a JexlScript from a String containing valid JEXL syntax.
    `protected Object` | `doCreateInstance(Object clazz, Object... args)` Creates a new instance of an object using the most appropriate constructor based on the arguments.
    `JexlArithmetic` | `getArithmetic()` Gets this engine underlying `JexlArithmetic`.
    `Charset` | `getCharset()` Gets the charset used for parsing.
    `protected String[]` | `getLocalVariables(JexlScript script)` Gets the array of local variable from a script.
    `protected String[]` | `getParameters(JexlScript script)` Gets the array of parameters from a script.
    `Object` | `getProperty(JexlContext context, Object bean, String expr)` Accesses properties of a bean using an expression.
    `Object` | `getProperty(Object bean, String expr)` Accesses properties of a bean using an expression.
    `JexlUberspect` | `getUberspect()` Gets this engine underlying `JexlUberspect`.
    `static Uberspect` | `getUberspect(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy)` Gets the default instance of Uberspect.
    `protected Set<List<String>>` | `getVariables(ASTJexlScript script)` Gets the list of variables accessed by a script.
    `protected void` | `getVariables(ASTJexlScript script, JexlNode node, Engine.VarCollector collector)` Fills up the list of variables accessed by a node.
    `Object` | `invokeMethod(Object obj, String meth, Object... args)` Invokes an object's method by name and arguments.
    `boolean` | `isDebug()` Checks whether this engine is in debug mode.
    `boolean` | `isSilent()` Checks whether this engine throws JexlException during evaluation.
    `boolean` | `isStrict()` Checks whether the engine considers unknown variables, methods, functions and constructors as errors.
    `protected TemplateEngine` | `jxlt()` Gets and/or creates a default template engine.
    `<T> T` | `newInstance(Class<? extends T> clazz, Object... args)` Creates a new instance of an object using the most appropriate constructor based on the arguments.
    `Object` | `newInstance(String clazz, Object... args)` Creates a new instance of an object using the most appropriate constructor based on the arguments.
    `protected ASTJexlScript` | `parse(JexlInfo info, String src, Scope scope, boolean registers, boolean expression)` Parses an expression.
    `protected JexlContext.ThreadLocal` | `putThreadLocal(JexlContext.ThreadLocal tls)` Swaps the current thread local context.
    `void` | `setClassLoader(ClassLoader loader)` Sets the class loader used to discover classes in 'new' expressions.
    `void` | `setProperty(JexlContext context, Object bean, String expr, Object value)` Assign properties of a bean using an expression.
    `void` | `setProperty(Object bean, String expr, Object value)` Assign properties of a bean using an expression.
    `protected String` | `trimSource(CharSequence str)` Trims the source from front and ending spaces.

    - ### Methods inherited from class org.apache.commons.jexl3.JexlEngine

      `createExpression, createInfo, createInfo, createJxltEngine, createJxltEngine, createScript, createScript, createScript, createScript, createScript, createScript, createScript, createScript, getThreadContext, readSource, readSource, setThreadContext, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### uberspect

          protected final JexlUberspect uberspect

      The JexlUberspect instance.

    - #### arithmetic

          protected final JexlArithmetic arithmetic

      The `JexlArithmetic` instance.

    - #### logger

          protected final org.apache.commons.logging.Log logger

      The Log to which all JexlEngine messages will be logged.

    - #### parser

          protected final Parser parser

      The `Parser`; when parsing expressions, this engine synchronizes on the parser.

    - #### strict

          protected final boolean strict

      Whether this engine considers unknown variables, methods and constructors 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.

    - #### debug

          protected final boolean debug

      Whether error messages will carry debugging information.

    - #### functions

          protected final Map<String,Object> functions

      The map of 'prefix:function' to object implementing the namespaces.

    - #### cache

          protected final Engine.SoftCache<String,ASTJexlScript> cache

      The expression cache.

    - #### cacheThreshold

          protected final int cacheThreshold

      The expression max length to hit the cache.

    - #### charset

          protected final Charset charset

      The default charset.

    - #### jxlt

          protected volatile TemplateEngine jxlt

      The default jxlt engine.

  - ### 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)

      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.

      Parameters:
        `logger` - the logger to use for the underlying Uberspect
        `strategy` - the property resolver strategy
      Returns:
        Uberspect the default uberspector 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 the engine considers unknown variables, methods, functions and constructors as errors.
      Specified by:
        `isStrict` in class `JexlEngine`
      Returns:
        true if strict, 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 should be called as an optional step of the JexlEngine initialization code before expression creation & evaluation.

      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

    - #### 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

    - #### 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

    - #### createCache

          protected <K,V> Map<K,V> createCache(int cacheSize)

      Creates a cache.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `cacheSize` - the cache size, must be > 0
      Returns:
        a Map usable as a cache bounded to the given size

    - #### 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,
                                      Scope.Frame frame)

      Creates an interpreter.
      Parameters:
        `context` - a JexlContext; if null, the empty context is used instead.
        `frame` - the interpreter frame
      Returns:
        an Interpreter

    - #### createScript

          public Script createScript(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:
        `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`

    - #### 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`

    - #### 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

    - #### 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

    - #### 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,
                            String src,
                            Scope scope,
                            boolean registers,
                            boolean expression)

      Parses an expression.
      Parameters:
        `info` - information structure
        `src` - the expression to parse
        `scope` - the script frame
        `registers` - whether the parser should allow the unnamed '#number' syntax for 'registers'
        `expression` - whether the parser allows scripts or only expressions
      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 semi-colon

    - #### jxlt

          protected TemplateEngine jxlt()

      Gets and/or creates a default template engine.
      Returns:
        a template engine

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.