SpringServletContainerInitializer (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web

## Class SpringServletContainerInitializer

- java.lang.Object
- - org.springframework.web.SpringServletContainerInitializer

- All Implemented Interfaces:
    ServletContainerInitializer

      public class SpringServletContainerInitializer
      extends Object
      implements ServletContainerInitializer

  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 `web.xml`-based approach.

  ## Mechanism of Operation

  This class will be loaded and instantiated and have its `onStartup(java.util.Set<java.lang.Class<?>>, javax.servlet.ServletContext)` method invoked by any Servlet 3.0-compliant container during container startup assuming that the `spring-web` module JAR is present on the classpath. This occurs through the JAR Services API `ServiceLoader.load(Class)` method detecting the `spring-web` module's `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.

  ### In combination with `web.xml`

  If a web application includes a `WEB-INF/web.xml` file, it is important to understand that neither this nor any other `ServletContextInitializer` will be processed unless the `<web-app>` element's `version` attribute is >= "3.0" and the `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 `metadata-complete` attribute in `web.xml`, which controls scanning for Servlet annotations or through an `<absolute-ordering>` element also in `web.xml`, which controls which web fragments (i.e. jars) are allowed to perform a `ServletContainerInitializer` scan. When using this feature, the `SpringServletContainerInitializer` can be enabled by adding "spring_web" to the list of named web fragments in `web.xml` as follows:

       <absolute-ordering>
         <name>some_web_fragment</name>
         <name>spring_web</name>
       </absolute-ordering>

  ## Relationship to Spring's `WebApplicationInitializer`

  Spring's `WebApplicationInitializer` SPI consists of just one method: `WebApplicationInitializer.onStartup(ServletContext)`. The signature is intentionally quite similar to `ServletContainerInitializer.onStartup(Set, ServletContext)`: simply put, `SpringServletContainerInitializer` is responsible for instantiating and delegating the `ServletContext` to any user-defined `WebApplicationInitializer` implementations. It is then the responsibility of each `WebApplicationInitializer` to do the actual work of initializing the `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 `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 `WebApplicationInitializer` implementations available on the classpath. If no `WebApplicationInitializer` types are detected, this container initializer will have no effect.

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

  This class is neither designed for extension nor intended to be extended. It should be considered an internal type, with `WebApplicationInitializer` being the public-facing SPI.

  ## See Also

  See `WebApplicationInitializer` Javadoc for examples and detailed usage recommendations.

  Since:
    3.1
  Author:
    Chris Beams, Juergen Hoeller, Rossen Stoyanchev
  See Also:
    `onStartup(Set, ServletContext)`, `WebApplicationInitializer`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SpringServletContainerInitializer()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `onStartup(Set<Class<?>> webAppInitializerClasses, ServletContext servletContext)` Delegate the `ServletContext` to any `WebApplicationInitializer` implementations present on the application classpath.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SpringServletContainerInitializer

          public SpringServletContainerInitializer()

  - ### Method Detail

    - #### onStartup

          public void onStartup(Set<Class<?>> webAppInitializerClasses,
                       ServletContext servletContext)
                         throws ServletException

      Delegate the `ServletContext` to any `WebApplicationInitializer` implementations present on the application classpath.

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

      If no `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 `ServletContainerInitializer` has indeed been invoked but that no `WebApplicationInitializer` implementations were found.

      Assuming that one or more `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 `ServletContext` such that each instance may register and configure servlets such as Spring's `DispatcherServlet`, listeners such as Spring's `ContextLoaderListener`, or any other Servlet API componentry such as filters.

      Specified by:
        `onStartup` in interface `ServletContainerInitializer`
      Parameters:
        `webAppInitializerClasses` - all implementations of `WebApplicationInitializer` found on the application classpath
        `servletContext` - the servlet context to be initialized
      Throws:
        `ServletException`
      See Also:
        `WebApplicationInitializer.onStartup(ServletContext)`, `AnnotationAwareOrderComparator`