org.springframework.web Documentation Differences

This file contains all the changes in documentation in the package org.springframework.web 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.

Create a new MediaTypeExceptionHttpMediaTypeException. @param message the exception message

Create a new HttpMediaTypeNotSupportedExceptionHttpMediaTypeException with a list of supported media types. @param supportedMediaTypes the list of supported media types

Exception thrown when a client POSTs, PUTs, or PUTsPATCHes content of a type not supported by request handler. @author Arjen Poutsma @since 3.0

Servlet 3.0 ServletContainerInitializer designed to support code-based configuration of the servlet container using Spring's WebApplicationInitializer SPI as opposed to (or possibly in combination with) the traditional {@code web.xml}-based approach.

Mechanism of Operation

This class will be loaded and instantiated and have its .onStartup method invoked by any Servlet 3.0-compliant container during container startup assuming that the {@code spring-web} module JAR is present on the classpath. This occurs through the JAR Services API ServiceLoader.load(Class) method detecting the {@code spring-web} module's {@code META-INF/services/javax.servlet.ServletContainerInitializer} service provider configuration file. See the JAR Services API documentation as well as section 8.2.4 of the Servlet 3.0 Final Draft specification for complete details.

when inIn combination with {@code web.xml}

If a web application does includeincludes a {@code WEB-INF/web.xml} file, it is important to understand that neither this nor any other {@code ServletContextInitializer} will be processed unless the {@code } element's {@code version} attribute is >= "3.0" and the {@code xsi:schemaLocation} for "http://java.sun.com/xml/ns/javaee" is set to "http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd".

A web application can choose to limit the amount of classpath scanning the Servlet container does at startup either through the {@code metadata-complete} attribute in {@code web.xml}, which controls scanning for Servlet annotations or through an {@code } element also in {@code web.xml}, which controls which web fragments (i.e. jars) are allowed to perform a {@code ServletContainerInitializer} scan. When using this feature, the SpringServletContainerInitializer can be enabled by adding "spring_web" to the list of named web fragments in {@code web.xml} as follows:

 {@code
 
   some_web_fragment
   spring_web
 
 }

Relationship to Spring's {@code WebApplicationInitializer}

Spring's {@code WebApplicationInitializer} SPI consists of just one method: WebApplicationInitializer.onStartup(ServletContext). The signature is intentionally quite similar to ServletContainerInitializer.onStartup(Set, ServletContext): simply put, {@code SpringServletContainerInitializer} is responsible for instantiating and delegating the {@code ServletContext} to any user-defined {@code WebApplicationInitializer} implementations. It is then the responsibility of each {@code WebApplicationInitializer} to do the actual work of initializing the {@code ServletContext}. The exact process of delegation is described in detail in the onStartup documentation below.

General Notes

In general, this class should be viewed as supporting infrastructure for the more important and user-facing {@code WebApplicationInitializer} SPI. Taking advantage of this container initializer is also completely optional: while it is true that this initializer will be loaded and invoked under all Servlet 3.0+ runtimes, it remains the user's choice whether to make any {@code WebApplicationInitializer} implementations available on the classpath. If no {@code WebApplicationInitializer} types are detected, this container initializer will have no effect.

Note that use of this container initializer and of {@code WebApplicationInitializer} is not in any way "tied" to Spring MVC other than the fact that the types are shipped in the {@code spring-web} module JAR. Rather, they can be considered general-purpose in their ability to facilitate convenient code-based configuration of the {@code ServletContext}. Said another wayIn other words, any servlet, listener, or filter may be registered within a {@code WebApplicationInitializer}, not just Spring MVC-specific components.

This class is notneither designed for extension nor intended to be extended. It should be considered considered an internal type, with {@code WebApplicationInitializer} being the public-facing SPI.

See Also

See WebApplicationInitializer Javadoc for examples and detailed usage recommendations.

@author Chris Beams @author Juergen Hoeller @author Rossen Stoyanchev @since 3.1 @see #onStartup(Set, ServletContext) @see WebApplicationInitializer

Delegate the {@code ServletContext} to any WebApplicationInitializer implementations present on the application classpath.

Because this class declares @{@code HandlesTypes(WebApplicationInitializer.class)}, Servlet 3.0+ containers will automatically scan the classpath for implementations of Spring's {@code WebApplicationInitializer} interface and provide the set of all such types to the {@code webAppInitializerClasses} parameter of this method.

If no {@code WebApplicationInitializer} implementations are found on the classpath, this method is effectively a no-op. An INFO-level log message will be issued notifying the user that the {@code ServletContainerInitializer} has indeed been invoked, but that no {@code WebApplicationInitializer} implementations were found.

Assuming that one or more {@code WebApplicationInitializer} types are detected, they will be instantiated (and sorted if the @@Order annotation is present or the Ordered interface has been implemented). Then the WebApplicationInitializer.onStartup(ServletContext) method will be invoked on each instance, delegating the {@code ServletContext} such that each instance may register and configure servlets such as Spring's {@code DispatcherServlet}, listeners such as Spring's {@code ContextLoaderListener}, or any other Servlet API componentry such as filters. @param webAppInitializerClasses all implementations of WebApplicationInitializer found on the application classpath @param servletContext the servlet context to be initialized @see WebApplicationInitializer#onStartup(ServletContext) @see AnnotationAwareOrderComparator

Interface to be implemented in Servlet 3.0+ environments in order to configure the ServletContext programmatically -- as opposed to (or possibly in conjunction with) the traditional {@code web.xml}-based approach.

Implementations of this SPI will be detected automatically by SpringServletContainerInitializer, which itself is bootstrapped automatically by any Servlet 3.0 container. See SpringServletContainerInitializer its Javadoc for details on this bootstrapping mechanism.

Example

The traditional, XML-based approach

Most Spring users building a web application will need to register Spring's {@code DispatcherServlet}. For reference, in WEB-INF/web.xml, this would typically be done as follows:

 {@code
 
   dispatcher
   
     org.springframework.web.servlet.DispatcherServlet
   
   
     contextConfigLocation
     /WEB-INF/spring/dispatcher-config.xml
   
   1
 

 
   dispatcher
   /
 }

The code-based approach with {@code WebApplicationInitializer}

Here is the equivalent {@code DispatcherServlet} registration logic, {@code WebApplicationInitializer}-style:

 public class MyWebAppInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext container) {
      XmlWebApplicationContext appContext = new XmlWebApplicationContext();
      appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");

      ServletRegistration.Dynamic dispatcher =
        container.addServlet("dispatcher", new DispatcherServlet(appContext));
      dispatcher.setLoadOnStartup(1);
      dispatcher.addMapping("/");
    }

 }

As an alternative to the above, you can also extend from org.springframework.web.servlet.support.AbstractDispatcherServletInitializer. As you can see, thanks to Servlet 3.0's new ServletContext.addServlet method we're actually registering an instance of the {@code DispatcherServlet}, and this means that the {@code DispatcherServlet} can now be treated like any other object -- receiving constructor injection of its application context in this case.

This style is both simpler and more concise. There is no concern for dealing with init-params, etc, just normal JavaBean-style properties and constructor arguments. You are free to create and work with your Spring application contexts as necessary before injecting them into the {@code DispatcherServlet}.

Most major Spring Web componentry hascomponents have been updated to support this style of registration. You'll find that {@code DispatcherServlet}, {@code FrameworkServlet}, {@code ContextLoaderListener} and {@code DelegatingFilterProxy} all now support constructor arguments. Even if a component (e.g. non-Spring, other third party) has not been specifically updated for use within {@code WebApplicationInitializers}, they still may be used in any case. The Servlet 3.0 {@code ServletContext} API allows for setting init-params, context-params, etc programmatically.

A 100% code-based approach to configuration

In the example above, {@code WEB-INF/web.xml} was successfully replaced with code in the form of a {@code WebApplicationInitializer}, but the actual {@code dispatcher-config.xml} Spring configuration remained XML-based. {@code WebApplicationInitializer} is a perfect fit for use with Spring's code-based {@code @Configuration} classes. See @Configuration Javadoc for complete details, but the following example demonstrates refactoring to use Spring's AnnotationConfigWebApplicationContext in lieu of {@code XmlWebApplicationContext}, and user-defined {@code @Configuration} classes {@code AppConfig} and {@code DispatcherConfig} instead of Spring XML files. This example also goes a bit beyond those above to demonstrate typical configuration of the 'root' application context and registration of the {@code ContextLoaderListener}:

 public class MyWebAppInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext container) {
      // Create the 'root' Spring application context
      AnnotationConfigWebApplicationContext rootContext =
        new AnnotationConfigWebApplicationContext();
      rootContext.register(AppConfig.class);

      // Manage the lifecycle of the root application context
      container.addListener(new ContextLoaderListener(rootContext));

      // Create the dispatcher servlet's Spring application context
      AnnotationConfigWebApplicationContext dispatcherContext =
        new AnnotationConfigWebApplicationContext();
      dispatcherContext.register(DispatcherConfig.class);

      // Register and map the dispatcher servlet
      ServletRegistration.Dynamic dispatcher =
        container.addServlet("dispatcher", new DispatcherServlet(dispatcherContext));
      dispatcher.setLoadOnStartup(1);
      dispatcher.addMapping("/");
    }

 }

As an alternative to the above, you can also extend from org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer. Remember that {@code WebApplicationInitializer} implementations are detected automatically -- so you are free to package them within your application as you see fit.

Ordering {@code WebApplicationInitializer} execution

{@code WebApplicationInitializer} implementations may optionally be annotated at the class level with Spring's @Order annotation or may implement Spring's Ordered interface. If so, the initializers will be ordered prior to invocation. This provides a mechanism for users to ensure the order in which servlet container initialization occurs. Use of this feature is expected to be rare, as typical applications will likely centralize all container initialization within a single {@code WebApplicationInitializer}.

Caveats

web.xml versioning

{@code WEB-INF/web.xml} and {@code WebApplicationInitializer} use are not mutually exclusive; for example, web.xml can register one servlet, and a {@code WebApplicationInitializer} can register another. An initializer can even modify registrations performed in {@code web.xml} through methods such as ServletContext.getServletRegistration(String). However, if {@code WEB-INF/web.xml} is present in the application, its {@code version} attribute must be set to "3.0" or greater, otherwise {@code ServletContainerInitializer} bootstrapping will be ignored by the servlet container.

Mapping to '/' under Tomcat

Apache Tomcat maps its internal {@code DefaultServlet} to "/", and on Tomcat versions <= 7.0.14, this servlet mapping cannot be overridden programmatically. 7.0.15 fixes this issue. Overriding the "/" servlet mapping has also been tested successfully under GlassFish 3.1.

@author Chris Beams @since 3.1 @see SpringServletContainerInitializerSpringServletContainerInitializer @see org.springframework.web.context.AbstractContextLoaderInitializer @see org.springframework.web.servlet.support.AbstractDispatcherServletInitializer @see org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer