Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

### when in combination with `web.xml`

If a web application does include 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".

## 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`. Said another way, any servlet, listener, or filter may be registered within a `WebApplicationInitializer`, not just Spring MVC-specific components.

This class is not designed for 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
See Also:
  `onStartup(Set, ServletContext)`, `WebApplicationInitializer`

Constructor Summary
`SpringServletContainerInitializer()`

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD