Skip to content

Commit b0848db

Browse files
committed
Merge pull request #771 from dgtombs/SPR-12759
* dgtombs-SPR-12759: Improve RedirectAttributes reference docs
2 parents b119a9c + 463878a commit b0848db

File tree

1 file changed

+35
-50
lines changed

1 file changed

+35
-50
lines changed

src/asciidoc/web-mvc.adoc

Lines changed: 35 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1169,8 +1169,8 @@ multiple requests are allowed to access a session concurrently.
11691169
* `org.springframework.web.servlet.mvc.support.RedirectAttributes` to specify the exact
11701170
set of attributes to use in case of a redirect and also to add flash attributes
11711171
(attributes stored temporarily on the server-side to make them available to the
1172-
request after the redirect). `RedirectAttributes` is used instead of the implicit
1173-
model if the method returns a "redirect:" prefixed view name or `RedirectView`.
1172+
request after the redirect). See <<mvc-redirecting-passing-data>> and
1173+
<<mvc-flash-attributes>>.
11741174
* Command or form objects to bind request parameters to bean properties (via setters)
11751175
or directly to fields, with customizable type conversion, depending on `@InitBinder`
11761176
methods and/or the HandlerAdapter configuration. See the `webBindingInitializer`
@@ -1674,34 +1674,6 @@ attribute name:
16741674
}
16751675
----
16761676

1677-
[[mvc-ann-redirect-attributes]]
1678-
==== Specifying redirect and flash attributes
1679-
By default all model attributes are considered to be exposed as URI template variables
1680-
in the redirect URL. Of the remaining attributes those that are primitive types or
1681-
collections/arrays of primitive types are automatically appended as query parameters.
1682-
1683-
In annotated controllers however the model may contain additional attributes originally
1684-
added for rendering purposes (e.g. drop-down field values). To gain precise control over
1685-
the attributes used in a redirect scenario, an `@RequestMapping` method can declare an
1686-
argument of type `RedirectAttributes` and use it to add attributes for use in
1687-
`RedirectView`. If the controller method does redirect, the content of
1688-
`RedirectAttributes` is used. Otherwise the content of the default `Model` is used.
1689-
1690-
The `RequestMappingHandlerAdapter` provides a flag called
1691-
`"ignoreDefaultModelOnRedirect"` that can be used to indicate the content of the default
1692-
`Model` should never be used if a controller method redirects. Instead the controller
1693-
method should declare an attribute of type `RedirectAttributes` or if it doesn't do so
1694-
no attributes should be passed on to `RedirectView`. Both the MVC namespace and the MVC
1695-
Java config keep this flag set to `false` in order to maintain backwards compatibility.
1696-
However, for new applications we recommend setting it to `true`
1697-
1698-
The `RedirectAttributes` interface can also be used to add flash attributes. Unlike
1699-
other redirect attributes, which end up in the target redirect URL, flash attributes are
1700-
saved in the HTTP session (and hence do not appear in the URL). The model of the
1701-
controller serving the target redirect URL automatically receives these flash attributes
1702-
after which they are removed from the session. See <<mvc-flash-attributes>> for an
1703-
overview of the general support for flash attributes in Spring MVC.
1704-
17051677

17061678
[[mvc-ann-form-urlencoded-data]]
17071679
==== Working with "application/x-www-form-urlencoded" data
@@ -2694,7 +2666,7 @@ the last results in the chain not being fully inspected, because the
26942666

26952667

26962668
[[mvc-redirecting]]
2697-
=== Redirecting to views
2669+
=== Redirecting to Views
26982670
As mentioned previously, a controller typically returns a logical view name, which a
26992671
view resolver resolves to a particular view technology. For view technologies such as
27002672
JSPs that are processed through the Servlet or JSP engine, this resolution is usually
@@ -2727,22 +2699,37 @@ One way to force a redirect as the result of a controller response is for the co
27272699
to create and return an instance of Spring's `RedirectView`. In this case,
27282700
`DispatcherServlet` does not use the normal view resolution mechanism. Rather because it
27292701
has been given the (redirect) view already, the `DispatcherServlet` simply instructs the
2730-
view to do its work.
2702+
view to do its work. The `RedirectView` in turn calls `HttpServletResponse.sendRedirect()`
2703+
to send an HTTP redirect to the client browser.
2704+
2705+
If you use `RedirectView` and the view is created by the controller itself, it is
2706+
recommended that you configure the redirect URL to be injected into the controller so
2707+
that it is not baked into the controller but configured in the context along with the
2708+
view names. The <<mvc-redirecting-redirect-prefix>> facilitates this decoupling.
2709+
2710+
[[mvc-redirecting-passing-data]]
2711+
===== Passing Data To the Redirect Target
27312712

2732-
The `RedirectView` issues an `HttpServletResponse.sendRedirect()` call that returns to
2733-
the client browser as an HTTP redirect. By default all model attributes are considered
2734-
to be exposed as URI template variables in the redirect URL. Of the remaining attributes
2735-
those that are primitive types or collections/arrays of primitive types are
2736-
automatically appended as query parameters.
2713+
By default all model attributes are considered to be exposed as URI template variables in
2714+
the redirect URL. Of the remaining attributes those that are primitive types or
2715+
collections/arrays of primitive types are automatically appended as query parameters.
27372716

27382717
Appending primitive type attributes as query parameters may be the desired result if a
27392718
model instance was prepared specifically for the redirect. However, in annotated
2740-
controllers the model may contain additional attributes added for rendering purposes
2741-
(e.g. drop-down field values). To avoid the possibility of having such attributes appear
2742-
in the URL an annotated controller can declare an argument of type `RedirectAttributes`
2743-
and use it to specify the exact attributes to make available to `RedirectView`. If the
2744-
controller method decides to redirect, the content of `RedirectAttributes` is used.
2745-
Otherwise the content of the model is used.
2719+
controllers the model may contain additional attributes added for rendering purposes (e.g.
2720+
drop-down field values). To avoid the possibility of having such attributes appear in the
2721+
URL, an `@RequestMapping` method can declare an argument of type `RedirectAttributes` and
2722+
use it to specify the exact attributes to make available to `RedirectView`. If the method
2723+
does redirect, the content of `RedirectAttributes` is used. Otherwise the content of the
2724+
model is used.
2725+
2726+
The `RequestMappingHandlerAdapter` provides a flag called
2727+
`"ignoreDefaultModelOnRedirect"` that can be used to indicate the content of the default
2728+
`Model` should never be used if a controller method redirects. Instead the controller
2729+
method should declare an attribute of type `RedirectAttributes` or if it doesn't do so
2730+
no attributes should be passed on to `RedirectView`. Both the MVC namespace and the MVC
2731+
Java config keep this flag set to `false` in order to maintain backwards compatibility.
2732+
However, for new applications we recommend setting it to `true`
27462733

27472734
Note that URI template variables from the present request are automatically made
27482735
available when expanding a redirect URL and do not need to be added explicitly neither
@@ -2758,11 +2745,9 @@ through `Model` nor `RedirectAttributes`. For example:
27582745
}
27592746
----
27602747

2761-
If you use `RedirectView` and the view is created by the controller itself, it is
2762-
recommended that you configure the redirect URL to be injected into the controller so
2763-
that it is not baked into the controller but configured in the context along with the
2764-
view names. The next section discusses this process.
2765-
2748+
Another way of passing data to the redirect target is via __Flash Attributes__. Unlike
2749+
other redirect attributes, flash attributes are saved in the HTTP session (and hence do
2750+
not appear in the URL). See <<mvc-flash-attributes>> for more information.
27662751

27672752
[[mvc-redirecting-redirect-prefix]]
27682753
==== The redirect: prefix
@@ -2967,8 +2952,8 @@ are accessible from anywhere in Spring MVC through static methods in
29672952
Annotated controllers typically do not need to work with `FlashMap` directly. Instead an
29682953
`@RequestMapping` method can accept an argument of type `RedirectAttributes` and use it
29692954
to add flash attributes for a redirect scenario. Flash attributes added via
2970-
`RedirectAttributes` are automatically propagated to the "output" FlashMap. Similarly
2971-
after the redirect attributes from the "input" `FlashMap` are automatically added to the
2955+
`RedirectAttributes` are automatically propagated to the "output" FlashMap. Similarly,
2956+
after the redirect, attributes from the "input" `FlashMap` are automatically added to the
29722957
`Model` of the controller serving the target URL.
29732958

29742959
.Matching requests to flash attributes

0 commit comments

Comments
 (0)