Update information in SpEL Evaluation chapter in reference manual

This commit updates the Evaluation chapter to reflect the following.

- SimpleEvaluationContext no longer has a create() method. Instead it
  has forPropertyAccessors(), forReadOnlyDataBinding(), and
  forReadWriteDataBinding() factory methods.

- SpEL cannot automatically create missing array elements or grow the
  size of an array like it can for a collection.

Closes gh-33456
This commit is contained in:
Sam Brannen 2024-08-30 19:06:30 +02:00
parent dca55236c4
commit 5927b70dfe
1 changed files with 36 additions and 27 deletions

View File

@ -222,29 +222,38 @@ Kotlin::
[[expressions-evaluation-context]] [[expressions-evaluation-context]]
== Understanding `EvaluationContext` == Understanding `EvaluationContext`
The `EvaluationContext` interface is used when evaluating an expression to resolve The `EvaluationContext` API is used when evaluating an expression to resolve properties,
properties, methods, or fields and to help perform type conversion. Spring provides two methods, or fields and to help perform type conversion. Spring provides two
implementations. implementations.
* `SimpleEvaluationContext`: Exposes a subset of essential SpEL language features and `SimpleEvaluationContext`::
configuration options, for categories of expressions that do not require the full extent Exposes a subset of essential SpEL language features and configuration options, for
of the SpEL language syntax and should be meaningfully restricted. Examples include but categories of expressions that do not require the full extent of the SpEL language
are not limited to data binding expressions and property-based filters. syntax and should be meaningfully restricted. Examples include but are not limited to
data binding expressions and property-based filters.
* `StandardEvaluationContext`: Exposes the full set of SpEL language features and `StandardEvaluationContext`::
configuration options. You can use it to specify a default root object and to configure Exposes the full set of SpEL language features and configuration options. You can use
every available evaluation-related strategy. it to specify a default root object and to configure every available evaluation-related
strategy.
`SimpleEvaluationContext` is designed to support only a subset of the SpEL language syntax. `SimpleEvaluationContext` is designed to support only a subset of the SpEL language
It excludes Java type references, constructors, and bean references. It also requires syntax. For example, it excludes Java type references, constructors, and bean references.
you to explicitly choose the level of support for properties and methods in expressions. It also requires you to explicitly choose the level of support for properties and methods
By default, the `create()` static factory method enables only read access to properties. in expressions. When creating a `SimpleEvaluationContext` you need to choose the level of
You can also obtain a builder to configure the exact level of support needed, targeting support that you need for data binding in SpEL expressions:
one or some combination of the following.
* Custom `PropertyAccessor` only (no reflection) * Data binding for read-only access
* Data binding properties for read-only access * Data binding for read and write access
* Data binding properties for read and write * A custom `PropertyAccessor` (typically not reflection-based), potentially combined with
a `DataBindingPropertyAccessor`
Conveniently, `SimpleEvaluationContext.forReadOnlyDataBinding()` enables read-only access
to properties via `DataBindingPropertyAccessor`. Similarly,
`SimpleEvaluationContext.forReadWriteDataBinding()` enables read and write access to
properties. Alternatively, configure custom accessors via
`SimpleEvaluationContext.forPropertyAccessors(...)`, potentially disable assignment, and
optionally activate method resolution and/or a type converter through the builder.
[[expressions-type-conversion]] [[expressions-type-conversion]]
@ -314,17 +323,17 @@ Kotlin::
It is possible to configure the SpEL expression parser by using a parser configuration It is possible to configure the SpEL expression parser by using a parser configuration
object (`org.springframework.expression.spel.SpelParserConfiguration`). The configuration object (`org.springframework.expression.spel.SpelParserConfiguration`). The configuration
object controls the behavior of some of the expression components. For example, if you object controls the behavior of some of the expression components. For example, if you
index into an array or collection and the element at the specified index is `null`, SpEL index into a collection and the element at the specified index is `null`, SpEL can
can automatically create the element. This is useful when using expressions made up of a automatically create the element. This is useful when using expressions made up of a
chain of property references. If you index into an array or list and specify an index chain of property references. Similarly, if you index into a collection and specify an
that is beyond the end of the current size of the array or list, SpEL can automatically index that is greater than the current size of the collection, SpEL can automatically
grow the array or list to accommodate that index. In order to add an element at the grow the collection to accommodate that index. In order to add an element at the
specified index, SpEL will try to create the element using the element type's default specified index, SpEL will try to create the element using the element type's default
constructor before setting the specified value. If the element type does not have a constructor before setting the specified value. If the element type does not have a
default constructor, `null` will be added to the array or list. If there is no built-in default constructor, `null` will be added to the collection. If there is no built-in
or custom converter that knows how to set the value, `null` will remain in the array or converter or custom converter that knows how to set the value, `null` will remain in the
list at the specified index. The following example demonstrates how to automatically grow collection at the specified index. The following example demonstrates how to
the list. automatically grow a `List`.
[tabs] [tabs]
====== ======