org.springframework.web.servlet Documentation Differences

This file contains all the changes in documentation in the package org.springframework.web.servlet as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Central dispatcher for HTTP request handlers/controllers, e.g. for web UI controllers or HTTP-based remote service exporters. Dispatches to registered handlers for processing a web request, providing convenient mapping and exception handling facilities.

This servlet is very flexible: It can be used with just about any workflow, with the installation of the appropriate adapter classes. It offers the following functionality that distinguishes it from other request-driven web MVC frameworks:

• It is based around a JavaBeans configuration mechanism.
• It can use any HandlerMapping implementation - pre-built or provided as part of an application - to control the routing of requests to handler objects. Default is org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping and org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping. HandlerMapping objects can be defined as beans in the servlet's application context, implementing the HandlerMapping interface, overriding the default HandlerMapping if present. HandlerMappings can be given any bean name (they are tested by type).
• It can use any HandlerAdapter; this allows for using any handler interface. Default adapters are org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter, org.springframework.web.servlet.mvc.SimpleControllerHandlerAdapter, for Spring's org.springframework.web.HttpRequestHandler and org.springframework.web.servlet.mvc.Controller interfaces, respectively. A default org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter will be registered as well. HandlerAdapter objects can be added as beans in the application context, overriding the default HandlerAdapters. Like HandlerMappings, HandlerAdapters can be given any bean name (they are tested by type).
• The dispatcher's exception resolution strategy can be specified via a HandlerExceptionResolver, for example mapping certain exceptions to error pages. Default are org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver, org.springframework.web.servlet.mvc.annotation.ResponseStatusExceptionResolver, and org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver. These HandlerExceptionResolvers can be overridden through the application context. HandlerExceptionResolver can be given any bean name (they are tested by type).
• Its view resolution strategy can be specified via a ViewResolver implementation, resolving symbolic view names into View objects. Default is org.springframework.web.servlet.view.InternalResourceViewResolver. ViewResolver objects can be added as beans in the application context, overriding the default ViewResolver. ViewResolvers can be given any bean name (they are tested by type).
• If a View or view name is not supplied by the user, then the configured RequestToViewNameTranslator will translate the current request into a view name. The corresponding bean name is "viewNameTranslator"; the default is org.springframework.web.servlet.view.DefaultRequestToViewNameTranslator.
• The dispatcher's strategy for resolving multipart requests is determined by a org.springframework.web.multipart.MultipartResolver implementation. Implementations for Jakarta Commons FileUpload and Jason Hunter's COS are included; the typical choise is org.springframework.web.multipart.commons.CommonsMultipartResolver. The MultipartResolver bean name is "multipartResolver"; default is none.
• Its locale resolution strategy is determined by a LocaleResolver. Out-of-the-box implementations work via HTTP accept header, cookie, or session. The LocaleResolver bean name is "localeResolver"; default is org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver.
• Its theme resolution strategy is determined by a ThemeResolver. Implementations for a fixed theme and for cookie and session storage are included. The ThemeResolver bean name is "themeResolver"; default is org.springframework.web.servlet.theme.FixedThemeResolver.

NOTE: The @RequestMapping annotation will only be processed if a corresponding HandlerMapping (for type level annotations) and/or HandlerAdapter (for method level annotations) is present in the dispatcher. This is the case by default. However, if you are defining custom HandlerMappings or HandlerAdapters, then you need to make sure that a corresponding custom DefaultAnnotationHandlerMapping and/or AnnotationMethodHandlerAdapter is defined as well - provided that you intend to use @RequestMapping.

A web application can define any number of DispatcherServlets. Each servlet will operate in its own namespace, loading its own application context with mappings, handlers, etc. Only the root application context as loaded by org.springframework.web.context.ContextLoaderListener, if any, will be shared.

As of Spring 3.1, {@code DispatcherServlet} may now be injected with a web application context, rather than creating its own internally. This is useful in Servlet 3.0+ environments, which support programmatic registration of servlet instances. See .DispatcherServlet(WebApplicationContext) Javadoc for details. @author Rod Johnson @author Juergen Hoeller @author Rob Harrop @author Chris Beams @author Rossen Stoyanchev @see org.springframework.web.HttpRequestHandler @see org.springframework.web.servlet.mvc.Controller @see org.springframework.web.context.ContextLoaderListener

Clean up any resources used by the given multipart request (if any). @param requestservletRequest current HTTP request @see MultipartResolver#cleanupMultipart

A FlashMap provides a way for one request to store attributes intended for for use in another. This is most commonly needed when redirecting from one URL to another -- e.g. the Post/Redirect/Get pattern. A FlashMap is saved before before the redirect (typically in the session) and is made available after the the redirect and removed immediately.

A FlashMap can be set up with a request path and request parameters to to help identify the target request. Without this information, a FlashMap is made available to the next request, which may or may not be the intended intended recipient. On a redirect, the target URL is known and a FlashMap can be updated with that information. This is done automatically when the {@code org.springframework.web.servlet.view.RedirectView} is used.

Note: annotated controllers will usually not use FlashMap directly. See {@code org.springframework.web.servlet.mvc.support.RedirectAttributes} for an overview of using flash attributes in annotated controllers. @author Rossen Stoyanchev @since 3.1 1 @see FlashMapManager

Compare two FlashMaps and prefer the one that specifies a target URL URL path or has more target URL parameters. Before comparing FlashMap instances ensure that they match a given request.

Base servlet for Spring's web framework. Provides integration with a Spring application context, in a JavaBean-based overall solution.

This class offers the following functionality:

• Manages a WebApplicationContext instance per servlet. The servlet's configuration is determined by beans in the servlet's namespace.
• Publishes events on request processing, whether or not a request is successfully handled.

Subclasses must implement .doService to handle requests. Because this extends HttpServletBean rather than HttpServlet directly, bean properties are automatically mapped onto it. Subclasses can override .initFrameworkServlet() for custom initialization.

Detects a "contextClass" parameter at the servlet init-param level, falling back to the default context class, XmlWebApplicationContext, if not found. Note that, with the default {@code FrameworkServlet}, a custom context class needs to implement the ConfigurableWebApplicationContext SPI.

Accepts an optional "contextInitializerClasses" servlet init-param that specifies one or more ApplicationContextInitializer classes. The managed web application context will be delegated to these initializers, allowing for additional programmatic configuration, e.g. adding property sources or activating profiles against the org.springframework.context.ConfigurableApplicationContext#getEnvironment() context's environment. See also org.springframework.web.context.ContextLoader which supports a "contextInitializerClasses" context-param with identical semantics for the "root" web application context.

Passes a "contextConfigLocation" servlet init-param to the context instance, parsing it into potentially multiple file paths which can be separated by any number of commas and spaces, like "test-servlet.xml, myServlet.xml". If not explicitly specified, the context implementation is supposed to build a default location from the namespace of the servlet.

Note: In case of multiple config locations, later bean definitions will override ones defined in earlier loaded files, at least when using Spring's default ApplicationContext implementation. This can be leveraged to deliberately override certain bean definitions via an extra XML file.

The default namespace is "'servlet-name'-servlet", e.g. "test-servlet" for a servlet-name "test" (leading to a "/WEB-INF/test-servlet.xml" default location with XmlWebApplicationContext). The namespace can also be set explicitly via the "namespace" servlet init-param.

As of Spring 3.1, {@code FrameworkServlet} may now be injected with a web application context, rather than creating its own internally. This is useful in Servlet 3.0+ environments, which support programmatic registration of servlet instances. See .FrameworkServlet(WebApplicationContext) Javadoc for details. @author Rod Johnson @author Juergen Hoeller @author Sam Brannen @author Chris Beams @author Rossen Stoyanchev @see #doService @see #setContextClass @see #setContextConfigLocation @see #setContextInitializerClasses @see #setNamespace

Post-process the given WebApplicationContext before it is refreshed and activated as context for this servlet.

The default implementation is empty. refresh() will be called automatically after this method returns.

Note that this method is designed to allow subclasses to modify the application context, while .initializeWebApplicationContextinitWebApplicationContext is designed to allow end-users to modify the context through the use of ApplicationContextInitializers. @param wac the configured WebApplicationContext (not refreshed yet) @see #createWebApplicationContext @see #initializeWebApplicationContext initWebApplicationContext @see ConfigurableWebApplicationContext#refresh()

Specify the set of fully-qualified ApplicationContextInitializer class names, per the optional "contextInitializerClasses" servlet init-param. @see #configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext) @see #applyInitializers(ConfigurableWebApplicationContextConfigurableApplicationContext)

Specify which ApplicationContextInitializer instances should be used to initialize the application context used by this {@code FrameworkServlet}. @see #configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext) @see #applyInitializers(ConfigurableWebApplicationContextConfigurableApplicationContext)

Workflow interface that allows for customized handler execution chains. Applications can register any number of existing or custom interceptors for certain groups of handlers, to add common preprocessing behavior without needing to modify each handler implementation.

A HandlerInterceptor gets called before the appropriate HandlerAdapter triggers the execution of the handler itself. This mechanism can be used for a large field of preprocessing aspects, e.g. for authorization checks, or common handler behavior like locale or theme changes. Its main purpose is to allow for factoring out repetitive handler code.

In an async processing scenario, the handler may be executed in a separate thread while the main thread exits without rendering or invoking the {@code postHandle} and {@code afterCompletion} callbacks. When concurrent handler execution completes, the request is dispatched back in order to proceed with rendering the model and all methods of this contract are invoked again. For further options and details see {@code org.springframework.web.servlet.AsyncHandlerInterceptor}

Typically an interceptor chain is defined per HandlerMapping bean, sharing its granularity. To be able to apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one HandlerMapping bean. The interceptors themselves are defined as beans in the application context, referenced by the mapping bean definition via its "interceptors" property (in XML: a <list> of <ref>).

HandlerInterceptor is basically similar to a Servlet 2.3 Filter, but in contrast to the latter it just allows custom pre-processing with the option of prohibiting the execution of the handler itself, and custom post-processing. Filters are more powerful, for example they allow for exchanging the request and response objects that are handed down the chain. Note that a filter gets configured in web.xml, a HandlerInterceptor in the application context.

As a basic guideline, fine-grained handler-related preprocessing tasks are candidates for HandlerInterceptor implementations, especially factored-out common handler code and authorization checks. On the other hand, a Filter is well-suited for request content and view content handling, like multipart forms and GZIP compression. This typically shows when one needs to map the filter to certain content types (e.g. images), or to all requests. @author Juergen Hoeller @since 20.06.2003 @see HandlerExecutionChain#getInterceptors @see org.springframework.web.servlet.handler.HandlerInterceptorAdapter @see org.springframework.web.servlet.handler.AbstractHandlerMapping#setInterceptors @see org.springframework.web.servlet.handler.UserRoleAuthorizationInterceptor @see org.springframework.web.servlet.i18n.LocaleChangeInterceptor @see org.springframework.web.servlet.theme.ThemeChangeInterceptor @see javax.servlet.Filter

Callback after completion of request processing, that is, after rendering the view. Will be called on any outcome of handler execution, thus allows for proper resource cleanup.

Note: Will only be called if this interceptor's preHandle method has successfully completed and returned true!

As with the {@code postHandle} method, the method will be invoked on each interceptor in the chain in reverse order, so the first interceptor will be the last to be invoked. @param request current HTTP request @param response current HTTP response @param handler chosen handler to(or HandlerMethod) that started executeasync execution, for type and/or instance examination @param ex exception thrown on handler execution, if any @throws Exception in case of errors

Intercept the execution of a handler. Called after HandlerAdapter actually invoked the handler, but before the DispatcherServlet renders the view. Can expose additional model objects to the view via the given ModelAndView.

DispatcherServlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can post-process an execution, getting applied in inverse order of the execution chain. @param request current HTTP request @param response current HTTP response @param handler chosen handler to(or HandlerMethod) executethat started async execution, for type and/or instance examination @param modelAndView the ModelAndView that the handler returned (can also be null) @throws Exception in case of errors

Name of the HttpServletRequest attribute that contains the set ofof producible MediaTypes applicable to the mapped handler.

Note: This attribute is not required to be supported by allall HandlerMapping implementations. Handlers should not necessarily expectexpect this request attribute to be present in all scenarios.

{@inheritDoc} Any@throws environment set here overrides theIllegalArgumentException if environment is not StandardServletEnvironment assignable providedto by{@code defaultConfigurableWebEnvironment}.

Name of the HttpServletRequest attribute that contains a Map with path variables. The map consists of String-based URI template variable names as keys and their correspondingcorresponding Object-based values -- extracted from segments of the URL and type converted.

Note: This attribute is not required to be supported by all View implementations.