Broadleaf Microservices

Rules Engine Configuration

Overview

There are various properties and beans you can configure when utilizing Broadleaf’s Rules Engine.

Configuring the SpelExpressionParser

The SpelRuleEvaluationService expects an org.springframework.expression.ExpressionParser to be provided in its constructor, and a default org.springframework.expression.spel.standard.SpelExpressionParser bean is registered in the auto-configuration. The parser itself is configured through the org.springframework.expression.spel.SpelParserConfiguration bean.

The values supplied to the parser configuration are sourced from properties in RuleBuilderParserProperties to allow simple customizations without code changes:

Property Description

broadleaf.rulebuilder.evaluation.compilerMode

Determines the mode for the SpelCompiler. Defaults to MIXED. See org.springframework.expression.spel.SpelCompilerMode for all modes and their meanings.

broadleaf.rulebuilder.evaluation.autoGrowNullReferences

Tells the parser whether to automatically initialize (grow) null references. Defaults to false.

broadleaf.rulebuilder.evaluation.autoGrowCollections

Tells the parser whether to automatically grow collections. This determines whether an array or collection should be expanded to accommodate an out-of-bounds index. Defaults to false.

broadleaf.rulebuilder.evaluation.maximumAutoGrowSize

Tells the parser the maximum size to which the collection can automatically grow. Defaults to the maximum allowed integer value.

Compiling Expressions

ClassLoader for Compilation

The org.springframework.expression.spel.SpelParserConfiguration also takes an optional classloader argument to serve as the basis for expression compilation.

If not supplied, the context classloader for the thread that is running during the expression evaluation will be used.

By default, the class loader will be sourced from these places, in order of highest to lowest precedence:

  • Classloader of the thread running during bean initialization of the configuration

  • Classloader of the RulesEngineAutoConfiguration class

  • System classloader

Unsupported Compilation Cases

Warning

Compilation fails in the following cases:

  • expressions involving assignment

  • expressions relying on the conversion service

  • expressions using custom resolvers or accessors

  • expressions using selection or projection

Configuring the EvaluationContext produced by CachingStdEvaluationContextFactory

For every invocation of CachingStdEvaluationContextFactory#getEvaluationContext(), we expect to populate each EvaluationContext with the root object and variables from the ExpressionContext. However, it may be useful to also load additional information in every created EvaluationContext.

Default Variables

Imagine a scenario where you want every rule to be able to use some common utility functions. If that’s the case, it makes sense to expose those utility functions through default variables loaded into every EvaluationContext.

The factory accepts a Map<String, Object> of "default expression variables" in its constructor, and it will set each of these onto every EvaluationContext it creates.

The map of variables is sourced from the defaultExpressionVariables bean defined in the auto-configuration. To add or change the default variables, simply override that bean.

Out of the box, Broadleaf provides a handful of values in this map that serve as shortcuts to useful utility classes. For example, there is an entry for strings that exposes the StringExpressionVariable object, which is effectively just a wrapper around the popular org.apache.commons.lang3.StringUtils library. A rule can then reference this object like #strings.equals(name, 'Expected Name').

List of All Default Variables

Variable name Object value Description

strings

StringExpressionVariable

Common, null-safe, string operations

dates

DateExpressionVariable

Common, null-safe, date operations

locales

LocaleExpressionVariable

Common, null-safe, locale operations

collections

CollectionExpressionVariable

Common, null-safe, collection operations

decimals

DecimalExpressionVariable

Common, null-safe, decimal operations

money

MoneyExpressionVariable

Common, null-safe operations for MonetaryAmount

objects

ObjectExpressionVariable

General object utilities

Default Property Accessors

If you want to customize how properties of objects referenced in rules are accessed, you’ll need to introduce new org.springframework.expression.PropertyAccessor implementations and ensure they are present in each EvaluationContext.

The factory accepts a list of PropertyAccessor objects in its constructor, and it will set each of these onto every EvaluationContext it creates.

To add or change the default property accessors, override the defaultPropertyAccessors list bean.

List of All Default Property Accessors

Accessor Description

MapAccessor

A simple extension of Spring’s org.springframework.context.expression.MapAccessor that doesn’t throw an exception if a key is missing.