SPR-6464 Update reference doc with FlashMap and RedirectAttributes information.

build-spring-framework/resources/changelog.txt

@@ -52,7 +52,10 @@ Changes in version 3.1 RC1 (2011-09-xx)
 * extended Servlet API mocks for Servlet 3.0 forward compatibility as far as possible
 * made MockHttpServletResponse compatible with Servlet 3.0 getHeader(s) method returning Strings
 * added getHeaderValue(s) method to MockHttpServletResponse for raw value access
-
+* add flash attribute support through FlashMap and FlashMapManager abstractions
+* add RedirectAttributes abstraction as supported method argument type of @RequestMapping methods
+* add "ignoreDefaultModelOnRedirect" flag to RequestMappingHandlerAdapter
+* add support for @RequestPart annotated controller method arguments
 
 Changes in version 3.1 M2 (2011-06-08)
 --------------------------------------
@@ -64,17 +67,16 @@ Changes in version 3.1 M2 (2011-06-08)
 * AnnotatedBeanDefinitionReader now inherits Environment of supplied BeanDefinitionRegistry
 * eliminated @Feature support in favor of @Enable* and framework-provided @Configuration classes
 * introduced @EnableTransactionManagement, @EnableScheduling, etc
-* introduced @EnableWebMvc to provide default configuration for Spring MVC applications
+* add Java config alternative to MVC namespace via @EnableWebMvc annotation
-* introduced HandlerMethod abstraction representing a Spring MVC controller method
+* introduce HandlerMethod abstraction selecting and invoking @RequestMapping methods
-* added HandlerMapping/HandlerAdapter/HandlerExceptionResolver HandlerMethod-based implementations
+* add HandlerMethod-based implementations of HandlerMapping, HandlerAdapter, HandlerExceptionResolver
-* enabled HandlerMethod-based infrastructure through the mvc namespace and Java-based configuration
+* merge @PathVariables in the model before rendering except for JSON/XML serialization/marshalling.
-* support for automatically adding @PathVariables to the model
+* use @PathVariables in addition to request parameters in data binding
-* support for including @PathVariables in data binding
+* support URI variable placeholders in "redirect:" prefixed view names
-* support for URI template variables in view names with the "redirect:" prefix
+* add flag to extract value from single-key model in MappingJacksonJsonView
-* added a flag for extracting the value from single-key models in MappingJacksonJsonView
+* support @Valid on @RequestBody method arguments
-* added support for @Valid with @RequestBody arguments
 * allow bean references in mvc:interceptor namespace elements
-* consolidated the initialization and use of MappedInterceptors in AbstractHandlerMapping
+* consolidate initialization and use of MappedInterceptors in AbstractHandlerMapping
 * added Servlet 3.0 based WebApplicationInitializer mechanism for programmatic bootstrapping
 * added Servlet 3.0 based StandardServletMultipartResolver
 * added "packagesToScan" feature to LocalContainerEntityManagerFactoryBean (avoiding persistence.xml)

org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java

@@ -108,6 +108,12 @@ import java.lang.annotation.Target;
  * <li>{@link java.util.Map} / {@link org.springframework.ui.Model} /
  * {@link org.springframework.ui.ModelMap} for enriching the implicit model
  * that will be exposed to the web view.
+ * <li>{@link org.springframework.web.servlet.mvc.support.RedirectAttributes} 
+ * to specify the exact set of attributes to use in case of a redirect
+ * and also to add flash attributes (attributes stored temporarily on the 
+ * server-side to make them available to the request after the redirect).
+ * {@code RedirectAttributes} is used instead of the implicit model if the 
+ * method returns a "redirect:" prefixed view name or {@code RedirectView}.
  * <li>Command/form objects to bind parameters to: as bean properties or fields,
  * with customizable type conversion, depending on {@link InitBinder} methods
  * and/or the HandlerAdapter configuration - see the "webBindingInitializer"

spring-framework-reference/src/mvc.xml

@@ -1132,6 +1132,18 @@ public class RelativePathUriTemplateController {
               view.</para>
             </listitem>
 
+            <listitem>
+              <para>
+                <interfacename>org.springframework.web.servlet.mvc.support.RedirectAttributes</interfacename>
+                to specify the exact set of attributes to use in case of a redirect
+                and also to add flash attributes (attributes stored temporarily on
+                the server-side to make them available to the request after the redirect).
+                <literal>RedirectAttributes</literal> is used instead of the implicit
+                model if the method returns a "redirect:" prefixed view name or 
+                <classname>RedirectView</classname>.
+              </para>
+            </listitem>
+
             <listitem>
               <para>Command or form objects to bind request parameters to bean
               properties (via setters) or directly to fields, with
@@ -1697,9 +1709,56 @@ public class EditPetForm {
           </para>
         </note>
       </section>
+
+      <section id="mvc-ann-redirect-attributes">
+        <title>Specifying redirect and flash attributes</title>
+
+        <para>By default all model attributes are considered to be exposed as 
+        URI template variables in the redirect URL. Of the remaining attributes 
+        those that are primitive types or collections/arrays of primitive types 
+        are automatically appended as query parameters.
+        </para>
+        
+        <para>In annotated controllers however the model may contain 
+        additional attributes originally added for rendering 
+        purposes (e.g. drop-down field values).
+        To gain precise control over the attributes used in a redirect scenario,
+        an <interfacename>@RequestMapping</interfacename> method can declare an
+        argument of type <interfacename>RedirectAttributes</interfacename>
+        and use it to add attributes for use in <classname>RedirectView</classname>. 
+        If the controller method does redirect, the content of 
+        <interfacename>RedirectAttributes</interfacename> is used. 
+        Otherwise the content of the default <interfacename>Model</interfacename> 
+        is used.
+        </para>
+        
+        <para>
+        The <classname>RequestMappingHandlerAdapter</classname> provides a flag
+        called <literal>"ignoreDefaultModelOnRedirect"</literal> that can be 
+        used to indicate the content of the default <interfacename>Model</interfacename>
+        should never be used if a controller method redirects. 
+        Instead the controller method should declare an attribute of type
+        <interfacename>RedirectAttributes</interfacename> or if it doesn't do so
+        no attributes should be passed on to <classname>RedirectView</classname>.
+        Both the MVC namespace and the MVC Java config (via
+        <interfacename>@EnableWebMvc</interfacename>) automatically set 
+        this flag to <literal>true</literal>.
+        </para>
+        
+        <para>The <interfacename>RedirectAttributes</interfacename> interface can
+        also be used to add flash attributes. Unlike other redirect attributes, 
+        which end up in the target redirect URL, flash attributes are saved
+        in the HTTP session (and hence do not appear in the URL). The model of 
+        the controller serving the target redirect URL automatically receives
+        these flash attributes after which they are removed from the session.
+        See <xref linkend="mvc-flash-attributes"/> for an overview of the general 
+        support for flash attributes in Spring MVC.
+        </para>
+        
+      </section>
       
       <section id="mvc-ann-form-urlencoded-data">
-        <title>Working with <literal>application/x-www-form-urlencoded</literal> data</title>
+        <title>Working with <literal>"application/x-www-form-urlencoded"</literal> data</title>
 
 		<para>The previous sections covered use of <interfacename>@ModelAttribute</interfacename> 
 		to support form submission requests from browser clients. The same annotation is 
@@ -2431,24 +2490,38 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter {
         <para>The <classname>RedirectView</classname> issues an
         <literal>HttpServletResponse.sendRedirect()</literal> call that
         returns to the client browser as an HTTP redirect.
-        All model attributes are considered to be exposed as either URI template variables first, 
+        By default all model attributes are considered to be exposed as URI
-        assuming the URL is a URI template such as <code>/account/{number}</code>, 
+        template variables in the redirect URL. Of the remaining attributes 
-        or as HTTP query parameters second. By default String and primitive model attributes 
+        those that are primitive types or collections/arrays of primitive types
-        are eligible to be exposed this way. However, this behavior can be extended by 
+        are automatically appended as query parameters.
-        sub-classing RedirectView. Also consider that <code>@PathVariable</code>-annotated 
+        </para>
-        method arguments are automatically added to the model, which is convenient when 
+        
-        redirecting to the same URL using a different HTTP method. For example:</para>
+        <para>
+        Appending primitive type attributes as query parameters may be the 
+        desired result if a model instance was prepared specifically for the
+        redirect. However, in annotated controllers the model may contain 
+        additional attributes added for rendering purposes (e.g. drop-down 
+        field values). To avoid the possibility of having such attributes 
+        appear in the URL an annotated controller can declare an 
+        argument of type <interfacename>RedirectAttributes</interfacename>
+        and use it to specify the exact attributes to make available to
+        <classname>RedirectView</classname>. If the controller method decides
+        to redirect, the content of <interfacename>RedirectAttributes</interfacename> 
+        is used. Otherwise the content of the model is used.
+        </para>
+        
+        <para>
+        Note that URI template variables from the present request are automatically
+        made available when expanding a redirect URL and do not need to be added
+        explicitly neither through <interfacename>Model</interfacename> nor 
+        <interfacename>RedirectAttributes</interfacename>. For example:</para>
         
       <programlisting language="java">@RequestMapping(value = "/files/{path}", method = RequestMethod.POST)
-public String upload(@PathVariable String path, ...) {
+public String upload(...) {
     // ...
     return "redirect:files/{path}";
 }
-
+</programlisting>        
-@RequestMapping(value = "/files/{path}", method = RequestMethod.GET)
-public void get(@PathVariable String path, ...) {
-    // ...
-}</programlisting>        
 
         <para>If you use <classname>RedirectView</classname> and the view is
         created by the controller itself, it is recommended that you configure
@@ -2681,6 +2754,73 @@ public class ContentController {
     </section>
   </section>
 
+  <section id="mvc-flash-attributes">
+    <title>Using flash attributes</title>
+
+    <para>Flash attributes provide a way for one request to store attributes 
+    intended for use in another. This is most commonly needed when redirecting 
+    -- e.g. the Post/Redirect/Get pattern. Flash attributes are saved temporarily
+    before the redirect (typically in the session) to be made available to the 
+    request after the redirect and removed immediately.
+    </para>
+    
+    <para>Spring MVC has two main abstractions in support of flash attributes. 
+    <classname>FlashMap</classname> is used to hold flash attributes while 
+    <interfacename>FlashMapManager</interfacename> is used to store, retrieve, 
+    and manage <classname>FlashMap</classname> instances.
+    </para>
+    
+    <para>Flash attribute support is always "on" and does not need to enabled
+    explicitly although if not used, it never causes HTTP session creation.
+    On each request there is an "input" <classname>FlashMap</classname> with 
+    attributes passed from a previous request (if any) and an "output" 
+    <classname>FlashMap</classname> with attributes to save for a subsequent 
+    request. Both <classname>FlashMap</classname> instances are accessible
+    from anywhere in Spring MVC through static methods in
+    <classname>RequestContextUtils</classname>. 
+    </para>
+
+    <para>Annotated controllers typically do not need to work with  
+    <classname>FlashMap</classname> directly. Instead an 
+    <interfacename>@RequestMapping</interfacename> method can accept an argument
+    of type <interfacename>RedirectAttributes</interfacename> and use it to
+    add flash attributes for a redirect scenario. Flash attributes added via
+    <interfacename>RedirectAttributes</interfacename> are automatically 
+    propagated to the "output" FlashMap. Similarly after the
+    redirect attributes from the "input" <classname>FlashMap</classname> are 
+    automatically added to the <interfacename>Model</interfacename> 
+    of the controller serving the target URL.  
+    </para>
+
+    <sidebar id="mvc-flash-attributes-concurrency">
+        <title>Matching requests to flash attributes</title>
+        <para>The concept of flash attributes exists in many other Web frameworks
+        and has proven to be exposed sometimes to concurrency issues. 
+        This is because by definition flash attributes are 
+        to be stored until the next request. However the very "next" 
+        request may not be the intended recepient but another 
+        asynchronous request (e.g. polling or resource requests)
+        in which case the flash attributes are removed too early. 
+        </para>
+        
+        <para>To reduce the possibility of such issues,
+        <classname>RedirectView</classname> automatically "stamps" 
+        <classname>FlashMap</classname> instances with the path and query
+        parameters of the target redirect URL. In turn the default 
+        <classname>FlashMapManager</classname> matches that information to incoming
+        requests when looking up the "input" <classname>FlashMap</classname>.
+        </para>
+        
+        <para>This does not eliminate the possibility of a concurrency issue
+        entirely but nevertheless reducess it greatly with information 
+        that is already available in the redirect URL.
+        Therefore the use of flash attributes is recommended
+        mainly for redirect scenarios unless the target URL and/or query 
+        parameters are known.</para>
+    </sidebar>
+
+  </section>
+  
   <section id="mvc-localeresolver">
     <title>Using locales</title>
 

spring-framework-reference/src/new-in-3.1.xml

@@ -240,37 +240,65 @@
       recommended going forward.</para>
     </section>
     <section>
-      <title>Consumes and Produces <interface>@RequestMapping</interface> Conditions</title>
+      <title>"consumes" and "produces" conditions in <interface>@RequestMapping</interface></title>
       <para>Improved support for specifying media types consumed by a method through the 
       <literal>'Content-Type'</literal> header as well as for producible types specified
       through the <literal>'Accept'</literal> header.
       See <xref linkend="mvc-ann-requestmapping-consumes"/> and 
       <xref linkend="mvc-ann-requestmapping-produces"/>
       </para>
+    </section>
+    <section>
+      <title>Flash Attributes and <interfacename>RedirectAttributes</interfacename></title>
+      <para>Flash attributes can now be stored in a <classname>FlashMap</classname>
+      and saved in the HTTP session to survive a redirect. For an overview of 
+      the general support for flash attributes in Spring MVC
+      see <xref linkend="mvc-flash-attributes"/>. 
+      </para>
+      <para>
+      In annotated controllers, an <interfacename>@RequestMapping</interfacename>
+      method can add flash attributes by declaring a method argument of type
+      <interfacename>RedirectAttributes</interfacename>. This method argument
+      can now also be used to get precise control over the attributes used in
+      a redirect scenario. See <xref linkend="mvc-ann-redirect-attributes"/> 
+      for more details.
+      </para>
     </section>
 	<section>
-	  <title>Working With URI Template Variables In Controller Methods</title>
+	  <title>URI Template Variable Enhancements</title>
-	  <para>@PathVariable method arguments are now automatically added to the model. 
+      <para>URI template variables from the current request are used in more places:
-	  If you declare any <interface>@PathVariable</interface> arguments on a 
+      <itemizedlist>
-	  controller method you no longer need to add them to the model.</para>
+        <listitem>URI template variables are used in addition to request parameters 
-	  <para>Redirect view strings can now be URI templates. 
+        when binding a request to @ModelAttribute method arguments.</listitem>
-	  For example a controller can return <literal>"redirect:/blog/{year}/{month}"</literal>.
+        <listitem>@PathVariable method argument values are merged into the model 
-	  The URI template will be expanded with variables from the model, which 
+        before rendering except in views that generate content in an automated
-	  of course includes <interface>@PathVariable</interface> method arguments 
+        fashion such as JSON serialization an XML marshalling.</listitem>
-	  that are now automatically added to the model.</para>
+        <listitem>A redirect string can contain placeholders for URI variables
-	  <para>URI template variables are now included in data binding
+        (e.g. <literal>"redirect:/blog/{year}/{month}"</literal>). When expanding
-	  in addition to request parameters, which are typically used for 
+        the placeholders, URI template variables from the current request are 
-	  populating a model.</para>
+        automatically considered.</listitem>
+        <listitem>An @ModelAttribute method argument can be instantiated from
+        a URI template variable provided there is a registered Converter or
+        PropertyEditor to convert from a String to the target object type.</listitem>
+      </itemizedlist>
+      </para>
 	</section>
 	<section>
-	  <title>Validation For <interface>@RequestBody</interface> Method Arguments</title>
+	  <title><interfacename>@Valid</interfacename> On 
-	  <para>An <interface>@RequestBody</interface> method argument annotated 
+      <interface>@RequestBody</interface> Controller Method Arguments</title>
-	  with <interface>@Valid</interface> is now automatically validated with the 
+	  <para>An <interface>@RequestBody</interface> method argument 
-	  same <classname>Validator</classname> instance used to validate 
+      can be annotated with <interface>@Valid</interface> to invoke automatic
-	  an <interface>@ModelAttribute</interface> method argument.
+      validation similar to the support for 
-	  Both the MVC namespace and <interface>@EnableWebMvc</interface> 
+      <interface>@ModelAttribute</interface> method arguments.
-	  automatically configure a JSR-303 <classname>Validator</classname> adapter 
+      The resulting MethodArgumentNotValidException is handled in the 
-	  provided a JSR-303 implementation is available on the classpath.</para>
+      DefaultHandlerExceptionResolver and results in 400 response code.</para>
 	</section>
+    <section>
+        <title><interfacename>@RequestPart</interfacename> Annotation On Controller Method Arguments</title>
+        <para>This new annotation provides access to the content of a 
+        "multipart/form-data" request part.
+        See <xref linkend="mvc-multipart-forms-non-browsers" /> and
+        <xref linkend="mvc-multipart"/></para>
+    </section>
   </section>
 </chapter>