diff --git a/spring-framework-reference/src/expressions.xml b/spring-framework-reference/src/expressions.xml
new file mode 100644
index 00000000000..644030f0934
--- /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 593c8361d0b..98c63a348cb 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;