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

org.springframework.web.servlet.support

## Class AbstractDispatcherServletInitializer

- java.lang.Object
- - org.springframework.web.context.AbstractContextLoaderInitializer
  - - org.springframework.web.servlet.support.AbstractDispatcherServletInitializer

- All Implemented Interfaces:
    WebApplicationInitializer
  Direct Known Subclasses:
    AbstractAnnotationConfigDispatcherServletInitializer

      public abstract class AbstractDispatcherServletInitializer
      extends AbstractContextLoaderInitializer

  Base class for `WebApplicationInitializer` implementations that register a `DispatcherServlet` in the servlet context.

  Concrete implementations are required to implement `createServletApplicationContext()`, as well as `getServletMappings()`, both of which gets invoked from `registerDispatcherServlet(ServletContext)`. Further customization can be achieved by overriding `customizeRegistration(ServletRegistration.Dynamic)`.

  Because this class extends from `AbstractContextLoaderInitializer`, concrete implementations are also required to implement `AbstractContextLoaderInitializer.createRootApplicationContext()` to set up a parent "root" application context. If a root context is not desired, implementations can simply return `null` in the `createRootApplicationContext()` implementation.

  Since:
    3.2
  Author:
    Arjen Poutsma, Chris Beams, Rossen Stoyanchev

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_SERVLET_NAME` The default servlet name.

    - ### Fields inherited from class org.springframework.web.context.AbstractContextLoaderInitializer

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractDispatcherServletInitializer()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract WebApplicationContext` | `createServletApplicationContext()` Create a servlet application context to be provided to the `DispatcherServlet`.
    `protected void` | `customizeRegistration(ServletRegistration.Dynamic registration)` Optionally perform further registration customization once `registerDispatcherServlet(ServletContext)` has completed.
    `protected Filter[]` | `getServletFilters()` Specify filters to add and also map to the `DispatcherServlet`.
    `protected abstract String[]` | `getServletMappings()` Specify the servlet mapping(s) for the `DispatcherServlet`, e.g.
    `protected String` | `getServletName()` Return the name under which the `DispatcherServlet` will be registered.
    `protected boolean` | `isAsyncSupported()` A single place to control the `asyncSupported` flag for the `DispatcherServlet` and all filters added via `getServletFilters()`.
    `void` | `onStartup(ServletContext servletContext)` Configure the given `ServletContext` with any servlets, filters, listeners context-params and attributes necessary for initializing this web application.
    `protected void` | `registerDispatcherServlet(ServletContext servletContext)` Register a `DispatcherServlet` against the given servlet context.
    `protected FilterRegistration.Dynamic` | `registerServletFilter(ServletContext servletContext, Filter filter)` Add the given filter to the ServletContext and map it to the `DispatcherServlet` as follows: a default filter name is chosen based on its concrete type the `asyncSupported` flag is set depending on the return value of `asyncSupported` a filter mapping is created with dispatcher types `REQUEST`, `FORWARD`, `INCLUDE`, and conditionally `ASYNC` depending on the return value of `asyncSupported`

    - ### Methods inherited from class org.springframework.web.context.AbstractContextLoaderInitializer

      `createRootApplicationContext, registerContextLoaderListener`

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

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

- - ### Field Detail

    - #### DEFAULT_SERVLET_NAME

          public static final String DEFAULT_SERVLET_NAME

      The default servlet name. Can be customized by overriding `getServletName()`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractDispatcherServletInitializer

          public AbstractDispatcherServletInitializer()

  - ### Method Detail

    - #### onStartup

          public void onStartup(ServletContext servletContext)
                         throws ServletException

      Description copied from interface: `WebApplicationInitializer`
      Configure the given `ServletContext` with any servlets, filters, listeners context-params and attributes necessary for initializing this web application. See examples above.
      Specified by:
        `onStartup` in interface `WebApplicationInitializer`
      Overrides:
        `onStartup` in class `AbstractContextLoaderInitializer`
      Parameters:
        `servletContext` - the `ServletContext` to initialize
      Throws:
        `ServletException` - if any call against the given `ServletContext` throws a `ServletException`

    - #### registerDispatcherServlet

          protected void registerDispatcherServlet(ServletContext servletContext)

      Register a `DispatcherServlet` against the given servlet context.

      This method will create a `DispatcherServlet` with the name returned by `getServletName()`, initializing it with the application context returned from `createServletApplicationContext()`, and mapping it to the patterns returned from `getServletMappings()`.

      Further customization can be achieved by overriding `customizeRegistration(ServletRegistration.Dynamic)`.

      Parameters:
        `servletContext` - the context to register the servlet against

    - #### getServletName

          protected String getServletName()

      Return the name under which the `DispatcherServlet` will be registered. Defaults to `DEFAULT_SERVLET_NAME`.
      See Also:
        `registerDispatcherServlet(ServletContext)`

    - #### createServletApplicationContext

          protected abstract WebApplicationContext createServletApplicationContext()

      Create a servlet application context to be provided to the `DispatcherServlet`.

      The returned context is delegated to Spring's `DispatcherServlet.DispatcherServlet(WebApplicationContext)` As such, it typically contains controllers, view resolvers, locale resolvers, and other web-related beans.

      See Also:
        `registerDispatcherServlet(ServletContext)`

    - #### getServletMappings

          protected abstract String[] getServletMappings()

      Specify the servlet mapping(s) for the `DispatcherServlet`, e.g. '/', '/app', etc.
      See Also:
        `registerDispatcherServlet(ServletContext)`

    - #### getServletFilters

          protected Filter[] getServletFilters()

      Specify filters to add and also map to the `DispatcherServlet`.
      Returns:
        an array of filters or `null`
      See Also:
        `registerServletFilter(ServletContext, Filter)`

    - #### registerServletFilter

          protected FilterRegistration.Dynamic registerServletFilter(ServletContext servletContext,
                                                         Filter filter)

      Add the given filter to the ServletContext and map it to the `DispatcherServlet` as follows:
      - a default filter name is chosen based on its concrete type
      - the `asyncSupported` flag is set depending on the return value of `asyncSupported`
      - a filter mapping is created with dispatcher types `REQUEST`, `FORWARD`, `INCLUDE`, and conditionally `ASYNC` depending on the return value of `asyncSupported`

      If the above defaults are not suitable or insufficient, register filters directly with the `ServletContext`.

      Parameters:
        `servletContext` - the servlet context to register filters with
        `filter` - the filter to be registered
      Returns:
        the filter registration

    - #### isAsyncSupported

          protected boolean isAsyncSupported()

      A single place to control the `asyncSupported` flag for the `DispatcherServlet` and all filters added via `getServletFilters()`.

      The default value is "true".

    - #### customizeRegistration

          protected void customizeRegistration(ServletRegistration.Dynamic registration)

      Optionally perform further registration customization once `registerDispatcherServlet(ServletContext)` has completed.
      Parameters:
        `registration` - the `DispatcherServlet` registration to be customized
      See Also:
        `registerDispatcherServlet(ServletContext)`