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

org.springframework.web.context.support

## Class WebApplicationContextUtils

- java.lang.Object
- - org.springframework.web.context.support.WebApplicationContextUtils

-     public abstract class WebApplicationContextUtils
      extends Object

  Convenience methods for retrieving the root `WebApplicationContext` for a given `ServletContext`. This is e.g. useful for accessing a Spring context from within custom web views or Struts actions.

  Note that there are more convenient ways of accessing the root context for many web frameworks, either part of Spring or available as external library. This helper class is just the most generic way to access the root context.

  Author:
    Juergen Hoeller
  See Also:
    `ContextLoader`, `FrameworkServlet`, `DispatcherServlet`, `FacesContextUtils`, `SpringBeanVariableResolver`, `SpringBeanFacesELResolver`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `WebApplicationContextUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static WebApplicationContext` | `getRequiredWebApplicationContext(ServletContext sc)` Find the root WebApplicationContext for this web application, which is typically loaded via `ContextLoaderListener`.
    `static WebApplicationContext` | `getWebApplicationContext(ServletContext sc)` Find the root WebApplicationContext for this web application, which is typically loaded via `ContextLoaderListener`.
    `static WebApplicationContext` | `getWebApplicationContext(ServletContext sc, String attrName)` Find a custom WebApplicationContext for this web application.
    `static void` | `initServletPropertySources(MutablePropertySources propertySources, ServletContext servletContext)` Convenient variant of `initServletPropertySources(MutablePropertySources, ServletContext, ServletConfig)` that always provides `null` for the `ServletConfig` parameter.
    `static void` | `initServletPropertySources(MutablePropertySources propertySources, ServletContext servletContext, ServletConfig servletConfig)` Replace `Servlet`-based `stub property sources` with actual instances populated with the given `servletContext` and `servletConfig` objects.
    `static void` | `registerEnvironmentBeans(ConfigurableListableBeanFactory bf, ServletContext sc)` Register web-specific environment beans ("contextParameters", "contextAttributes") with the given BeanFactory, as used by the WebApplicationContext.
    `static void` | `registerEnvironmentBeans(ConfigurableListableBeanFactory bf, ServletContext sc, ServletConfig config)` Register web-specific environment beans ("contextParameters", "contextAttributes") with the given BeanFactory, as used by the WebApplicationContext.
    `static void` | `registerWebApplicationScopes(ConfigurableListableBeanFactory beanFactory)` Register web-specific scopes ("request", "session", "globalSession") with the given BeanFactory, as used by the WebApplicationContext.
    `static void` | `registerWebApplicationScopes(ConfigurableListableBeanFactory beanFactory, ServletContext sc)` Register web-specific scopes ("request", "session", "globalSession", "application") with the given BeanFactory, as used by the WebApplicationContext.

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

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

- - ### Constructor Detail

    - #### WebApplicationContextUtils

          public WebApplicationContextUtils()

  - ### Method Detail

    - #### getRequiredWebApplicationContext

          public static WebApplicationContext getRequiredWebApplicationContext(ServletContext sc)
                                                                        throws IllegalStateException

      Find the root WebApplicationContext for this web application, which is typically loaded via `ContextLoaderListener`.

      Will rethrow an exception that happened on root context startup, to differentiate between a failed context startup and no context at all.

      Parameters:
        `sc` - ServletContext to find the web application context for
      Returns:
        the root WebApplicationContext for this web app
      Throws:
        `IllegalStateException` - if the root WebApplicationContext could not be found
      See Also:
        `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE`

    - #### getWebApplicationContext

          public static WebApplicationContext getWebApplicationContext(ServletContext sc)

      Find the root WebApplicationContext for this web application, which is typically loaded via `ContextLoaderListener`.

      Will rethrow an exception that happened on root context startup, to differentiate between a failed context startup and no context at all.

      Parameters:
        `sc` - ServletContext to find the web application context for
      Returns:
        the root WebApplicationContext for this web app, or `null` if none
      See Also:
        `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE`

    - #### getWebApplicationContext

          public static WebApplicationContext getWebApplicationContext(ServletContext sc,
                                                       String attrName)

      Find a custom WebApplicationContext for this web application.
      Parameters:
        `sc` - ServletContext to find the web application context for
        `attrName` - the name of the ServletContext attribute to look for
      Returns:
        the desired WebApplicationContext for this web app, or `null` if none

    - #### registerWebApplicationScopes

          public static void registerWebApplicationScopes(ConfigurableListableBeanFactory beanFactory)

      Register web-specific scopes ("request", "session", "globalSession") with the given BeanFactory, as used by the WebApplicationContext.
      Parameters:
        `beanFactory` - the BeanFactory to configure

    - #### registerWebApplicationScopes

          public static void registerWebApplicationScopes(ConfigurableListableBeanFactory beanFactory,
                                          ServletContext sc)

      Register web-specific scopes ("request", "session", "globalSession", "application") with the given BeanFactory, as used by the WebApplicationContext.
      Parameters:
        `beanFactory` - the BeanFactory to configure
        `sc` - the ServletContext that we're running within

    - #### registerEnvironmentBeans

          public static void registerEnvironmentBeans(ConfigurableListableBeanFactory bf,
                                      ServletContext sc)

      Register web-specific environment beans ("contextParameters", "contextAttributes") with the given BeanFactory, as used by the WebApplicationContext.
      Parameters:
        `bf` - the BeanFactory to configure
        `sc` - the ServletContext that we're running within

    - #### registerEnvironmentBeans

          public static void registerEnvironmentBeans(ConfigurableListableBeanFactory bf,
                                      ServletContext sc,
                                      ServletConfig config)

      Register web-specific environment beans ("contextParameters", "contextAttributes") with the given BeanFactory, as used by the WebApplicationContext.
      Parameters:
        `bf` - the BeanFactory to configure
        `sc` - the ServletContext that we're running within
        `config` - the ServletConfig of the containing Portlet

    - #### initServletPropertySources

          public static void initServletPropertySources(MutablePropertySources propertySources,
                                        ServletContext servletContext)

      Convenient variant of `initServletPropertySources(MutablePropertySources, ServletContext, ServletConfig)` that always provides `null` for the `ServletConfig` parameter.
      See Also:
        `initServletPropertySources(MutablePropertySources, ServletContext, ServletConfig)`

    - #### initServletPropertySources

          public static void initServletPropertySources(MutablePropertySources propertySources,
                                        ServletContext servletContext,
                                        ServletConfig servletConfig)

      Replace `Servlet`-based `stub property sources` with actual instances populated with the given `servletContext` and `servletConfig` objects.

      This method is idempotent with respect to the fact it may be called any number of times but will perform replacement of stub property sources with their corresponding actual property sources once and only once.

      Parameters:
        `propertySources` - the `MutablePropertySources` to initialize (must not be `null`)
        `servletContext` - the current `ServletContext` (ignored if `null` or if the `servlet context property source` has already been initialized)
        `servletConfig` - the current `ServletConfig` (ignored if `null` or if the `servlet config property source` has already been initialized)
      See Also:
        `PropertySource.StubPropertySource`, `ConfigurableEnvironment.getPropertySources()`