public class JexlBuilder extends Object
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 throw JexlException
exceptions.
The strict
flag tells the engine when and if null as operand is considered an error. The safe
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
and lexicalShade
flags can be used to enforce a lexical scope for
variables and parameters. The lexicalShade
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. (see JexlFeatures
)
The following rules apply on silent and strict flags:
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.
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.
The error control grain is roughly on par with JEXL 1.0
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.
Modifier and Type | Field and Description |
---|---|
protected static int |
CACHE_THRESHOLD
The default maximum expression length to hit the expression cache.
|
Constructor and Description |
---|
JexlBuilder()
Default constructor.
|
Modifier and Type | Method and 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.
|
int |
cacheThreshold() |
JexlBuilder |
cacheThreshold(int length)
Sets the maximum length for an expression to be cached.
|
Boolean |
cancellable() |
JexlBuilder |
cancellable(boolean flag)
Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation
and return null.
|
Charset |
charset() |
JexlBuilder |
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() |
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.
|
Collection<String> |
imports()
Gets the optional set of imported packages.
|
JexlBuilder |
imports(Collection<String> imports)
Sets the optional set of imports.
|
JexlBuilder |
imports(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.
|
ClassLoader |
loader() |
JexlBuilder |
loader(Charset arg)
Deprecated.
since 3.1 use
charset(Charset) instead |
JexlBuilder |
loader(ClassLoader l)
Sets the class loader to use.
|
org.apache.commons.logging.Log |
logger() |
JexlBuilder |
logger(org.apache.commons.logging.Log log)
Sets the o.a.c.Log instance to use.
|
Map<String,Object> |
namespaces() |
JexlBuilder |
namespaces(Map<String,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.
|
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.
|
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.
|
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.
|
protected static final int CACHE_THRESHOLD
public JexlBuilder()
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 using JexlPermissions.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 like new JexlBuilder().permissions(
.
JexlPermissions.UNRESTRICTED
)
Note that an explicit call to uberspect(JexlUberspect)
will supersede any permissions related behavior
by using the JexlUberspect
provided as argument used as-is in the created JexlEngine
.
public static void setDefaultPermissions(JexlPermissions permissions)
permissions
- the permissionspublic JexlBuilder uberspect(JexlUberspect u)
u
- the uberspectpublic JexlUberspect uberspect()
public JexlBuilder permissions(JexlPermissions p)
p
- the permissionspublic JexlPermissions permissions()
public JexlBuilder strategy(JexlUberspect.ResolverStrategy rs)
This is ignored if the uberspect has been set.
rs
- the strategypublic JexlUberspect.ResolverStrategy strategy()
public JexlOptions options()
public JexlBuilder arithmetic(JexlArithmetic a)
a
- the arithmeticpublic JexlArithmetic arithmetic()
public JexlBuilder sandbox(JexlSandbox box)
box
- the sandboxpublic JexlSandbox sandbox()
public JexlBuilder features(JexlFeatures f)
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.
f
- the featurespublic JexlFeatures features()
public JexlBuilder logger(org.apache.commons.logging.Log log)
log
- the loggerpublic org.apache.commons.logging.Log logger()
public JexlBuilder loader(ClassLoader l)
l
- the class loaderpublic ClassLoader loader()
@Deprecated public JexlBuilder loader(Charset arg)
charset(Charset)
insteadarg
- the charsetpublic JexlBuilder charset(Charset arg)
arg
- the charsetpublic JexlBuilder antish(boolean flag)
flag
- true means antish resolution is enabled, false disables itpublic boolean antish()
public JexlBuilder lexical(boolean flag)
flag
- true means lexical function scope is in effect, false implies non-lexical scopingpublic boolean lexical()
public JexlBuilder lexicalShade(boolean flag)
flag
- true means lexical shading is in effect, false implies no lexical shadingpublic boolean lexicalShade()
public JexlBuilder silent(boolean flag)
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.
flag
- true means no JexlException will occur, false allows thempublic JexlBuilder strict(boolean flag)
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.
flag
- true means strict error reporting, false allows them to be evaluated as nullpublic JexlBuilder safe(boolean flag)
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.
flag
- true means safe navigation, false throws exception when dereferencing nullpublic JexlBuilder debug(boolean flag)
flag
- true implies debug is on, false implies debug is off.public JexlBuilder cancellable(boolean flag)
flag
- true implies the engine throws the exception, false makes the engine return null.public Boolean cancellable()
public JexlBuilder collectAll(boolean flag)
flag
- true means var collections considers constant array accesses equivalent to dotted referencespublic JexlBuilder collectMode(int mode)
mode
- 0 or 1 as equivalents to false and true, other values are experimentalpublic boolean collectAll()
public int collectMode()
public JexlBuilder namespaces(Map<String,Object> ns)
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.
ns
- the map of namespacespublic Map<String,Object> namespaces()
public Collection<String> imports()
public JexlBuilder imports(Collection<String> imports)
imports
- the imported packagespublic JexlBuilder imports(String... imports)
imports
- the imported packagespublic JexlBuilder cache(int size)
The cache will contain at most size
expressions of at most cacheThreshold
length.
Note that all JEXL caches are held through SoftReferences and may be garbage-collected.
size
- if not strictly positive, no cache is used.public int cache()
public JexlBuilder cacheThreshold(int length)
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.
length
- if not strictly positive, the value is silently replaced by the default value (64).public int cacheThreshold()
public JexlBuilder stackOverflow(int size)
size
- if not strictly positive, limit is reached when java StackOverflow is thrown.public int stackOverflow()
public JexlEngine create()
JexlEngine
instanceCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.