Skip to content

Commit

Permalink
Update information in SpEL Evaluation chapter in reference manual
Browse files Browse the repository at this point in the history
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
  • Loading branch information
sbrannen committed Aug 30, 2024
1 parent dca5523 commit 5927b70
Showing 1 changed file with 36 additions and 27 deletions.
63 changes: 36 additions & 27 deletions framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -222,29 +222,38 @@ Kotlin::
[[expressions-evaluation-context]]
== Understanding `EvaluationContext`

The `EvaluationContext` interface is used when evaluating an expression to resolve
properties, methods, or fields and to help perform type conversion. Spring provides two
The `EvaluationContext` API is used when evaluating an expression to resolve properties,
methods, or fields and to help perform type conversion. Spring provides two
implementations.

* `SimpleEvaluationContext`: Exposes a subset of essential SpEL language features and
configuration options, for categories of expressions that do not require the full extent
of the SpEL language syntax and should be meaningfully restricted. Examples include but
are not limited to data binding expressions and property-based filters.
`SimpleEvaluationContext`::
Exposes a subset of essential SpEL language features and configuration options, for
categories of expressions that do not require the full extent of the SpEL language
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
configuration options. You can use it to specify a default root object and to configure
every available evaluation-related strategy.
`StandardEvaluationContext`::
Exposes the full set of SpEL language features and configuration options. You can use
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.
It excludes Java type references, constructors, and bean references. It also requires
you to explicitly choose the level of support for properties and methods in expressions.
By default, the `create()` static factory method enables only read access to properties.
You can also obtain a builder to configure the exact level of support needed, targeting
one or some combination of the following.
`SimpleEvaluationContext` is designed to support only a subset of the SpEL language
syntax. For example, it excludes Java type references, constructors, and bean references.
It also requires you to explicitly choose the level of support for properties and methods
in expressions. When creating a `SimpleEvaluationContext` you need to choose the level of
support that you need for data binding in SpEL expressions:

* Custom `PropertyAccessor` only (no reflection)
* Data binding properties for read-only access
* Data binding properties for read and write
* Data binding for read-only access
* Data binding for read and write access
* 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]]
Expand Down Expand Up @@ -314,17 +323,17 @@ Kotlin::
It is possible to configure the SpEL expression parser by using a parser configuration
object (`org.springframework.expression.spel.SpelParserConfiguration`). The configuration
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
can 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
that is beyond the end of the current size of the array or list, SpEL can automatically
grow the array or list to accommodate that index. In order to add an element at the
index into a collection and the element at the specified index is `null`, SpEL can
automatically create the element. This is useful when using expressions made up of a
chain of property references. Similarly, if you index into a collection and specify an
index that is greater than the current size of the collection, SpEL can automatically
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
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
or custom converter that knows how to set the value, `null` will remain in the array or
list at the specified index. The following example demonstrates how to automatically grow
the list.
default constructor, `null` will be added to the collection. If there is no built-in
converter or custom converter that knows how to set the value, `null` will remain in the
collection at the specified index. The following example demonstrates how to
automatically grow a `List`.

[tabs]
======
Expand Down

0 comments on commit 5927b70

Please sign in to comment.