diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 352864154a1..322a939a7d3 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -3562,159 +3562,6 @@ http://hdiv.org/[HDIV] is one such framework and integrates with Spring MVC. -[[mvc-coc-modelmap]] -=== The Model ModelMap (ModelAndView) - -The `ModelMap` class is essentially a glorified `Map` that can make adding objects that -are to be displayed in (or on) a `View` adhere to a common naming convention. Consider -the following `Controller` implementation; notice that objects are added to the -`ModelAndView` without any associated name specified. - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class DisplayShoppingCartController implements Controller { - - public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) { - - List cartItems = // get a List of CartItem objects - User user = // get the User doing the shopping - - ModelAndView mav = new ModelAndView("displayShoppingCart"); <-- the logical view name - - mav.addObject(cartItems); <-- look ma, no name, just the object - mav.addObject(user); <-- and again ma! - - return mav; - } - } ----- - -The `ModelAndView` class uses a `ModelMap` class that is a custom `Map` implementation -that automatically generates a key for an object when an object is added to it. The -strategy for determining the name for an added object is, in the case of a scalar object -such as `User`, to use the short class name of the object's class. The following -examples are names that are generated for scalar objects put into a `ModelMap` instance. - -* An `x.y.User` instance added will have the name `user` generated. -* An `x.y.Registration` instance added will have the name `registration` generated. -* An `x.y.Foo` instance added will have the name `foo` generated. -* A `java.util.HashMap` instance added will have the name `hashMap` generated. You - probably want to be explicit about the name in this case because `hashMap` is less - than intuitive. -* Adding `null` will result in an `IllegalArgumentException` being thrown. If the object - (or objects) that you are adding could be `null`, then you will also want to be - explicit about the name. - -.What, no automatic pluralization? -**** -Spring Web MVC's convention-over-configuration support does not support automatic -pluralization. That is, you cannot add a `List` of `Person` objects to a `ModelAndView` -and have the generated name be `people`. - -This decision was made after some debate, with the "Principle of Least Surprise" winning -out in the end. -**** - -The strategy for generating a name after adding a `Set` or a `List` is to peek into the -collection, take the short class name of the first object in the collection, and use -that with `List` appended to the name. The same applies to arrays although with arrays -it is not necessary to peek into the array contents. A few examples will make the -semantics of name generation for collections clearer: - -* An `x.y.User[]` array with zero or more `x.y.User` elements added will have the name - `userList` generated. -* An `x.y.Foo[]` array with zero or more `x.y.User` elements added will have the name - `fooList` generated. -* A `java.util.ArrayList` with one or more `x.y.User` elements added will have the name - `userList` generated. -* A `java.util.HashSet` with one or more `x.y.Foo` elements added will have the name - `fooList` generated. -* An __empty__ `java.util.ArrayList` will not be added at all (in effect, the - `addObject(..)` call will essentially be a no-op). - - - -[[mvc-coc-r2vnt]] -=== Default view name - -The `RequestToViewNameTranslator` interface determines a logical `View` name when no -such logical view name is explicitly supplied. It has just one implementation, the -`DefaultRequestToViewNameTranslator` class. - -The `DefaultRequestToViewNameTranslator` maps request URLs to logical view names, as -with this example: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - public class RegistrationController implements Controller { - - public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) { - // process the request... - ModelAndView mav = new ModelAndView(); - // add data as necessary to the model... - return mav; - // notice that no View or logical view name has been set - } - - } ----- - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - ----- - -Notice how in the implementation of the `handleRequest(..)` method no `View` or logical -view name is ever set on the `ModelAndView` that is returned. The -`DefaultRequestToViewNameTranslator` is tasked with generating a __logical view name__ -from the URL of the request. In the case of the above `RegistrationController`, which is -used in conjunction with the `ControllerClassNameHandlerMapping`, a request URL of -`http://localhost/registration.html` results in a logical view name of `registration` -being generated by the `DefaultRequestToViewNameTranslator`. This logical view name is -then resolved into the `/WEB-INF/jsp/registration.jsp` view by the -`InternalResourceViewResolver` bean. - -[TIP] -==== -You do not need to define a `DefaultRequestToViewNameTranslator` bean explicitly. If you -like the default settings of the `DefaultRequestToViewNameTranslator`, you can rely on -the Spring Web MVC `DispatcherServlet` to instantiate an instance of this class if one -is not explicitly configured. -==== - -Of course, if you need to change the default settings, then you do need to configure -your own `DefaultRequestToViewNameTranslator` bean explicitly. Consult the comprehensive -`DefaultRequestToViewNameTranslator` javadocs for details on the various properties -that can be configured. - - - [[mvc-caching]] == HTTP Caching