Package org.apache.commons.jexl3

Class JexlEngine

java.lang.Object
org.apache.commons.jexl3.JexlEngine
public abstract class JexlEngine extends Object
Creates and evaluates JexlExpression and JexlScript objects. Determines the behavior of expressions and scripts during their evaluation with respect to:

Note that methods that evaluate expressions may throw unchecked exceptions; The JexlException are thrown in "non-silent" mode but since these are RuntimeException, user-code should catch them wherever most appropriate.

Since:
2.0

  • Field Details

  • Constructor Details

  • Method Details

    • getThreadContext

      public static JexlContext.ThreadLocal getThreadContext()
      Accesses the current thread local context.
      Returns:
      the context or null

    • getThreadEngine

      public static JexlEngine getThreadEngine()
      Accesses the current thread local engine.

      Advanced: you should only use this to retrieve the engine within a method/ctor called through the evaluation of a script/expression.

      Returns:
      the engine or null

    • setThreadContext

      public static void setThreadContext(JexlContext.ThreadLocal tls)
      Sets the current thread local context.

      This should only be used carefully, for instance when re-evaluating a "stored" script that requires a given Namespace resolver. Remember to synchronize access if context is shared between threads.

      Parameters:
      tls - the thread local context to set

    • toString

      protected static String toString(BufferedReader reader) throws IOException
      Creates a string from a reader.
      Parameters:
      reader - to be read.
      Returns:
      the contents of the reader as a String.
      Throws:
      IOException - on any error reading the reader.

    • clearCache

      public abstract void clearCache()
      Clears the expression cache.

    • createExpression

      public abstract JexlExpression createExpression(JexlInfo info, String expression)
      Creates an JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
      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
      Throws:
      JexlException - if there is a problem parsing the script

    • createExpression

      public final JexlExpression createExpression(String expression)
      Creates a JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
      Parameters:
      expression - A String containing valid JEXL syntax
      Returns:
      An JexlExpression which can be evaluated using a JexlContext
      Throws:
      JexlException - if there is a problem parsing the script

    • createInfo

      public JexlInfo createInfo()
      Create an information structure for dynamic set/get/invoke/new.

      This gathers the class, method and line number of the first calling method outside of o.a.c.jexl3.

      Returns:
      a JexlInfo instance

    • createInfo

      public JexlInfo createInfo(String fn, int l, int c)
      Creates a JexlInfo instance.
      Parameters:
      fn - url/file/template/script user given name
      l - line number
      c - column number
      Returns:
      a JexlInfo instance

    • createJxltEngine

      public JxltEngine createJxltEngine()
      Creates a new JxltEngine instance using this engine.
      Returns:
      a JEXL Template engine

    • createJxltEngine

      public JxltEngine createJxltEngine(boolean noScript)
      Creates a new JxltEngine instance using this engine.
      Parameters:
      noScript - whether the JxltEngine only allows Jexl expressions or scripts
      Returns:
      a JEXL Template engine

    • createJxltEngine

      public abstract JxltEngine createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred)
      Creates a new instance of JxltEngine using this engine.
      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

    • createScript

      public final JexlScript createScript(File scriptFile)
      Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
      Returns:
      A JexlScript which can be executed with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • createScript

      public final JexlScript createScript(File scriptFile, String... names)
      Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
      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 with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • createScript

      public abstract JexlScript createScript(JexlFeatures features, JexlInfo info, String source, String... names)
      Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      features - A set of features that will be enforced during parsing
      info - An info structure to carry debugging information if needed
      source - 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
      Throws:
      JexlException - if there is a problem parsing the script

    • createScript

      public final JexlScript createScript(JexlInfo info, File scriptFile, String... names)
      Creates a Script from a File containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      info - An info structure to carry debugging information if needed
      scriptFile - A File containing valid JEXL syntax. Must not be null. Must be a readable file.
      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 with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • createScript

      public final JexlScript createScript(JexlInfo info, String source, String... names)
      Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      info - An info structure to carry debugging information if needed
      source - 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
      Throws:
      JexlException - if there is a problem parsing the script

    • createScript

      public final JexlScript createScript(JexlInfo info, URL scriptUrl, String... names)
      Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      info - An info structure to carry debugging information if needed
      scriptUrl - A URL containing valid JEXL syntax. Must not be null.
      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 with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • createScript

      public final JexlScript createScript(String scriptText)
      Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      scriptText - A String containing valid JEXL syntax
      Returns:
      A JexlScript which can be executed using a JexlContext
      Throws:
      JexlException - if there is a problem parsing the script.

    • createScript

      public final JexlScript createScript(String source, String... names)
      Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      source - 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
      Throws:
      JexlException - if there is a problem parsing the script

    • createScript

      public final JexlScript createScript(URL scriptUrl)
      Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      scriptUrl - A URL containing valid JEXL syntax. Must not be null.
      Returns:
      A JexlScript which can be executed with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • createScript

      public final JexlScript createScript(URL scriptUrl, String... names)
      Creates a Script from a URL containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
      scriptUrl - A URL containing valid JEXL syntax. Must not be null.
      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 with a JexlContext.
      Throws:
      JexlException - if there is a problem reading or parsing the script.

    • getArithmetic

      public abstract JexlArithmetic getArithmetic()
      Gets this engine underlying JexlArithmetic.
      Returns:
      the arithmetic

    • getCharset

      public abstract Charset getCharset()
      Gets the charset used for parsing.
      Returns:
      the charset

    • getProperty

      public abstract Object getProperty(JexlContext context, Object bean, String expr)
      Accesses properties of a bean using an expression.

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

      Parameters:
      context - the evaluation context
      bean - the bean to get properties from
      expr - the property expression
      Returns:
      the value of the property
      Throws:
      JexlException - if there is an error parsing the expression or during evaluation

    • getProperty

      public abstract Object getProperty(Object bean, String expr)
      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.

      Parameters:
      bean - the bean to get properties from
      expr - the property expression
      Returns:
      the value of the property
      Throws:
      JexlException - if there is an error parsing the expression or during evaluation

    • getUberspect

      public abstract JexlUberspect getUberspect()
      Gets this engine underlying JexlUberspect.
      Returns:
      the uberspect

    • invokeMethod

      public abstract Object invokeMethod(Object obj, String meth, Object... args)
      Invokes an object's method by name and arguments.
      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
      Throws:
      JexlException - if method could not be found or failed and engine is not silent

    • isCancellable

      public abstract boolean isCancellable()
      Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
      Returns:
      true if cancellable, false otherwise

    • isDebug

      public abstract boolean isDebug()
      Checks whether this engine is in debug mode.
      Returns:
      true if debug is on, false otherwise

    • isSilent

      public abstract boolean isSilent()
      Checks whether this engine throws JexlException during evaluation.
      Returns:
      true if silent, false (default) otherwise

    • isStrict

      public abstract boolean isStrict()
      Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
      Returns:
      true if strict, false otherwise

    • newInstance

      public abstract <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.
      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 abstract Object newInstance(String clazz, Object... args)
      Creates a new instance of an object using the most appropriate constructor based on the arguments.
      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

    • readSource

      protected String readSource(File file)
      Reads a JEXL source from a File.
      Parameters:
      file - the script file
      Returns:
      the source

    • readSource

      protected String readSource(URL url)
      Reads a JEXL source from an URL.
      Parameters:
      url - the script url
      Returns:
      the source

    • setClassLoader

      public abstract void setClassLoader(ClassLoader loader)
      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.

      Parameters:
      loader - the class loader to use

    • setProperty

      public abstract void setProperty(JexlContext context, Object bean, String expr, Object value)
      Assign properties of a bean using an expression.

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

      Parameters:
      context - the evaluation context
      bean - the bean to set properties in
      expr - the property expression
      value - the value of the property
      Throws:
      JexlException - if there is an error parsing the expression or during evaluation

    • setProperty

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

      Parameters:
      bean - the bean to set properties in
      expr - the property expression
      value - the value of the property
      Throws:
      JexlException - if there is an error parsing the expression or during evaluation