diff --git a/spring-framework-reference/src/mvc.xml b/spring-framework-reference/src/mvc.xml index 8b2ce8e70e1..083b57ca5eb 100644 --- a/spring-framework-reference/src/mvc.xml +++ b/spring-framework-reference/src/mvc.xml @@ -1399,8 +1399,8 @@ public class EditPetForm { JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 - The following code sample allows you to easily get the value of - the "JSESSIONID"cookie: + The following code sample demonstrates how to get the value of + the JSESSIONID cookie: @RequestMapping("/displayHeaderInfo.do") public void displayHeaderInfo(@CookieValue("JSESSIONID") String cookie) { @@ -1420,7 +1420,7 @@ public void displayHeaderInfo(@CookieValue("JSESSIONID")The @RequestHeader annotation allows a method parameter to be bound to a request header. - Here is a request header sample: + Here is a sample request header: Host localhost:8080 @@ -1431,12 +1431,12 @@ Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 Keep-Alive 300 - The following code sample allows you to easily get the value of - the "Accept-Encoding" and "Keep-Alive" headers: + The following code sample demonstrates how to get the value of + the Accept-Encoding and Keep-Alive headers: @RequestMapping("/displayHeaderInfo.do") - public void displayHeaderInfo(@RequestHeader("Accept-Encoding") String encoding, - @RequestHeader("Keep-Alive") long keepAlive) { +public void displayHeaderInfo(@RequestHeader("Accept-Encoding") String encoding, + @RequestHeader("Keep-Alive") long keepAlive) { //... @@ -1464,7 +1464,7 @@ Keep-Alive 300 @InitBinder allows you to configure web data binding directly within your controller class. @InitBinder identifies methods that - initialize the WebDataBinder, which will be + initialize the WebDataBinder that will be used to populate command and form object arguments of annotated handler methods. @@ -1538,66 +1538,88 @@ public class MyFormController { DefaultAnnotationHandlerMapping, which looks for @RequestMapping annotations on @Controllers. Typically, you do not need to - override this default mapping, except when overriding the properties. + override this default mapping, unless you need to override the default property values. These properties are: - - - interceptors: List of interceptors to use. - HandlerInterceptors are discussed in - . - + + + interceptors + + + List of interceptors to use. + HandlerInterceptors are discussed in + . + + + - - defaultHandler: Default handler to use, when - this handler mapping does not result in a matching handler. - + + defaultHandler + + Default handler to use, when this handler mapping does not result + in a matching handler. + + - - order: Based on the value of the order - property (see the org.springframework.core.Ordered - interface), Spring sorts all handler mappings available in the context - and applies the first matching handler. - + + order + + + Based on the value of the order property (see the + org.springframework.core.Ordered + interface), Spring sorts all handler mappings available in the context + and applies the first matching handler. + + + - - alwaysUseFullPath: If - true, Spring uses the full path within the current - servlet context to find an appropriate handler. If - false (the default), the path within the current - servlet mapping is used. For example, if a servlet is mapped using - /testing/* and the - alwaysUseFullPath property is set to true, - /testing/viewPage.html is used, whereas if the - property is set to false, /viewPage.html is - used. - + + alwaysUseFullPath + + + If true , Spring uses the full path within the current + servlet context to find an appropriate handler. If false + (the default), the path within the current servlet mapping is used. For + example, if a servlet is mapped using /testing/* + and the alwaysUseFullPath property is set to true, + /testing/viewPage.html is used, whereas if the + property is set to false, /viewPage.html is used. + + + - - urlDecode: Defaults to - true, as of Spring 2.5. If - you prefer to compare encoded paths, switch this flag to - false. However, the - HttpServletRequest always exposes the - servlet path in decoded form. Be aware that the servlet path will not - match when compared with encoded paths. - + + urlDecode + + + Defaults to true, as of Spring 2.5. + If you prefer to compare encoded paths, set this flag to false. + However, the HttpServletRequest always exposes the + servlet path in decoded form. Be aware that the servlet path will not match when + compared with encoded paths. + + + - - lazyInitHandlers: Allows lazy initialization - of singleton handlers (prototype handlers are - always lazy-initialized). The default value is - false. - - + + lazyInitHandlers + + + Allows lazy initialization of singleton + handlers (prototype handlers are always lazy-initialized). + The default value is false. + + + + - - The - alwaysUseFullPath,urlDecode, and - lazyInitHandlers properties are only available to - subclasses of - org.springframework.web.servlet.handler.AbstractUrlHandlerMapping. - + + + The alwaysUseFullPath, urlDecode, and + lazyInitHandlers properties are only available to subclasses of + org.springframework.web.servlet.handler.AbstractUrlHandlerMapping. + + The following example shows how to override the default mapping and add an interceptor: @@ -1633,7 +1655,7 @@ public class MyFormController { The preHandle(..) method returns a boolean value. You can use this method to break or continue the processing of the execution chain. When this method returns true, - the handler execution chain will continue, when it returns false, the + the handler execution chain will continue; when it returns false, the DispatcherServlet assumes the interceptor itself has taken care of requests (and, for example, rendered an appropriate view) and does not continue executing the other interceptors and the @@ -1732,10 +1754,12 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { Resolving views with the <interfacename>ViewResolver</interfacename> interface - As discussed in , all controllers - in the Spring Web MVC framework return a - ModelAndView instance. Views in Spring are - addressed by a view name and are resolved by a view resolver. Spring + As discussed in , all handler + methods in the Spring Web MVC controllers must resolve to a logical + view name, either explicitly (e.g., by returning a String, + View, or ModelAndView) or implicitly + (i.e., based on conventions). Views in Spring are + addressed by a logical view name and are resolved by a view resolver. Spring comes with quite a few view resolvers. This table lists most of them; a couple of examples follow. @@ -1791,9 +1815,9 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { Simple implementation of the ViewResolver interface that - effects the direct resolution of symbolic view names to URLs, + effects the direct resolution of logical view names to URLs, without an explicit mapping definition. This is appropriate if - your symbolic names match the names of your view resources in a + your logical names match the names of your view resources in a straightforward manner, without the need for arbitrary mappings. @@ -1801,10 +1825,10 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { InternalResourceViewResolver - Convenience subclass of + Convenient subclass of UrlBasedViewResolver that supports InternalResourceView (in effect, Servlets - and JSPs), and subclasses such as + and JSPs) and subclasses such as JstlView and TilesView. You can specify the view class for all views generated by this resolver by using @@ -1817,7 +1841,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { VelocityViewResolver / FreeMarkerViewResolver - Convenience subclass of + Convenient subclass of UrlBasedViewResolver that supports VelocityView (in effect, Velocity templates) or FreeMarkerView @@ -1849,7 +1873,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { <property name="suffix" value=".jsp"/> </bean> - When returning test as a viewname, this view + When returning test as a logical view name, this view resolver forwards the request to the RequestDispatcher that will send the request to /WEB-INF/jsp/test.jsp. @@ -1876,7 +1900,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { Subclasses of AbstractCachingViewResolver cache view instances that they resolve. Caching improves performance - of certain view technologies. It's possible to turn off the cache, by + of certain view technologies. It's possible to turn off the cache by setting the cache property to false. Furthermore, if you must refresh a certain view at runtime (for example when a Velocity template is modified), @@ -1892,12 +1916,12 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { resolvers and, for example, override specific views in certain circumstances. You chain view resolvers by adding more than one resolver to your application context and, if necessary, by setting the - order property to specify an order. Remember, the + order property to specify ordering. Remember, the higher the order property, the later the view resolver is positioned in the chain. In the following example, the chain of view resolvers consists of - two resolvers, a InternalResourceViewResolver, + two resolvers, an InternalResourceViewResolver, which is always automatically positioned as the last resolver in the chain, and an XmlViewResolver for specifying Excel views. Excel views are not supported by the @@ -1923,7 +1947,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { If a specific view resolver does not result in a view, Spring examines the context for other view resolvers. If additional view resolvers exist, Spring continues to inspect them. If - they do not, it throws an Exception. + they do not exist, Spring throws an Exception. The contract of a view resolver specifies that a view resolver can return null to indicate the view could not be @@ -1950,30 +1974,32 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { view name, which a view resolver resolves to a particular view technology. For view technologies such as JSPs that are processed through the Servlet or JSP engine, this resolution is usually handled - through InternalResourceViewResolver / + through the combination of InternalResourceViewResolver and InternalResourceView, which - issues an internal forward or include, through the Servlet API's - RequestDispatcher.forward(..) or - RequestDispatcher.include(). For other view + issues an internal forward or include via the Servlet API's + RequestDispatcher.forward(..) method or + RequestDispatcher.include() method. For other view technologies, such as Velocity, XSLT, and so on, the view itself - produces the content on the response stream. + writes the content directly to the response stream. It is sometimes desirable to issue an HTTP redirect back to the - client, before the view is rendered. This is desirable for example when + client, before the view is rendered. This is desirable, for example, when one controller has been called with POSTed data, and the response is actually a delegation to another controller (for example on a successful form submission). In this case, a normal internal - forward will mean the other controller will also see the same + forward will mean that the other controller will also see the same POST data, which is potentially problematic if it can - confuse it with other expected data. Another reason to do a redirect - before displaying the result is that this will eliminate the possibility - of the user doing a double submission of form data. The browser will - have sent the initial POST, will have seen a redirect - back and done a subsequent GET because of that, and - thus as far as it is concerned, the current page does not reflect the - result of a POST, but rather of a - GET, so there is no way the user can accidentally - re-POST the same data by doing a refresh. The refresh + confuse it with other expected data. Another reason to perform a redirect + before displaying the result is to eliminate the possibility + of the user submitting the form data multiple times. In this scenario, + the browser will first send an initial POST; it will + then receive a response to redirect to a different URL; and finally + the browser will perform a subsequent GET for the + URL named in the redirect response. Thus, from the perspective of the + browser, the current page does not reflect the result of a + POST but rather of a GET. The + end effect is that there is no way the user can accidentally + re-POST the same data by performing a refresh. The refresh forces a GET of the result page, not a resend of the initial POST data. @@ -1989,12 +2015,12 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { instructs the view to do its work. The RedirectView issues an - HttpServletResponse.sendRedirect() call, which - comes back to the client browser as an HTTP redirect. All - model attributes are exposed as HTTP query parameters. This does mean + HttpServletResponse.sendRedirect() call that + returns to the client browser as an HTTP redirect. All + model attributes are exposed as HTTP query parameters. This means that the model must contain only objects (generally Strings or - convertible to Strings), which can be readily converted to a - string-form HTTP query parameter. + objects converted to a String representation), which can be readily converted to a + textual HTTP query parameter. If you use RedirectView and the view is created by the controller itself, it is recommended that you configure @@ -2008,18 +2034,18 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { The <literal>redirect:</literal> prefix While the use of RedirectView works fine, - if the controller itself is creating the - RedirectView, there is no getting around the + if the controller itself creates the + RedirectView, there is no avoiding the fact that the controller is aware that a redirection is happening. This is really suboptimal and couples things too tightly. The controller should not really care about how the response gets - handled. In general it should operate only in terms of view names that + handled. In general it should operate only in terms of view names that have been injected into it. The special redirect: prefix allows you to accomplish this. If a view name is returned that has the prefix - redirect:, then UrlBasedViewResolver (and all - subclasses) recognize this as a special indication that a redirect is + redirect:, the UrlBasedViewResolver (and all + subclasses) will recognize this as a special indication that a redirect is needed. The rest of the view name will be treated as the redirect URL. @@ -2029,7 +2055,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { such as redirect:/my/response/controller.html will redirect relative to the current servlet context, while a name such as redirect:http://myhost.com/some/arbitrary/path.html - will redirect to an absolute URL. The important thing is that as long + will redirect to an absolute URL. The important thing is that, as long as this redirect view name is injected into the controller like any other logical view name, the controller is not even aware that redirection is happening. @@ -2040,12 +2066,12 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { It is also possible to use a special forward: prefix for view names that are ultimately resolved by - UrlBasedViewResolver and subclasses. All this - does is create an InternalResourceView (which + UrlBasedViewResolver and subclasses. This + creates an InternalResourceView (which ultimately does a RequestDispatcher.forward()) around the rest of the view name, which is considered a URL. Therefore, this prefix is not useful with - InternalResourceViewResolver / + InternalResourceViewResolver and InternalResourceView (for JSPs for example). But the prefix can be helpful when you are primarily using another view technology, but still want to force a forward of a resource to be @@ -2053,7 +2079,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { multiple view resolvers, instead.) As with the redirect: prefix, if the view - name with the prefix is just injected into the controller, the + name with the forward: prefix is injected into the controller, the controller does not detect that anything special is happening in terms of handling the response. @@ -2063,7 +2089,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { <classname>ContentNegotiatingViewResolver</classname> The ContentNegotiatingViewResolver does not - resolve views itself, but rather delegates to other view resolvers, + resolve views itself but rather delegates to other view resolvers, selecting the view that resembles the representation requested by the client. Two strategies exist for a client to request a representation from the server: @@ -2088,7 +2114,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { types that it understands. For example, an HTTP request for http://www.example.com/users/fred with an Accept header set to application/pdf - requests a PDF representation of the user fred while + requests a PDF representation of the user fred, while http://www.example.com/users/fred with an Accept header set to text/xml requests an XML representation. This strategy is known as - One issue with the Accept header is that is impossible to change - it in a web browser, in HTML. For example, in Firefox, it is fixed - to + One issue with the Accept header is that it is + impossible to set it in a web browser within HTML. For example, in Firefox, it is fixed + to: + - Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 - + Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 For this reason it is common to see the use of a distinct URI - for each representation. + for each representation when developing browser based web applications. To support multiple representations of a resource, Spring provides the ContentNegotiatingViewResolver to resolve a view based on the file extension or Accept header of the HTTP request. ContentNegotiatingViewResolver - does not perform the view resolution itself, but instead delegates to a + does not perform the view resolution itself but instead delegates to a list of view resolvers that you specify through the bean property ViewResolvers. @@ -2129,10 +2155,10 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { example text/*, in which case a View whose Context-Type was text/xml is a compatible match. - To support the resolution of a view based on a file extension, you + To support the resolution of a view based on a file extension, use the ContentNegotiatingViewResolver bean - property MediaTypes to specify a mapping of file - extensions to media types. For more information on the algorithm to + property mediaTypes to specify a mapping of file + extensions to media types. For more information on the algorithm used to determine the request media type, refer to the API documentation for ContentNegotiatingViewResolver. @@ -2161,7 +2187,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { <bean id="content" class="com.springsource.samples.rest.SampleContentAtomView"/> The InternalResourceViewResolver handles - the translation of view names and JSP pages while the + the translation of view names and JSP pages, while the BeanNameViewResolver returns a view based on the name of a bean. (See "Resolving views with the @@ -2172,22 +2198,22 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { feed. For more information on creating an Atom Feed representation, see the section Atom Views. - In this configuration, if a request is made with an .html - extension, the view resolver looks for a view that matches the text/html + In the above configuration, if a request is made with an .html + extension, the view resolver looks for a view that matches the text/html media type. The InternalResourceViewResolver - provides the matching view for text/html. If the request is made with - the file extension .atom, the view resolver looks for a view that - matches the application/atom+xml media type. This view is provided by + provides the matching view for text/html. If the request is made with + the file extension .atom, the view resolver looks for a view that + matches the application/atom+xml media type. This view is provided by the BeanNameViewResolver that maps to the SampleContentAtomView if the view name returned is content. Alternatively, client requests can be - made without a file extension and setting the Accept header to the - preferred media-type and the same resolution of request to views would + made without a file extension but with the Accept header set to the + preferred media-type, and the same resolution of request to views would occur. If ContentNegotiatingViewResolver's list - of ViewResolvers is not configured explicitly, then it automatically + of ViewResolvers is not configured explicitly, it automatically uses any ViewResolvers defined in the application context. @@ -2195,22 +2221,22 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { for a URI of the form http://localhost/content.atom or http://localhost/content with an Accept header of application/atom+xml is shown - below + below. @Controller - public class ContentController { +public class ContentController { - private List<SampleContent> contentList = new ArrayList<SampleContent>(); + private List<SampleContent> contentList = new ArrayList<SampleContent>(); - @RequestMapping(value="/content", method=RequestMethod.GET) - public ModelAndView getContent() { - ModelAndView mav = new ModelAndView(); - mav.setViewName("content"); - mav.addObject("sampleContentList", contentList); - return mav; - } + @RequestMapping(value="/content", method=RequestMethod.GET) + public ModelAndView getContent() { + ModelAndView mav = new ModelAndView(); + mav.setViewName("content"); + mav.addObject("sampleContentList", contentList); + return mav; + } - } +} @@ -2224,19 +2250,19 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { LocaleResolver objects. When a request comes in, the - DispatcherServlet looks for a locale resolver and + DispatcherServlet looks for a locale resolver, and if it finds one it tries to use it to set the locale. Using the RequestContext.getLocale() method, you can always retrieve the locale that was resolved by the locale resolver. - Besides the automatic locale resolution, you can also attach an + In addition to automatic locale resolution, you can also attach an interceptor to the handler mapping (see for more information on - handler mapping interceptors), to change the locale under specific - circumstances, based on a parameter in the request, for example. + handler mapping interceptors) to change the locale under specific + circumstances, for example, based on a parameter in the request. - Locale resolvers and interceptors are all defined in the - org.springframework.web.servlet.i18n package, and are + Locale resolvers and interceptors are defined in the + org.springframework.web.servlet.i18n package and are configured in your application context in the normal way. Here is a selection of the locale resolvers included in Spring. @@ -2245,7 +2271,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { This locale resolver inspects the accept-language header in the request that was sent - by the browser of the client. Usually this header field contains the + by the client (e.g., a web browser). Usually this header field contains the locale of the client's operating system. @@ -2253,11 +2279,10 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { <classname>CookieLocaleResolver</classname> This locale resolver inspects a Cookie that - might exist on the client, to see if a locale is specified. If so, it - uses that specific locale. Using the properties of this locale resolver, - you can specify the name of the cookie, as well as the maximum age. Find - below an example of defining a - CookieLocaleResolver. + might exist on the client to see if a locale is specified. If so, it + uses the specified locale. Using the properties of this locale resolver, + you can specify the name of the cookie as well as the maximum age. Find + below an example of defining a CookieLocaleResolver. <bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver"> @@ -2303,7 +2328,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { Integer.MAX_INT The maximum time a cookie will stay persistent on the - client. If -1 is specified, the cookie will not be persisted. It + client. If -1 is specified, the cookie will not be persisted; it will only be available until the client shuts down his or her browser. @@ -2314,9 +2339,8 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { / Limits the visibility of the cookie to a certain part of - your site.. When cookiePath is - specified, the cookie will only be visible to that path, and the - paths below it. + your site. When cookiePath is specified, the cookie will only + be visible to that path and the paths below it. @@ -2334,7 +2358,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter {
<classname>LocaleChangeInterceptor</classname> - You can build in changing of locales by adding the + You can enable changing of locales by adding the LocaleChangeInterceptor to one of the handler mappings (see ). It will detect a parameter in the request and change the locale. It calls @@ -2397,7 +2421,7 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { ResourceBundleThemeSource, you can register a bean in the application context with the reserved name themeSource. The web application context - automatically detects that bean and starts using it. + automatically detects a bean with that name and uses it. When using the ResourceBundleThemeSource, a theme is defined in a simple properties file. The @@ -2419,14 +2443,14 @@ background=/themes/cool/img/coolBg.jpg <head> <link rel="stylesheet" href="<spring:theme code="styleSheet"/>" type="text/css"/> </head> - <body background="<spring:theme code="background"/>"> + <body style="background=<spring:theme code="background"/>"> ... </body> </html> By default, the ResourceBundleThemeSource uses an empty base name prefix. As a result, the properties files are - loaded from the root of the classpath, so you would put the + loaded from the root of the classpath. Thus you would put the cool.properties theme definition in a directory at the root of the classpath, for example, in /WEB-INF/classes. The @@ -2485,15 +2509,14 @@ background=/themes/cool/img/coolBg.jpg CookieThemeResolver - The selected theme is stored in a cookie on the - user-agent's machine. + The selected theme is stored in a cookie on the client. Spring also provides a - ThemeChangeInterceptor, which allows theme + ThemeChangeInterceptor that allows theme changes on every request with a simple request parameter.