Class JexlBuilder
- java.lang.Object
-
- org.apache.commons.jexl3.JexlBuilder
-
public class JexlBuilder extends java.lang.Object
Configures and builds a JexlEngine.The builder allow fine-tuning an engine instance behavior according to various control needs. Check
JexlBuilder()
for permission impacts starting with JEXL 3.3.Broad configurations elements are controlled through the features (
JexlFeatures
) that can restrict JEXL syntax - for instance, only expressions with no-side effects - and permissions (JexlPermissions
) that control the visible set of objects - for instance, avoiding access to any object in java.rmi.* -.Fine error control and runtime-overridable behaviors are implemented through options (
JexlOptions
). Most common flags accessible from the builder are reflected in its options (options()
).The
silent
flag tells the engine what to do with the error; when true, errors are logged as warning, when false, they throwJexlException
exceptions.The
strict
flag tells the engine when and if null as operand is considered an error. Thesafe
flog determines if safe-navigation is used. Safe-navigation allows an evaluation shortcut and return null in expressions that attempts dereferencing null, typically a method call or accessing a property.The
lexical
andlexicalShade
flags can be used to enforce a lexical scope for variables and parameters. ThelexicalShade
can be used to further ensure no global variable can be used with the same name as a local one even after it goes out of scope. The corresponding feature flags should be preferred since they will detect violations at parsing time. (seeJexlFeatures
)The following rules apply on silent and strict flags:
- When "silent" & "not-strict":
0 & null should be indicators of "default" values so that even in an case of error, something meaningful can still be inferred; may be convenient for configurations.
- When "silent" & "strict":
One should probably consider using null as an error case - ie, every object manipulated by JEXL should be valued; the ternary operator, especially the '?:' form can be used to workaround exceptional cases. Use case could be configuration with no implicit values or defaults.
- When "not-silent" & "not-strict":
The error control grain is roughly on par with JEXL 1.0
- When "not-silent" & "strict":
The finest error control grain is obtained; it is the closest to Java code - still augmented by "script" capabilities regarding automated conversions and type matching.
- When "silent" & "not-strict":
-
-
Field Summary
Fields Modifier and Type Field Description private JexlArithmetic
arithmetic
TheJexlArithmetic
instance.private int
cache
The cache size.protected static int
CACHE_THRESHOLD
The default maximum expression length to hit the expression cache.private java.util.function.IntFunction<JexlCache<?,?>>
cacheFactory
The cache class factory.private int
cacheThreshold
The maximum expression length to hit the expression cache.private java.lang.Boolean
cancellable
Whether interrupt throws JexlException.Cancel.private java.nio.charset.Charset
charset
The charset.private int
collectMode
Whether getVariables considers all potential equivalent syntactic forms.private java.lang.Boolean
debug
Whether error messages will carry debugging information.private JexlFeatures
features
The features.private java.lang.ClassLoader
loader
The class loader.private org.apache.commons.logging.Log
logger
The Log to which all JexlEngine messages will be logged.private JexlOptions
options
The options.private JexlPermissions
permissions
The set of permissions.private static JexlPermissions
PERMISSIONS
The set of default permissions used when creating a new builder.private JexlSandbox
sandbox
The sandbox.private int
stackOverflow
The stack overflow limit.private JexlUberspect.ResolverStrategy
strategy
TheJexlUberspect
resolver strategy.private JexlUberspect
uberspect
The JexlUberspect instance.
-
Constructor Summary
Constructors Constructor Description JexlBuilder()
Default constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
antish()
JexlBuilder
antish(boolean flag)
Sets whether the engine will resolve antish variable names.JexlArithmetic
arithmetic()
JexlBuilder
arithmetic(JexlArithmetic a)
Sets the JexlArithmetic instance the engine will use.int
cache()
JexlBuilder
cache(int size)
Sets the expression cache size the engine will use.java.util.function.IntFunction<JexlCache<?,?>>
cacheFactory()
JexlBuilder
cacheFactory(java.util.function.IntFunction<JexlCache<?,?>> factory)
Sets the expression cache size the engine will use.int
cacheThreshold()
JexlBuilder
cacheThreshold(int length)
Sets the maximum length for an expression to be cached.java.lang.Boolean
cancellable()
JexlBuilder
cancellable(boolean flag)
Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.java.nio.charset.Charset
charset()
JexlBuilder
charset(java.nio.charset.Charset arg)
Sets the charset to use.boolean
collectAll()
JexlBuilder
collectAll(boolean flag)
Sets whether the engine variable collectors considers all potential forms of variable syntaxes.int
collectMode()
JexlBuilder
collectMode(int mode)
Experimental collector mode setter.JexlEngine
create()
java.lang.Boolean
debug()
JexlBuilder
debug(boolean flag)
Sets whether the engine will report debugging information when error occurs.JexlFeatures
features()
JexlBuilder
features(JexlFeatures f)
Sets the features the engine will use as a base by default.java.util.Collection<java.lang.String>
imports()
Gets the optional set of imported packages.JexlBuilder
imports(java.lang.String... imports)
Sets the optional set of imports.JexlBuilder
imports(java.util.Collection<java.lang.String> imports)
Sets the optional set of imports.boolean
lexical()
JexlBuilder
lexical(boolean flag)
Sets whether the engine is in lexical mode.boolean
lexicalShade()
JexlBuilder
lexicalShade(boolean flag)
Sets whether the engine is in lexical shading mode.java.lang.ClassLoader
loader()
JexlBuilder
loader(java.lang.ClassLoader l)
Sets the class loader to use.JexlBuilder
loader(java.nio.charset.Charset arg)
Deprecated.since 3.1 usecharset(Charset)
insteadorg.apache.commons.logging.Log
logger()
JexlBuilder
logger(org.apache.commons.logging.Log log)
Sets the o.a.c.Log instance to use.java.util.Map<java.lang.String,java.lang.Object>
namespaces()
JexlBuilder
namespaces(java.util.Map<java.lang.String,java.lang.Object> ns)
Sets the default namespaces map the engine will use.JexlOptions
options()
JexlPermissions
permissions()
JexlBuilder
permissions(JexlPermissions p)
Sets the JexlPermissions instance the engine will use.java.lang.Boolean
safe()
JexlBuilder
safe(boolean flag)
Sets whether the engine considers dereferencing null in navigation expressions as null or triggers an error.JexlSandbox
sandbox()
JexlBuilder
sandbox(JexlSandbox box)
Sets the sandbox the engine will use.static void
setDefaultPermissions(JexlPermissions permissions)
Sets the default permissions.java.lang.Boolean
silent()
JexlBuilder
silent(boolean flag)
Sets whether the engine will throw JexlException during evaluation when an error is triggered.int
stackOverflow()
JexlBuilder
stackOverflow(int size)
Sets the number of script/expression evaluations that can be stacked.JexlUberspect.ResolverStrategy
strategy()
JexlBuilder
strategy(JexlUberspect.ResolverStrategy rs)
Sets the JexlUberspect strategy the engine will use.java.lang.Boolean
strict()
JexlBuilder
strict(boolean flag)
Sets whether the engine considers unknown variables, methods, functions and constructors as errors or evaluates them as null.JexlUberspect
uberspect()
JexlBuilder
uberspect(JexlUberspect u)
Sets the JexlUberspect instance the engine will use.
-
-
-
Field Detail
-
PERMISSIONS
private static JexlPermissions PERMISSIONS
The set of default permissions used when creating a new builder.Static but modifiable so these default permissions can be changed to a purposeful set.
In JEXL 3.3, these are
JexlPermissions.RESTRICTED
.In JEXL 3.2, these were equivalent to
JexlPermissions.UNRESTRICTED
.
-
CACHE_THRESHOLD
protected static final int CACHE_THRESHOLD
The default maximum expression length to hit the expression cache.- See Also:
- Constant Field Values
-
uberspect
private JexlUberspect uberspect
The JexlUberspect instance.
-
strategy
private JexlUberspect.ResolverStrategy strategy
TheJexlUberspect
resolver strategy.
-
permissions
private JexlPermissions permissions
The set of permissions.
-
sandbox
private JexlSandbox sandbox
The sandbox.
-
logger
private org.apache.commons.logging.Log logger
The Log to which all JexlEngine messages will be logged.
-
debug
private java.lang.Boolean debug
Whether error messages will carry debugging information.
-
cancellable
private java.lang.Boolean cancellable
Whether interrupt throws JexlException.Cancel.
-
options
private final JexlOptions options
The options.
-
collectMode
private int collectMode
Whether getVariables considers all potential equivalent syntactic forms.
-
arithmetic
private JexlArithmetic arithmetic
TheJexlArithmetic
instance.
-
cache
private int cache
The cache size.
-
cacheFactory
private java.util.function.IntFunction<JexlCache<?,?>> cacheFactory
The cache class factory.
-
stackOverflow
private int stackOverflow
The stack overflow limit.
-
cacheThreshold
private int cacheThreshold
The maximum expression length to hit the expression cache.
-
charset
private java.nio.charset.Charset charset
The charset.
-
loader
private java.lang.ClassLoader loader
The class loader.
-
features
private JexlFeatures features
The features.
-
-
Constructor Detail
-
JexlBuilder
public JexlBuilder()
Default constructor.As of JEXL 3.3, to reduce the security risks inherent to JEXL"s purpose, the builder will use a set of restricted permissions as a default to create the
JexlEngine
instance. This will greatly reduce which classes and methods are visible to JEXL and usable in scripts using default implicit behaviors.However, without mitigation, this change will likely break some scripts at runtime, especially those exposing your own class instances through arguments, contexts or namespaces. The new default set of allowed packages and denied classes is described by
JexlPermissions.RESTRICTED
.The recommended mitigation if your usage of JEXL is impacted is to first thoroughly review what should be allowed and exposed to script authors and implement those through a set of
JexlPermissions
; those are easily created usingJexlPermissions.parse(String...)
.In the urgent case of a strict 3.2 compatibility, the simplest and fastest mitigation is to use the 'unrestricted' set of permissions. The builder must be explicit about it either by setting the default permissions with a statement like
JexlBuilder.setDefaultPermissions(JexlPermissions.UNRESTRICTED);
or with a more precise one likenew JexlBuilder().permissions(
.JexlPermissions.UNRESTRICTED
)Note that an explicit call to
uberspect(JexlUberspect)
will supersede any permissions related behavior by using theJexlUberspect
provided as argument used as-is in the createdJexlEngine
.- Since:
- 3.3
-
-
Method Detail
-
setDefaultPermissions
public static void setDefaultPermissions(JexlPermissions permissions)
Sets the default permissions.- Parameters:
permissions
- the permissions
-
antish
public boolean antish()
- Returns:
- whether antish resolution is enabled
-
antish
public JexlBuilder antish(boolean flag)
Sets whether the engine will resolve antish variable names.- Parameters:
flag
- true means antish resolution is enabled, false disables it- Returns:
- this builder
-
arithmetic
public JexlArithmetic arithmetic()
- Returns:
- the arithmetic
-
arithmetic
public JexlBuilder arithmetic(JexlArithmetic a)
Sets the JexlArithmetic instance the engine will use.- Parameters:
a
- the arithmetic- Returns:
- this builder
-
cache
public int cache()
- Returns:
- the cache size
-
cache
public JexlBuilder cache(int size)
Sets the expression cache size the engine will use.The cache will contain at most
size
expressions of at mostcacheThreshold
length. Note that all JEXL caches are held through SoftReferences and may be garbage-collected.- Parameters:
size
- if not strictly positive, no cache is used.- Returns:
- this builder
-
cacheFactory
public java.util.function.IntFunction<JexlCache<?,?>> cacheFactory()
- Returns:
- the cache factory
-
cacheFactory
public JexlBuilder cacheFactory(java.util.function.IntFunction<JexlCache<?,?>> factory)
Sets the expression cache size the engine will use.- Parameters:
factory
- the function to produce a cache.- Returns:
- this builder
-
cacheThreshold
public int cacheThreshold()
- Returns:
- the cache threshold
-
cacheThreshold
public JexlBuilder cacheThreshold(int length)
Sets the maximum length for an expression to be cached.Expression whose length is greater than this expression cache length threshold will bypass the cache.
It is expected that a "long" script will be parsed once and its reference kept around in user-space structures; the jexl expression cache has no added-value in this case.
- Parameters:
length
- if not strictly positive, the value is silently replaced by the default value (64).- Returns:
- this builder
-
cancellable
public java.lang.Boolean cancellable()
- Returns:
- the cancellable information flag
- Since:
- 3.1
-
cancellable
public JexlBuilder cancellable(boolean flag)
Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.- Parameters:
flag
- true implies the engine throws the exception, false makes the engine return null.- Returns:
- this builder
- Since:
- 3.1
-
charset
public java.nio.charset.Charset charset()
- Returns:
- the charset
-
charset
public JexlBuilder charset(java.nio.charset.Charset arg)
Sets the charset to use.- Parameters:
arg
- the charset- Returns:
- this builder
- Since:
- 3.1
-
collectAll
public boolean collectAll()
- Returns:
- true if variable collection follows strict syntactic rule
- Since:
- 3.2
-
collectAll
public JexlBuilder collectAll(boolean flag)
Sets whether the engine variable collectors considers all potential forms of variable syntaxes.- Parameters:
flag
- true means var collections considers constant array accesses equivalent to dotted references- Returns:
- this builder
- Since:
- 3.2
-
collectMode
public int collectMode()
- Returns:
- 0 if variable collection follows strict syntactic rule
- Since:
- 3.2
-
collectMode
public JexlBuilder collectMode(int mode)
Experimental collector mode setter.- Parameters:
mode
- 0 or 1 as equivalents to false and true, other values are experimental- Returns:
- this builder
- Since:
- 3.2
-
create
public JexlEngine create()
- Returns:
- a
JexlEngine
instance
-
debug
public java.lang.Boolean debug()
- Returns:
- the debugging information flag
-
debug
public JexlBuilder debug(boolean flag)
Sets whether the engine will report debugging information when error occurs.- Parameters:
flag
- true implies debug is on, false implies debug is off.- Returns:
- this builder
-
features
public JexlFeatures features()
- Returns:
- the features
-
features
public JexlBuilder features(JexlFeatures f)
Sets the features the engine will use as a base by default.Note that the script flag will be ignored; the engine will be able to parse expressions and scripts.
Note also that these will apply to template expressions and scripts.
As a last remark, if lexical or lexicalShade are set as features, this method will also set the corresponding options.
- Parameters:
f
- the features- Returns:
- this builder
-
imports
public java.util.Collection<java.lang.String> imports()
Gets the optional set of imported packages.- Returns:
- the set of imports, may be empty, not null
-
imports
public JexlBuilder imports(java.util.Collection<java.lang.String> imports)
Sets the optional set of imports.- Parameters:
imports
- the imported packages- Returns:
- this builder
-
imports
public JexlBuilder imports(java.lang.String... imports)
Sets the optional set of imports.- Parameters:
imports
- the imported packages- Returns:
- this builder
-
lexical
public boolean lexical()
- Returns:
- whether lexical scope is enabled
-
lexical
public JexlBuilder lexical(boolean flag)
Sets whether the engine is in lexical mode.- Parameters:
flag
- true means lexical function scope is in effect, false implies non-lexical scoping- Returns:
- this builder
- Since:
- 3.2
-
lexicalShade
public boolean lexicalShade()
- Returns:
- whether lexical shading is enabled
-
lexicalShade
public JexlBuilder lexicalShade(boolean flag)
Sets whether the engine is in lexical shading mode.- Parameters:
flag
- true means lexical shading is in effect, false implies no lexical shading- Returns:
- this builder
- Since:
- 3.2
-
loader
public java.lang.ClassLoader loader()
- Returns:
- the class loader
-
loader
@Deprecated public JexlBuilder loader(java.nio.charset.Charset arg)
Deprecated.since 3.1 usecharset(Charset)
insteadSets the charset to use.- Parameters:
arg
- the charset- Returns:
- this builder
-
loader
public JexlBuilder loader(java.lang.ClassLoader l)
Sets the class loader to use.- Parameters:
l
- the class loader- Returns:
- this builder
-
logger
public org.apache.commons.logging.Log logger()
- Returns:
- the logger
-
logger
public JexlBuilder logger(org.apache.commons.logging.Log log)
Sets the o.a.c.Log instance to use.- Parameters:
log
- the logger- Returns:
- this builder
-
namespaces
public java.util.Map<java.lang.String,java.lang.Object> namespaces()
- Returns:
- the map of namespaces.
-
namespaces
public JexlBuilder namespaces(java.util.Map<java.lang.String,java.lang.Object> ns)
Sets the default namespaces map the engine will use.Each entry key is used as a prefix, each entry value used as a bean implementing methods; an expression like 'nsx:method(123)' will thus be solved by looking at a registered bean named 'nsx' that implements method 'method' in that map. If all methods are static, you may use the bean class instead of an instance as value.
If the entry value is a class that has one constructor taking a JexlContext as argument, an instance of the namespace will be created at evaluation time. It might be a good idea to derive a JexlContext to carry the information used by the namespace to avoid variable space pollution and strongly type the constructor with this specialized JexlContext.
The key or prefix allows to retrieve the bean that plays the role of the namespace. If the prefix is null, the namespace is the top-level namespace allowing to define top-level user-defined namespaces ( ie: myfunc(...) )
Note that the JexlContext is also used to try to solve top-level namespaces. This allows ObjectContext derived instances to call methods on the wrapped object.
- Parameters:
ns
- the map of namespaces- Returns:
- this builder
-
options
public JexlOptions options()
- Returns:
- the current set of options
-
permissions
public JexlPermissions permissions()
- Returns:
- the permissions
-
permissions
public JexlBuilder permissions(JexlPermissions p)
Sets the JexlPermissions instance the engine will use.- Parameters:
p
- the permissions- Returns:
- this builder
-
safe
public java.lang.Boolean safe()
- Returns:
- true if safe, false otherwise
-
safe
public JexlBuilder safe(boolean flag)
Sets whether the engine considers dereferencing null in navigation expressions as null or triggers an error.x.y()
if x is null throws an exception when not safe, return null and warns if it is.It is recommended to use safe(false) as an explicit default.
- Parameters:
flag
- true means safe navigation, false throws exception when dereferencing null- Returns:
- this builder
-
sandbox
public JexlSandbox sandbox()
- Returns:
- the sandbox
-
sandbox
public JexlBuilder sandbox(JexlSandbox box)
Sets the sandbox the engine will use.- Parameters:
box
- the sandbox- Returns:
- this builder
-
silent
public java.lang.Boolean silent()
- Returns:
- the silent error handling flag
-
silent
public JexlBuilder silent(boolean flag)
Sets whether the engine will throw JexlException during evaluation when an error is triggered.When not silent, the engine throws an exception when the evaluation triggers an exception or an error.
It is recommended to use silent(true) as an explicit default.
- Parameters:
flag
- true means no JexlException will occur, false allows them- Returns:
- this builder
-
stackOverflow
public int stackOverflow()
- Returns:
- the cache size
-
stackOverflow
public JexlBuilder stackOverflow(int size)
Sets the number of script/expression evaluations that can be stacked.- Parameters:
size
- if not strictly positive, limit is reached when Java StackOverflow is thrown.- Returns:
- this builder
-
strategy
public JexlUberspect.ResolverStrategy strategy()
- Returns:
- the JexlUberspect strategy
-
strategy
public JexlBuilder strategy(JexlUberspect.ResolverStrategy rs)
Sets the JexlUberspect strategy the engine will use.This is ignored if the uberspect has been set.
- Parameters:
rs
- the strategy- Returns:
- this builder
-
strict
public java.lang.Boolean strict()
- Returns:
- true if strict, false otherwise
-
strict
public JexlBuilder strict(boolean flag)
Sets whether the engine considers unknown variables, methods, functions and constructors as errors or evaluates them as null.When not strict, operators or functions using null operands return null on evaluation. When strict, those raise exceptions.
It is recommended to use strict(true) as an explicit default.
- Parameters:
flag
- true means strict error reporting, false allows them to be evaluated as null- Returns:
- this builder
-
uberspect
public JexlUberspect uberspect()
- Returns:
- the uberspect
-
uberspect
public JexlBuilder uberspect(JexlUberspect u)
Sets the JexlUberspect instance the engine will use.- Parameters:
u
- the uberspect- Returns:
- this builder
-
-