spring-framework / org.springframework.web / SpringServletContainerInitializer

SpringServletContainerInitializer

open class SpringServletContainerInitializer : 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 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 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.

Author
Chris Beams

Author
Juergen Hoeller

Author
Rossen Stoyanchev

Since
3.1

See Also
#onStartup(Set, ServletContext)WebApplicationInitializer

Constructors

<init>

 SpringServletContainerInitializer()

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

Functions

onStartup

 open fun onStartup(webAppInitializerClasses: MutableSet<Class<*>>, servletContext: ServletContext): Unit

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 @ annotation is present or the org.springframework.core.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.