Package org.springframework.web

# Interface WebApplicationInitializer

All Known Implementing Classes:
  `AbstractContextLoaderInitializer`, `AbstractReactiveWebInitializer`

public interface WebApplicationInitializer
Interface to be implemented in Servlet environments in order to configure the `ServletContext` programmatically -- as opposed to (or possibly in conjunction with) the traditional `web.xml`-based approach.

Implementations of this SPI will be detected automatically by `SpringServletContainerInitializer`, which itself is bootstrapped automatically by any Servlet container. See 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 `DispatcherServlet`. For reference, in WEB-INF/web.xml, this would typically be done as follows:

     <servlet>
       <servlet-name>dispatcher</servlet-name>
       <servlet-class>
         org.springframework.web.servlet.DispatcherServlet
       </servlet-class>
       <init-param>
         <param-name>contextConfigLocation</param-name>
         <param-value>/WEB-INF/spring/dispatcher-config.xml</param-value>
       </init-param>
       <load-on-startup>1</load-on-startup>
     </servlet>

     <servlet-mapping>
       <servlet-name>dispatcher</servlet-name>
       <url-pattern>/</url-pattern>
     </servlet-mapping>

### The code-based approach with `WebApplicationInitializer`

Here is the equivalent `DispatcherServlet` registration logic, `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 the Servlet container's `ServletContext.addServlet(java.lang.String, java.lang.String)` method we're actually registering an instance of the `DispatcherServlet`, and this means that the `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 `DispatcherServlet`.

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

## A 100% code-based approach to configuration

In the example above, `WEB-INF/web.xml` was successfully replaced with code in the form of a `WebApplicationInitializer`, but the actual `dispatcher-config.xml` Spring configuration remained XML-based. `WebApplicationInitializer` is a perfect fit for use with Spring's code-based `@Configuration` classes. See @`Configuration` Javadoc for complete details, but the following example demonstrates refactoring to use Spring's `AnnotationConfigWebApplicationContext` in lieu of `XmlWebApplicationContext`, and user-defined `@Configuration` classes `AppConfig` and `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 `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 `WebApplicationInitializer` implementations are detected automatically -- so you are free to package them within your application as you see fit.

## Ordering `WebApplicationInitializer` execution

`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 `WebApplicationInitializer`.

Since:
  3.1
Author:
  Chris Beams
See Also:
  - `SpringServletContainerInitializer`
  - `AbstractContextLoaderInitializer`
  - `org.springframework.web.servlet.support.AbstractDispatcherServletInitializer`
  - `org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer`

## Method Summary

Modifier and Type
Method
Description
`void`
`onStartup(ServletContext servletContext)`
Configure the given `ServletContext` with any servlets, filters, listeners context-params and attributes necessary for initializing this web application.

## Method Details

### onStartup

void onStartup(ServletContext servletContext) throws ServletException
Configure the given `ServletContext` with any servlets, filters, listeners context-params and attributes necessary for initializing this web application. See examples above.

Parameters:
  `servletContext` - the `ServletContext` to initialize
Throws:
  `ServletException` - if any call against the given `ServletContext` throws a `ServletException`