Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs on DispatcherServlet config and processing

Browse Source 
Issue: SPR-15149
This commit is contained in:
Rossen Stoyanchev
2017-08-18 19:05:41 +02:00
parent 940a344a73
commit dabb02d830
1 changed files with 45 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
src/docs/asciidoc/web/web-mvc.adoc
View File

@@ -196,12 +196,15 @@ And the `web.xml` equivalent:
[[mvc-servlet-special-bean-types]] [[mvc-servlet-special-bean-types]]
=== Special Bean Types In the WebApplicationContext === Special Bean Types In the WebApplicationContext
The `DispatcherServlet` uses special beans to process requests and render the The `DispatcherServlet` delegates to special beans to process requests and render the
appropriate views. These beans are part of Spring MVC. You can choose which special appropriate responses. By "special beans" we mean Spring-managed Object instances that
beans to use by simply configuring one or more of them in the `WebApplicationContext`. implement specific framework contracts listed in the table further below in this section.
However, you don't need to do that initially since Spring MVC maintains a list of Spring MVC provides built-in implementations of these contracts so all you
default beans to use if you don't configure any. More on that in the next section. First need to do is configure them in your Spring configuration. It is however possible to
see the table below listing the special bean types the `DispatcherServlet` relies on. customize, extend, or completely replace those built-in implementations.
The table below lists special bean types the `DispatcherServlet` depends on
and delegates to.
[[mvc-webappctx-special-beans-tbl]] [[mvc-webappctx-special-beans-tbl]]
.Special bean types in the WebApplicationContext .Special bean types in the WebApplicationContext
@@ -209,33 +212,35 @@ see the table below listing the special bean types the `DispatcherServlet` relie
| Bean type| Explanation | Bean type| Explanation
| <<mvc-handlermapping,HandlerMapping>> | <<mvc-handlermapping,HandlerMapping>>
| Maps incoming requests to handlers and a list of pre- and post-processors (handler | Map a request to a handler along with a list of `HandlerInterceptor`s for
interceptors) based on some criteria the details of which vary by `HandlerMapping` pre- and post-processing. The mapping is based on some criteria the details of
implementation. The most popular implementation supports annotated controllers but which vary by `HandlerMapping` implementation. The most popular implementation
other implementations exists as well. supports annotated controllers but other implementations exists as well.
| HandlerAdapter | HandlerAdapter
| Helps the `DispatcherServlet` to invoke a handler mapped to a request regardless of | Helps the `DispatcherServlet` to invoke a handler mapped to a request regardless of
the handler is actually invoked. For example, invoking an annotated controller how the handler is actually invoked. For example, invoking an annotated controller
requires resolving various annotations. Thus the main purpose of a `HandlerAdapter` is requires resolving various annotations. The main purpose of a `HandlerAdapter` is
to shield the `DispatcherServlet` from such details. to shield the `DispatcherServlet` from such details.
| <<mvc-exceptionhandlers,HandlerExceptionResolver>> | <<mvc-exceptionhandlers,HandlerExceptionResolver>>
| Maps exceptions to views also allowing for more complex exception handling code. | Strategy to resolve exceptions possibly mapping them to handlers, or to HTML error
views, or other.
| <<mvc-viewresolver,ViewResolver>> | <<mvc-viewresolver,ViewResolver>>
| Resolves logical String-based view names to actual `View` types. | Resolves logical String-based view names returned from a handler to an actual `View`
to render to the response with.
| <<mvc-localeresolver,LocaleResolver>> & <<mvc-timezone,LocaleContextResolver>> | <<mvc-localeresolver,LocaleResolver>> & <<mvc-timezone,LocaleContextResolver>>
| Resolves the locale a client is using and possibly their time zone, in order to be able | Resolves the `Locale` a client is using and possibly their time zone, in order to be able
to offer internationalized views to offer internationalized views
| <<mvc-themeresolver,ThemeResolver>> | <<mvc-themeresolver,ThemeResolver>>
| Resolves themes your web application can use, for example, to offer personalized layouts | Resolves themes your web application can use, for example, to offer personalized layouts
| <<mvc-multipart,MultipartResolver>> | <<mvc-multipart,MultipartResolver>>
| Parses multi-part requests for example to support processing file uploads from HTML | Abstraction for parsing a multi-part request (e.g. browser form file upload) with
forms. the help of some multipart parsing library.
| <<mvc-flash-attributes,FlashMapManager>> | <<mvc-flash-attributes,FlashMapManager>>
| Stores and retrieves the "input" and the "output" `FlashMap` that can be used to pass | Stores and retrieves the "input" and the "output" `FlashMap` that can be used to pass
@@ -245,35 +250,31 @@ see the table below listing the special bean types the `DispatcherServlet` relie
[[mvc-servlet-config]] [[mvc-servlet-config]]
=== Default DispatcherServlet Configuration === `DispatcherServlet` Configuration
As mentioned in the previous section for each special bean the `DispatcherServlet` There are more than one ways to actually configure the `DispatcherServlet` with the special
maintains a list of implementations to use by default. This information is kept in the bean types listed in the previous section.
file `DispatcherServlet.properties` in the package `org.springframework.web.servlet`.
All special beans have some reasonable defaults of their own. Sooner or later though If there are no beans of a given type in the `WebApplicationContext` by default the
you'll need to customize one or more of the properties these beans provide. For example `DispatcherServlet` will refer to a list of default implementations to use in the file
it's quite common to configure an `InternalResourceViewResolver` settings its `prefix` https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[DispatcherServlet.properties].
property to the parent location of view files.
Regardless of the details, the important concept to understand here is that once Applications can explicitly declare the special beans to use to take over the defaults.
you configure a special bean such as an `InternalResourceViewResolver` in your However for most applications the MVC Java config or the MVC XML namespace are the
`WebApplicationContext`, you effectively override the list of default implementations best starting point. Each creates the necessary Spring configuration for the
that would have been used otherwise for that special bean type. For example if you `DispatcherServlet` and also provide a higher-level API to configure Spring MVC without
configure an `InternalResourceViewResolver`, the default list of `ViewResolver` having to understand all the details. See <<mvc-config>> for more details.
implementations is ignored.
In <<mvc-config>> you'll learn about other options for configuring Spring MVC including [NOTE]
MVC Java config and the MVC XML namespace both of which provide a simple starting point ====
and assume little knowledge of how Spring MVC works. Regardless of how you choose to Spring Boot uses the MVC Java config to configure Spring MVC and provides many
configure your application, the concepts explained in this section are fundamental and extra options and conveniences on top.
should be of help to you. ====
[[mvc-servlet-sequence]] [[mvc-servlet-sequence]]
=== DispatcherServlet Processing Sequence === DispatcherServlet Processing Sequence
After you set up a `DispatcherServlet`, and a request comes in for that specific The `DispatcherServlet` processes requests as follows:
`DispatcherServlet`, the `DispatcherServlet` starts processing the request as follows:
* The `WebApplicationContext` is searched for and bound in the request as an attribute * The `WebApplicationContext` is searched for and bound in the request as an attribute
that the controller and other elements in the process can use. It is bound by default that the controller and other elements in the process can use. It is bound by default
@@ -289,14 +290,16 @@ After you set up a `DispatcherServlet`, and a request comes in for that specific
information about multipart handling. information about multipart handling.
* An appropriate handler is searched for. If a handler is found, the execution chain * An appropriate handler is searched for. If a handler is found, the execution chain
associated with the handler (preprocessors, postprocessors, and controllers) is associated with the handler (preprocessors, postprocessors, and controllers) is
executed in order to prepare a model or rendering. executed in order to prepare a model or rendering. Or alternatively for annotated
controllers, the response may be rendered (within the `HandlerAdapter`) instead of
returning a view.
* If a model is returned, the view is rendered. If no model is returned, (may be due to * If a model is returned, the view is rendered. If no model is returned, (may be due to
a preprocessor or postprocessor intercepting the request, perhaps for security a preprocessor or postprocessor intercepting the request, perhaps for security
reasons), no view is rendered, because the request could already have been fulfilled. reasons), no view is rendered, because the request could already have been fulfilled.
Handler exception resolvers that are declared in the `WebApplicationContext` pick up The `HandlerExceptionResolver` beans declared in the `WebApplicationContext` are used to
exceptions that are thrown during processing of the request. Using these exception resolve exceptions thrown during request processing. Those exception resolvers allow
resolvers allows you to define custom behaviors to address exceptions. customizing the logic to address exceptions. See <<mvc-exceptionhandlers>> for more details.
The Spring `DispatcherServlet` also supports the return of the The Spring `DispatcherServlet` also supports the return of the
__last-modification-date__, as specified by the Servlet API. The process of determining __last-modification-date__, as specified by the Servlet API. The process of determining