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