diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc index 8b30b68d9e6a6cf82dc035ecf7f68d5cb50072af..fdb8a298ad26c66900b1aa1764d6e13809788457 100644 --- a/src/docs/asciidoc/core/core-expressions.adoc +++ b/src/docs/asciidoc/core/core-expressions.adoc @@ -7,17 +7,17 @@ [[expressions-intro]] == Introduction -The Spring Expression Language (SpEL for short) is a powerful expression language that +The Spring Expression Language (_SpEL_ for short) is a powerful expression language that supports querying and manipulating an object graph at runtime. The language syntax is similar to Unified EL but offers additional features, most notably method invocation and basic string templating functionality. -While there are several other Java expression languages available, OGNL, MVEL, and JBoss -EL, to name a few, the Spring Expression Language was created to provide the Spring +While there are several other Java expression languages available -- OGNL, MVEL, and JBoss +EL, to name a few -- the Spring Expression Language was created to provide the Spring community with a single well supported expression language that can be used across all the products in the Spring portfolio. Its language features are driven by the requirements of the projects in the Spring portfolio, including tooling requirements for -code completion support within the eclipse based Spring Tool Suite. That said, +code completion support within the Eclipse based Spring Tool Suite. That said, SpEL is based on a technology agnostic API allowing other expression language implementations to be integrated should the need arise. @@ -29,10 +29,10 @@ infrastructure classes such as the parser. Most Spring users will not need to de this infrastructure and will instead only author expression strings for evaluation. An example of this typical use is the integration of SpEL into creating XML or annotated based bean definitions as shown in the section <> +for defining bean definitions>>. This chapter covers the features of the expression language, its API, and its language -syntax. In several places an Inventor and Inventor's Society class are used as the +syntax. In several places an `Inventor` and Inventor's `Society` classes are used as the target objects for expression evaluation. These class declarations and the data used to populate them are listed at the end of the chapter. @@ -82,7 +82,7 @@ The following code introduces the SpEL API to evaluate the literal string expres The value of the message variable is simply 'Hello World'. The SpEL classes and interfaces you are most likely to use are located in the packages -`org.springframework.expression` and its sub packages and `spel.support`. +`org.springframework.expression` and its sub packages such as `spel.support`. The interface `ExpressionParser` is responsible for parsing an expression string. In this example the expression string is a string literal denoted by the surrounding single @@ -120,7 +120,7 @@ as shown below. ---- SpEL also supports nested properties using standard _dot_ notation, i.e. -prop1.prop2.prop3 and the setting of property values +`prop1.prop2.prop3` and the setting of property values Public fields may also be accessed. @@ -181,7 +181,7 @@ create a boolean condition: === `EvaluationContext` The interface `EvaluationContext` is used when evaluating an expression to resolve -properties, methods, fields, and to help perform type conversion. There are two +properties, methods, or fields and to help perform type conversion. There are two out-of-the-box implementations. * `SimpleEvaluationContext` -- exposes a subset of essential SpEL language features and @@ -190,26 +190,26 @@ of the SpEL language syntax and should be meaningfully restricted. Examples incl are not limited to data binding expressions, property-based filters, and others. * `StandardEvaluationContext` -- exposes the full set of SpEL language features and -configuration options. You may use it to specify a default root object, and to configure +configuration options. You may 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 -explicit choosing the level of support for properties and methods in expressions. +It _excludes_ Java type references, constructors, and bean references. It also requires +that one 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 of, or some combination of the following: +one or some combination of the following: -. Custom `PropertyAccessor` only (no reflection). -. Data binding properties for read-only access. -. Data binding properties for read and write. +. Custom `PropertyAccessor` only (no reflection) +. Data binding properties for read-only access +. Data binding properties for read and write [[expressions-type-conversion]] ==== Type conversion -By default SpEL uses the conversion service available in Spring core ( -`org.springframework.core.convert.ConversionService`). This conversion service comes +By default SpEL uses the conversion service available in Spring core +(`org.springframework.core.convert.ConversionService`). This conversion service comes with many converters built in for common conversions but is also fully extensible so custom conversions between types can be added. Additionally it has the key capability that it is generics aware. This means that when working with generic types in @@ -288,17 +288,17 @@ It is also possible to configure the behaviour of the SpEL expression compiler. Spring Framework 4.1 includes a basic expression compiler. Expressions are usually interpreted which provides a lot of dynamic flexibility during evaluation but -does not provide the optimum performance. For occasional expression usage +does not provide optimum performance. For occasional expression usage this is fine, but when used by other components like Spring Integration, performance can be very important and there is no real need for the dynamism. -The new SpEL compiler is intended to address this need. The +The SpEL compiler is intended to address this need. The compiler will generate a real Java class on the fly during evaluation that embodies the expression behavior and use that to achieve much faster expression evaluation. Due to the lack of typing around expressions the compiler uses information gathered during the interpreted evaluations of an expression when performing compilation. For example, it does not know the type -of a property reference purely from the expression but during the first +of a property reference purely from the expression, but during the first interpreted evaluation it will find out what it is. Of course, basing the compilation on this information could cause trouble later if the types of the various expression elements change over time. For this reason compilation @@ -378,9 +378,9 @@ enum values (`off`, `immediate`, or `mixed`). [[expressions-compiler-limitations]] ==== Compiler limitations -With Spring Framework 4.1 the basic compilation framework is in place. However, the framework does not +Since Spring Framework 4.1 the basic compilation framework is in place. However, the framework does not yet support compiling every kind of expression. The initial focus has been on the common expressions that are -likely to be used in performance critical contexts. These kinds of expression cannot be compiled +likely to be used in performance critical contexts. The following kinds of expression cannot be compiled at the moment: - expressions involving assignment @@ -951,7 +951,7 @@ used). === Variables Variables can be referenced in the expression using the syntax `#variableName`. Variables -are set using the method setVariable on `EvaluationContext` implementations. +are set using the method `setVariable` on `EvaluationContext` implementations. [source,java,indent=0] [subs="verbatim,quotes"] @@ -969,10 +969,10 @@ are set using the method setVariable on `EvaluationContext` implementations. [[expressions-this-root]] ==== The #this and #root variables -The variable #this is always defined and refers to the current evaluation object -(against which unqualified references are resolved). The variable #root is always -defined and refers to the root context object. Although #this may vary as components of -an expression are evaluated, #root always refers to the root. +The variable `#this` is always defined and refers to the current evaluation object +(against which unqualified references are resolved). The variable `#root` is always +defined and refers to the root context object. Although `#this` may vary as components of +an expression are evaluated, `#root` always refers to the root. [source,java,indent=0] [subs="verbatim,quotes"] @@ -1047,7 +1047,7 @@ The above method can then be registered and used as follows: === Bean references If the evaluation context has been configured with a bean resolver it is possible to -lookup beans from an expression using the (@) symbol. +look up beans from an expression using the `@` symbol. [source,java,indent=0] [subs="verbatim,quotes"] @@ -1060,7 +1060,7 @@ lookup beans from an expression using the (@) symbol. Object bean = parser.parseExpression("@foo").getValue(context); ---- -To access a factory bean itself, the bean name should instead be prefixed with a (&) symbol. +To access a factory bean itself, the bean name should instead be prefixed with an `&` symbol. [source,java,indent=0] [subs="verbatim,quotes"] @@ -1087,7 +1087,7 @@ the expression. A minimal example is: "false ? 'trueExp' : 'falseExp'").getValue(String.class); ---- -In this case, the boolean false results in returning the string value 'falseExp'. A more +In this case, the boolean false results in returning the string value `'falseExp'`. A more realistic example is shown below. [source,java,indent=0] @@ -1274,9 +1274,9 @@ define, a common choice is to use `#{ }` as the delimiters. For example, // evaluates to "random number is 0.7038186818312008" ---- -The string is evaluated by concatenating the literal text 'random number is ' with the -result of evaluating the expression inside the #{ } delimiter, in this case the result -of calling that random() method. The second argument to the method `parseExpression()` +The string is evaluated by concatenating the literal text `'random number is '` with the +result of evaluating the expression inside the `#{ }` delimiter, in this case the result +of calling that `random()` method. The second argument to the method `parseExpression()` is of the type `ParserContext`. The `ParserContext` interface is used to influence how the expression is parsed in order to support the expression templating functionality. The definition of `TemplateParserContext` is shown below.