Class JexlBuilder
     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:
- 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. 
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected static final intThe default maximum expression length to hit the expression cache.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionbooleanantish()Is antish resolution enabled?antish(boolean flag) Sets whether the engine will resolve antish variable names.Gets the JexlArithmetic instance the engine will use.Sets the JexlArithmetic instance the engine will use.booleanLogical(boolean flag) Sets whether logical expressions ("" , ||) coerce their result to boolean.intcache()Gets the expression cache size the engine will use.cache(int size) Sets the expression cache size the engine will use.IntFunction<JexlCache<?, ?>> Gets the expression-cache factory the engine will use.cacheFactory(IntFunction<JexlCache<?, ?>> factory) Sets the expression-cache factory the engine will use.intGets the maximum length for an expression to be cached.cacheThreshold(int length) Sets the maximum length for an expression to be cached.Gets the cancellable information flagcancellable(boolean flag) Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.charset()Gets the charsetSets the charset to use.booleanDoes the variable collection follow strict syntactic rule?collectAll(boolean flag) Sets whether the engine variable collectors considers all potential forms of variable syntaxes.intGets the collection mode.collectMode(int mode) Experimental collector mode setter.create()Create a new enginedebug()Gets the debug flagdebug(boolean flag) Sets whether the engine will report debugging information when error occurs.features()Gets the features the engine will use as a base by default.Sets the features the engine will use as a base by default.imports()Gets the optional set of imported packages.Sets the optional set of imports.imports(Collection<String> imports) Sets the optional set of imports.booleanlexical()Deprecated.3.5.0lexical(boolean flag) Sets whether the engine is in lexical mode.booleanDeprecated.3.5.0lexicalShade(boolean flag) Sets whether the engine is in lexical shading mode.loader()Gets the classloaderSets the class loader to use.Deprecated.since 3.1 usecharset(Charset)insteadorg.apache.commons.logging.Loglogger()Gets the loggerlogger(org.apache.commons.logging.Log log) Sets the o.a.c.Log instance to use.Gets the map of namespaces.namespaces(Map<String, Object> ns) Sets the default namespaces map the engine will use.options()Gets the current set of optionsSupplier<org.apache.commons.jexl3.parser.JexlScriptParser> Gets the Jexl script parser factory the engine will use.parserFactory(Supplier<org.apache.commons.jexl3.parser.JexlScriptParser> factory) Sets the Jexl script parser factory the engine will use.Gets the permissionsSets the JexlPermissions instance the engine will use.safe()Is it safe to dereference null?safe(boolean flag) Sets whether the engine considers dereferencing null in navigation expressions as null or triggers an error.sandbox()Gets the sandboxsandbox(JexlSandbox box) Sets the sandbox the engine will use.static voidsetDefaultPermissions(JexlPermissions permissions) Sets the default permissions.silent()Is error handling silent?silent(boolean flag) Sets whether the engine will throw JexlException during evaluation when an error is triggered.intGets the cache sizestackOverflow(int size) Sets the number of script/expression evaluations that can be stacked.strategy()Gets the JexlUberspect strategySets the JexlUberspect strategy the engine will use.strict()Is it strict mode?strict(boolean flag) Sets whether the engine considers unknown variables, methods, functions and constructors as errors or evaluates them as null.strictInterpolation(boolean flag) Is interpolation strict?Gets the uberspectSets the JexlUberspect instance the engine will use.
- 
Field Details- 
CACHE_THRESHOLDThe default maximum expression length to hit the expression cache.- See Also:
 
 
- 
- 
Constructor Details- 
JexlBuilderpublic 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 JexlEngineinstance. 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 theJexlUberspectprovided as argument used as-is in the createdJexlEngine.- Since:
- 3.3
 
 
- 
- 
Method Details- 
setDefaultPermissionsSets the default permissions.- Parameters:
- permissions- the permissions
 
- 
antishIs antish resolution enabled?- Returns:
- whether antish resolution is enabled
 
- 
antishSets whether the engine will resolve antish variable names.- Parameters:
- flag- true means antish resolution is enabled, false disables it
- Returns:
- this builder
 
- 
arithmeticGets the JexlArithmetic instance the engine will use.- Returns:
- the arithmetic
 
- 
arithmeticSets the JexlArithmetic instance the engine will use.- Parameters:
- a- the arithmetic
- Returns:
- this builder
 
- 
booleanLogicalSets whether logical expressions ("" , ||) coerce their result to boolean.- Parameters:
- flag- true or false
- Returns:
- this builder
 
- 
cacheGets the expression cache size the engine will use.- Returns:
- the cache size
 
- 
cacheSets the expression cache size the engine will use.The cache will contain at most sizeexpressions of at mostcacheThresholdlength. 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
 
- 
cacheFactoryGets the expression-cache factory the engine will use.- Returns:
- the cache factory
 
- 
cacheFactorySets the expression-cache factory the engine will use.- Parameters:
- factory- the function to produce a cache.
- Returns:
- this builder
 
- 
parserFactoryGets the Jexl script parser factory the engine will use.- Returns:
- the cache factory
- Since:
- 3.5.0
 
- 
parserFactorypublic JexlBuilder parserFactory(Supplier<org.apache.commons.jexl3.parser.JexlScriptParser> factory) Sets the Jexl script parser factory the engine will use.- Parameters:
- factory- the function to produce a cache.
- Returns:
- this builder
- Since:
- 3.5.0
 
- 
cacheThresholdGets the maximum length for an expression to be cached.- Returns:
- the cache threshold
 
- 
cacheThresholdSets 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
 
- 
cancellableGets the cancellable information flag- Returns:
- the cancellable information flag
- Since:
- 3.1
 
- 
cancellableSets 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
 
- 
charsetGets the charset- Returns:
- the charset
 
- 
charsetSets the charset to use.- Parameters:
- arg- the charset
- Returns:
- this builder
- Since:
- 3.1
 
- 
collectAllDoes the variable collection follow strict syntactic rule?- Returns:
- true if variable collection follows strict syntactic rule
- Since:
- 3.2
 
- 
collectAllSets 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
 
- 
collectModeGets the collection mode.- Returns:
- 0 if variable collection follows strict syntactic rule
- Since:
- 3.2
 
- 
collectModeExperimental collector mode setter.- Parameters:
- mode- 0 or 1 as equivalents to false and true, other values are experimental
- Returns:
- this builder
- Since:
- 3.2
 
- 
createCreate a new engine- Returns:
- a JexlEngineinstance
 
- 
debugGets the debug flag- Returns:
- the debugging information flag
 
- 
debugSets 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
 
- 
featuresGets the features the engine will use as a base by default.- Returns:
- the features
 
- 
featuresSets 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
 
- 
importsGets the optional set of imported packages.- Returns:
- the set of imports, may be empty, not null
 
- 
importsSets the optional set of imports.- Parameters:
- imports- the imported packages
- Returns:
- this builder
 
- 
importsSets the optional set of imports.- Parameters:
- imports- the imported packages
- Returns:
- this builder
 
- 
lexicalDeprecated.3.5.0Is lexical scope enabled?- Returns:
- whether lexical scope is enabled
- See Also:
 
- 
lexicalSets 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
 
- 
lexicalShadeDeprecated.3.5.0Checks whether lexical shading is enabled.- Returns:
- whether lexical shading is enabled
- See Also:
 
- 
lexicalShadeSets 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
 
- 
loaderGets the classloader- Returns:
- the class loader
 
- 
loaderDeprecated.since 3.1 usecharset(Charset)insteadSets the charset to use.- Parameters:
- arg- the charset
- Returns:
- this builder
 
- 
loaderSets the class loader to use.- Parameters:
- l- the class loader
- Returns:
- this builder
 
- 
loggerGets the logger- Returns:
- the logger
 
- 
loggerSets the o.a.c.Log instance to use.- Parameters:
- log- the logger
- Returns:
- this builder
 
- 
namespacesGets the map of namespaces.- Returns:
- the map of namespaces.
 
- 
namespacesSets 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
 
- 
optionsGets the current set of options- Returns:
- the current set of options
 
- 
permissionsGets the permissions- Returns:
- the permissions
 
- 
permissionsSets the JexlPermissions instance the engine will use.- Parameters:
- p- the permissions
- Returns:
- this builder
 
- 
safeIs it safe to dereference null?- Returns:
- true if safe, false otherwise
 
- 
safeSets 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
 
- 
sandboxGets the sandbox- Returns:
- the sandbox
 
- 
sandboxSets the sandbox the engine will use.- Parameters:
- box- the sandbox
- Returns:
- this builder
 
- 
silentIs error handling silent?- Returns:
- the silent error handling flag
 
- 
silentSets 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
 
- 
stackOverflowGets the cache size- Returns:
- the cache size
 
- 
stackOverflowSets 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
 
- 
strategyGets the JexlUberspect strategy- Returns:
- the JexlUberspect strategy
 
- 
strategySets the JexlUberspect strategy the engine will use.This is ignored if the uberspect has been set. - Parameters:
- rs- the strategy
- Returns:
- this builder
 
- 
strictIs it strict mode?- Returns:
- true if strict, false otherwise
 
- 
strictSets 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
 
- 
strictInterpolationIs interpolation strict?- Parameters:
- flag- strict interpolation flag
- Returns:
- this builder
- See Also:
 
- 
uberspectGets the uberspect- Returns:
- the uberspect
 
- 
uberspectSets the JexlUberspect instance the engine will use.- Parameters:
- u- the uberspect
- Returns:
- this builder
 
 
-