## org.springframework.web.context
Class ContextLoader

    java.lang.Object
      org.springframework.web.context.ContextLoader

Direct Known Subclasses:
  ContextLoaderListener

    public class ContextLoader

extends Object

Performs the actual initialization work for the root application context. Called by `ContextLoaderListener`.

Looks for a `"contextClass"` parameter at the `web.xml` context-param level to specify the context class type, falling back to the default of `XmlWebApplicationContext` if not found. With the default ContextLoader implementation, any context class specified needs to implement the ConfigurableWebApplicationContext interface.

Processes a `"contextConfigLocation"` context-param and passes its value to the context instance, parsing it into potentially multiple file paths which can be separated by any number of commas and spaces, e.g. "WEB-INF/applicationContext1.xml, WEB-INF/applicationContext2.xml". Ant-style path patterns are supported as well, e.g. "WEB-INF/*Context.xml,WEB-INF/spring*.xml" or "WEB-INF/**/*Context.xml". If not explicitly specified, the context implementation is supposed to use a default location (with XmlWebApplicationContext: "/WEB-INF/applicationContext.xml").

Note: In case of multiple config locations, later bean definitions will override ones defined in previously loaded files, at least when using one of Spring's default ApplicationContext implementations. This can be leveraged to deliberately override certain bean definitions via an extra XML file.

Above and beyond loading the root application context, this class can optionally load or obtain and hook up a shared parent context to the root application context. See the `loadParentContext(ServletContext)` method for more information.

As of Spring 3.1, `ContextLoader` supports injecting the root web application context via the `ContextLoader(WebApplicationContext)` constructor, allowing for programmatic configuration in Servlet 3.0+ environments. See `WebApplicationInitializer` for usage examples.

Since:
  17.02.2003
Author:
  Juergen Hoeller, Colin Sampaleanu, Sam Brannen
See Also:
  `ContextLoaderListener`, `ConfigurableWebApplicationContext`, `XmlWebApplicationContext`

Field Summary
`static String` `CONFIG_LOCATION_PARAM` Name of servlet context parameter (i.e., "contextConfigLocation") that can specify the config location for the root context, falling back to the implementation's default otherwise.
`static String` `CONTEXT_CLASS_PARAM` Config param for the root WebApplicationContext implementation class to use: "contextClass"
`static String` `CONTEXT_ID_PARAM` Config param for the root WebApplicationContext id, to be used as serialization id for the underlying BeanFactory: "contextId"
`static String` `CONTEXT_INITIALIZER_CLASSES_PARAM` Config param for which `ApplicationContextInitializer` classes to use for initializing the web application context: "contextInitializerClasses"
`static String` `LOCATOR_FACTORY_KEY_PARAM` Optional servlet context parameter (i.e., "`parentContextKey`") used only when obtaining a parent context using the default implementation of `loadParentContext(ServletContext servletContext)`.
`static String` `LOCATOR_FACTORY_SELECTOR_PARAM` Optional servlet context parameter (i.e., "`locatorFactorySelector`") used only when obtaining a parent context using the default implementation of `loadParentContext(ServletContext servletContext)`.

Constructor Summary
`ContextLoader()` Create a new `ContextLoader` that will create a web application context based on the "contextClass" and "contextConfigLocation" servlet context-params.
`ContextLoader(WebApplicationContext context)` Create a new `ContextLoader` with the given application context.

Method Summary
`void` `closeWebApplicationContext(ServletContext servletContext)` Close Spring's web application context for the given servlet context.
`protected void` `configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext wac, ServletContext sc)`
`protected WebApplicationContext` `createWebApplicationContext(ServletContext sc)` Instantiate the root WebApplicationContext for this loader, either the default context class or a custom context class if specified.
`protected WebApplicationContext` `createWebApplicationContext(ServletContext sc, ApplicationContext parent)` Deprecated. as of Spring 3.1 in favor of `createWebApplicationContext(ServletContext)` and `configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext, ServletContext)`
`protected void` `customizeContext(ServletContext servletContext, ConfigurableWebApplicationContext applicationContext)` Customize the `ConfigurableWebApplicationContext` created by this ContextLoader after config locations have been supplied to the context but before the context is refreshed.
`protected Class<?>` `determineContextClass(ServletContext servletContext)` Return the WebApplicationContext implementation class to use, either the default XmlWebApplicationContext or a custom context class if specified.
`protected List<Class<ApplicationContextInitializer<ConfigurableApplicationContext>>>` `determineContextInitializerClasses(ServletContext servletContext)` Return the `ApplicationContextInitializer` implementation classes to use if any have been specified by `CONTEXT_INITIALIZER_CLASSES_PARAM`.
`static WebApplicationContext` `getCurrentWebApplicationContext()` Obtain the Spring root web application context for the current thread (i.e.
`WebApplicationContext` `initWebApplicationContext(ServletContext servletContext)` Initialize Spring's web application context for the given servlet context, using the application context provided at construction time, or creating a new one according to the "`contextClass`" and "`contextConfigLocation`" context-params.
`protected ApplicationContext` `loadParentContext(ServletContext servletContext)` Template method with default implementation (which may be overridden by a subclass), to load or obtain an ApplicationContext instance which will be used as the parent context of the root WebApplicationContext.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### CONTEXT_CLASS_PARAM

    public static final String CONTEXT_CLASS_PARAM

  Config param for the root WebApplicationContext implementation class to use: "contextClass"

  See Also:
    `determineContextClass(ServletContext)`, `createWebApplicationContext(ServletContext, ApplicationContext)`, Constant Field Values

### CONTEXT_ID_PARAM

    public static final String CONTEXT_ID_PARAM

  Config param for the root WebApplicationContext id, to be used as serialization id for the underlying BeanFactory: "contextId"

  See Also:
    Constant Field Values

### CONTEXT_INITIALIZER_CLASSES_PARAM

    public static final String CONTEXT_INITIALIZER_CLASSES_PARAM

  Config param for which `ApplicationContextInitializer` classes to use for initializing the web application context: "contextInitializerClasses"

  See Also:
    `customizeContext(ServletContext, ConfigurableWebApplicationContext)`, Constant Field Values

### CONFIG_LOCATION_PARAM

    public static final String CONFIG_LOCATION_PARAM

  Name of servlet context parameter (i.e., "contextConfigLocation") that can specify the config location for the root context, falling back to the implementation's default otherwise.

  See Also:
    `XmlWebApplicationContext.DEFAULT_CONFIG_LOCATION`, Constant Field Values

### LOCATOR_FACTORY_SELECTOR_PARAM

    public static final String LOCATOR_FACTORY_SELECTOR_PARAM

  Optional servlet context parameter (i.e., "`locatorFactorySelector`") used only when obtaining a parent context using the default implementation of `loadParentContext(ServletContext servletContext)`. Specifies the 'selector' used in the `ContextSingletonBeanFactoryLocator.getInstance(String selector)` method call, which is used to obtain the BeanFactoryLocator instance from which the parent context is obtained.

  The default is `classpath*:beanRefContext.xml`, matching the default applied for the `ContextSingletonBeanFactoryLocator.getInstance()` method. Supplying the "parentContextKey" parameter is sufficient in this case.

  See Also:
    Constant Field Values

### LOCATOR_FACTORY_KEY_PARAM

    public static final String LOCATOR_FACTORY_KEY_PARAM

  Optional servlet context parameter (i.e., "`parentContextKey`") used only when obtaining a parent context using the default implementation of `loadParentContext(ServletContext servletContext)`. Specifies the 'factoryKey' used in the `BeanFactoryLocator.useBeanFactory(String factoryKey)` method call, obtaining the parent application context from the BeanFactoryLocator instance.

  Supplying this "parentContextKey" parameter is sufficient when relying on the default `classpath*:beanRefContext.xml` selector for candidate factory references.

  See Also:
    Constant Field Values

Constructor Detail

### ContextLoader

    public ContextLoader()

  Create a new `ContextLoader` that will create a web application context based on the "contextClass" and "contextConfigLocation" servlet context-params. See class-level documentation for details on default values for each.

  This constructor is typically used when declaring the `ContextLoaderListener` subclass as a `<listener>` within `web.xml`, as a no-arg constructor is required.

  The created application context will be registered into the ServletContext under the attribute name `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE` and subclasses are free to call the `closeWebApplicationContext(javax.servlet.ServletContext)` method on container shutdown to close the application context.

  See Also:
    `ContextLoader(WebApplicationContext)`, `initWebApplicationContext(ServletContext)`, `closeWebApplicationContext(ServletContext)`

### ContextLoader

    public ContextLoader(WebApplicationContext context)

  Create a new `ContextLoader` with the given application context. This constructor is useful in Servlet 3.0+ environments where instance-based registration of listeners is possible through the `ServletContext#addListener` API.

  The context may or may not yet be refreshed. If it (a) is an implementation of `ConfigurableWebApplicationContext` and (b) has not already been refreshed (the recommended approach), then the following will occur:

  - If the given context has not already been assigned an id, one will be assigned to it
  - `ServletContext` and `ServletConfig` objects will be delegated to the application context
  - `customizeContext(javax.servlet.ServletContext, org.springframework.web.context.ConfigurableWebApplicationContext)` will be called
  - Any `ApplicationContextInitializer`s specified through the "contextInitializerClasses" init-param will be applied.
  - `refresh()` will be called
  If the context has already been refreshed or does not implement `ConfigurableWebApplicationContext`, none of the above will occur under the assumption that the user has performed these actions (or not) per his or her specific needs.

  See `WebApplicationInitializer` for usage examples.

  In any case, the given application context will be registered into the ServletContext under the attribute name `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE` and subclasses are free to call the `closeWebApplicationContext(javax.servlet.ServletContext)` method on container shutdown to close the application context.

  Parameters:
    `context` - the application context to manage
  See Also:
    `initWebApplicationContext(ServletContext)`, `closeWebApplicationContext(ServletContext)`

Method Detail

### initWebApplicationContext

    public WebApplicationContext initWebApplicationContext(ServletContext servletContext)

  Initialize Spring's web application context for the given servlet context, using the application context provided at construction time, or creating a new one according to the "`contextClass`" and "`contextConfigLocation`" context-params.

  Parameters:
    `servletContext` - current servlet context
  Returns:
    the new WebApplicationContext
  See Also:
    `ContextLoader(WebApplicationContext)`, `CONTEXT_CLASS_PARAM`, `CONFIG_LOCATION_PARAM`

### createWebApplicationContext

    protected WebApplicationContext createWebApplicationContext(ServletContext sc)

  Instantiate the root WebApplicationContext for this loader, either the default context class or a custom context class if specified.

  This implementation expects custom contexts to implement the `ConfigurableWebApplicationContext` interface. Can be overridden in subclasses.

  In addition, `customizeContext(javax.servlet.ServletContext, org.springframework.web.context.ConfigurableWebApplicationContext)` gets called prior to refreshing the context, allowing subclasses to perform custom modifications to the context.

  Parameters:
    `sc` - current servlet context
  Returns:
    the root WebApplicationContext
  See Also:
    `ConfigurableWebApplicationContext`

### createWebApplicationContext

    @Deprecated
    protected WebApplicationContext createWebApplicationContext(ServletContext sc,
                                                                           ApplicationContext parent)

  Deprecated. as of Spring 3.1 in favor of `createWebApplicationContext(ServletContext)` and `configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext, ServletContext)`

### configureAndRefreshWebApplicationContext

    protected void configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext wac,
                                                            ServletContext sc)

### determineContextClass

    protected Class<?> determineContextClass(ServletContext servletContext)

  Return the WebApplicationContext implementation class to use, either the default XmlWebApplicationContext or a custom context class if specified.

  Parameters:
    `servletContext` - current servlet context
  Returns:
    the WebApplicationContext implementation class to use
  See Also:
    `CONTEXT_CLASS_PARAM`, `XmlWebApplicationContext`

### determineContextInitializerClasses

    protected List<Class<ApplicationContextInitializer<ConfigurableApplicationContext>>> determineContextInitializerClasses(ServletContext servletContext)

  Return the `ApplicationContextInitializer` implementation classes to use if any have been specified by `CONTEXT_INITIALIZER_CLASSES_PARAM`.

  Parameters:
    `servletContext` - current servlet context
  See Also:
    `CONTEXT_INITIALIZER_CLASSES_PARAM`

### customizeContext

    protected void customizeContext(ServletContext servletContext,
                                    ConfigurableWebApplicationContext applicationContext)

  Customize the `ConfigurableWebApplicationContext` created by this ContextLoader after config locations have been supplied to the context but before the context is refreshed.

  The default implementation determines what (if any) context initializer classes have been specified through context init parameters and invokes each with the given web application context.

  Any `ApplicationContextInitializers` implementing `Ordered` or marked with @`Order` will be sorted appropriately.

  Parameters:
    `servletContext` - the current servlet context
    `applicationContext` - the newly created application context
  See Also:
    `createWebApplicationContext(ServletContext, ApplicationContext)`, `CONTEXT_INITIALIZER_CLASSES_PARAM`, `ApplicationContextInitializer.initialize(ConfigurableApplicationContext)`

### loadParentContext

    protected ApplicationContext loadParentContext(ServletContext servletContext)

  Template method with default implementation (which may be overridden by a subclass), to load or obtain an ApplicationContext instance which will be used as the parent context of the root WebApplicationContext. If the return value from the method is null, no parent context is set.

  The main reason to load a parent context here is to allow multiple root web application contexts to all be children of a shared EAR context, or alternately to also share the same parent context that is visible to EJBs. For pure web applications, there is usually no need to worry about having a parent context to the root web application context.

  The default implementation uses `ContextSingletonBeanFactoryLocator`, configured via `LOCATOR_FACTORY_SELECTOR_PARAM` and `LOCATOR_FACTORY_KEY_PARAM`, to load a parent context which will be shared by all other users of ContextsingletonBeanFactoryLocator which also use the same configuration parameters.

  Parameters:
    `servletContext` - current servlet context
  Returns:
    the parent application context, or `null` if none
  See Also:
    `ContextSingletonBeanFactoryLocator`

### closeWebApplicationContext

    public void closeWebApplicationContext(ServletContext servletContext)

  Close Spring's web application context for the given servlet context. If the default `loadParentContext(ServletContext)` implementation, which uses ContextSingletonBeanFactoryLocator, has loaded any shared parent context, release one reference to that shared parent context.

  If overriding `loadParentContext(ServletContext)`, you may have to override this method as well.

  Parameters:
    `servletContext` - the ServletContext that the WebApplicationContext runs in

### getCurrentWebApplicationContext

    public static WebApplicationContext getCurrentWebApplicationContext()

  Obtain the Spring root web application context for the current thread (i.e. for the current thread's context ClassLoader, which needs to be the web application's ClassLoader).

  Returns:
    the current root web application context, or `null` if none found
  See Also:
    `SpringBeanAutowiringSupport`