From 51f741ccec218e355903e2d61406cfc1ed23b055 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Sun, 5 Apr 2009 09:38:19 +0000 Subject: [PATCH] Initial pass of docs for he Spring expression language. --- .../src/expressions.xml | 465 ++++++++++++++++++ .../src/spring-framework-reference.xml | 5 + 2 files changed, 470 insertions(+) create mode 100644 spring-framework-reference/src/expressions.xml diff --git a/spring-framework-reference/src/expressions.xml b/spring-framework-reference/src/expressions.xml new file mode 100644 index 0000000000..644030f093 --- /dev/null +++ b/spring-framework-reference/src/expressions.xml @@ -0,0 +1,465 @@ + + + Spring Expression Language (SpEL) + +
+ Introduction + + 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 community with a single well supported + expression language that can 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 SpringSource Tool Suite. That + said, SpEL is based on an technology agnostic API allowing other + expression language implementations to be integreatd should the need + arise. + + While SpEL serves as the foundation for expression evaluation within + the Spring portfolio, it is not directly tied to Spring and can be used + independently. In order to be self contained many of the examples shown + use SpEL as if it was an independent expression language. This requires + creating a few boostrapping infrastructure classes such as the parser. + Most Spring users will not need to deal with this infrastructure and will + instead only be authoring expression strings for evaluation. An example of + this typical use is the integration of SpEL into the definition of XML or + annotated based bean definitions shown in the section Expression support for defining bean + definitions. + + This chapter covers the features of the expression language and its + synax. In several places an Inventor and Inventor's Society class 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. + +
+ +
+ Feature Overview + + The expression language support the following functionality + + + + Literal expressions + + + + Boolean and relational operators + + + + Regular expressions + + + + Class expressions + + + + Accessing properties, arrays, lists, maps + + + + Method invocation + + + + Operators + + + + Assignment + + + + Calling constructors + + + + Variables + + + + User defined functions + + + + Templated expressions + + +
+ +
+ Expression Evaluation using Spring's Expression Interface + + This section introduces simple use of SpEL interfaces and its + expression language. The complete language reference can be found in the + section Language + Reference + + The following code introduces the SpEL API to evaluate the literal + string expression 'Hello World' + + ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("'Hello World'"); +String message = (String) exp.getValue();The value of the + message variable is simply 'Hello World'. + + The expression language is based on a grammar and uses ANTLR to + construct the lexer and parser. The interface + ExpressionParser is responsible for parsing + an expression string, in this case a string literal denoted by the + surrounding single quotes. The interface + Expression is responsible for evaluating + the previously defined expression string. There are two exceptions that + can be thrown, ParseException and + EvaluationException when calling + 'parser.parseExpression' and + 'exp.getValue' respectfully. + + SpEL supports a wide range of features, such a calling methods, + accessing properties and calling constructors. + + As an example to method invocation, we call the 'concat' method on + the string literal + + ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("'Hello World'.concat(!)"); +String message = (String) exp.getValue(); + + The value of message is now 'Hello World!'. + + As an example of calling a JavaBean property, the String property + 'Bytes' can be called as shown below + + ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("'Hello World'.bytes"); // invokes 'getBytes()' +byte[] bytes = (byte[]) exp.getValue(); + + Upper or lowercase can be used to specify the property name. SpEL + also supports nested properties using standard 'dot' notation, i.e. + prop1.prop2.prop3. + + Public fields may also be accessed + + ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("'Hello World'.bytes.length"); // invokes 'getBytes().length' +int length = (Integer) exp.getValue(); + + The String's constructor can be called instead of using the string + literal + + ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("new String('hello world').toUpperCase()"); +String message = exp.getValue(String.class); + + Note the use of the generic method public <T> T + getValue(Class<T> desiredResultType). Using this method + removes the need to cast the value of the expression to the desired result + type. An EvaluationException will be thrown if the + value an not be cast to the type T or converted using + the registered type converter. + + The more common usage of SpEL is provide an expression string that + is evaluated against a specific object instance. In the following example + we retrieve the Name property from an instance of the + Inventor class. + + GregorianCalendar c = new GregorianCalendar(); +c.set(1856, 7, 9); + +// The constructor arguments are name, birthday, and nationaltiy. +Inventor tesla = new Inventor("Nikola Tesla", c.getTime(), "Serbian"); + +ExpressionParser parser = new SpelAntlrExpressionParser(); +Expression exp = parser.parseExpression("Name"); + +EvaluationContext context = new StandardEvaluationContext(); +context.setRootObject(tesla); + +String name = (String) exp.getValue(context);In the last + line, the value of the string variable 'name' will be set to "Nikola + Tesla". + + + In standalone usage of SpEL you will need to create the parser + as well as provide an evaluation context. However, more common usage + would be to provide only the SpEL expression string as part of a + configuration file, for example for Spring bean or web flow + definitions. The parser, evaluation context and root object will be + set up for you implicitly. + + +
+ The EvaluationContext interface + + The interface EvaluationContext is + used when evaluating an expression to resolve properties, methods + ,fields, and help perform type conversion. The out-of-the-box + implementation, StandardEvaluationContext ,uses + reflection to manipulate the object, caching java.lang.reflect Method, + Fields, and Constructor instances for increased performance. + + The StandardEvaluationContext is where you + specify the root object to evaluate against via the method + setRootObject . You can also specify variables + and functions using the methods setVariable + and, registerFunction. The use of variables and + functions are described in the language reference section. + +
+ Type Conversion + + The StandardEvaluationContext uses an instance of + org.springframework.expression.TypeConverter. A + simple implementation of this interface, + StandardTypeConverter, that converts basic + types, primitive values, booleans and characters is used but will be + replaced with an updated type conversion framework that is to be + included as part of Spring 3.0 +
+
+
+ +
+ Expression support for defining bean definitions + + SpEL expressions can be used with XML or annotation based + configuration metadata for defining BeanDefinitions. In both cases the + syntax to define the expression is of the form #{ <expression + string> }. + +
+ XML based configuration + + A property or constructor-arg value can be set using expressions + as shown below + + <bean id="numberGuess" class="org.spring.samples.NumberGuess"> + <property name="randomNumber" value="#{ T(java.lang.Math).random() * 100.0 }"/> + + <!-- other properties --> +</bean> + + The variable 'systemProperties' is predefined, so you can use it + in your expressions as shown below. + + <bean id="taxCalculator" class="org.spring.samples.TaxCalculator"> + <property name="defaultLocale" value="#{ systemProperties['user.region'] }"/> + + <!-- other properties --> +</bean> + + You can also refer to other bean properties by name, for + example + + <bean id="numberGuess" class="org.spring.samples.NumberGuess"> + <property name="randomNumber" value="#{ T(java.lang.Math).random() * 100.0 }"/> + + <!-- other properties --> +</bean> + + +<bean id="shapeGuess" class="org.spring.samples.ShapeGuess"> + <property name="initialShapeSeed" value="#{ numberGuess.randomNumber }"/> + + <!-- other properties --> +</bean> +
+ +
+ Annotation-based configuration + + The @Value annotation can be placed on fields, methods and + method/constructor parameters to specify a default value. + + Here is an example to set the default value of a field + variable + + public static class FieldValueTestBean + + @Value("#{ systemProperties['user.region'] }") + private String defaultLocale; + + public void setDefaultLocale(String defaultLocale) + { + this.defaultLocale = defaultLocale; + } + + public String getDefaultLocale() + { + return this.defaultLocale; + } + +} + + + + The equivalent but on a property setter method is shown + below + + public static class PropertyValueTestBean + + private String defaultLocale; + + @Value("#{ systemProperties['user.region'] }") + public void setDefaultLocale(String defaultLocale) + { + this.defaultLocale = defaultLocale; + } + + public String getDefaultLocale() + { + return this.defaultLocale; + } + +} + + Autowired methods and constructors can also use the + @Value annotation. + + public class SimpleMovieLister { + + private MovieFinder movieFinder; + private String defaultLocale; + + @Autowired + public void configure(MovieFinder movieFinder, + @Value("#{ systemProperties['user.region'] } String defaultLocale) { + this.movieFinder = movieFinder; + this.defaultLocale = defaultLocale; + } + + // ... +} + + public class MovieRecommender { + + private String defaultLocale; + + private CustomerPreferenceDao customerPreferenceDao; + + @Autowired + public MovieRecommender(CustomerPreferenceDao customerPreferenceDao, + @Value("#{ systemProperties['user.region'] } String defaultLocale) { + this.customerPreferenceDao = customerPreferenceDao; + this.defaultLocale = defaultLocale; + } + + // ... +} +
+
+ +
+ Language Reference + + + +
+ Literal expressions + + blah blah +
+ +
+ Properties, Arrays, Lists, Dictionaries, Indexers + + blah blah +
+ +
+ Methods + + blah blah varargs +
+ +
+ Operators + + blah blah + +
+ Relational operators + + blah blah + + +
+ +
+ Logical operators + + + + +
+ +
+ Mathematical operators + + blah blah + + +
+
+ +
+ Assignment + + blah blah + + +
+ +
+ Types + + blah blah +
+ +
+ Constructors + + blah blah +
+ +
+ Variables + + blah blah + +
+ The #this and #root variables + + blah blah +
+
+ +
+ Functions + + blah blah +
+ +
+ Expression templating + + blah blah +
+
+ +
+ Classes used in the examples + + +
+ \ No newline at end of file diff --git a/spring-framework-reference/src/spring-framework-reference.xml b/spring-framework-reference/src/spring-framework-reference.xml index 593c8361d0..98c63a348c 100644 --- a/spring-framework-reference/src/spring-framework-reference.xml +++ b/spring-framework-reference/src/spring-framework-reference.xml @@ -7,6 +7,7 @@ + @@ -196,6 +197,9 @@ + + + @@ -210,6 +214,7 @@ &beans; &resources; &validation; + &expressions; &aop; &aop-api; &testing; -- GitLab