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

org.springframework.test.context

## Interface SmartContextLoader

- All Superinterfaces:
    ContextLoader
  All Known Implementing Classes:
    AbstractContextLoader, AbstractDelegatingSmartContextLoader, AbstractGenericContextLoader, AbstractGenericWebContextLoader, AnnotationConfigContextLoader, AnnotationConfigWebContextLoader, DelegatingSmartContextLoader, GenericPropertiesContextLoader, GenericXmlContextLoader, GenericXmlWebContextLoader, WebDelegatingSmartContextLoader

      public interface SmartContextLoader
      extends ContextLoader

  Strategy interface for loading an `application context` for an integration test managed by the Spring TestContext Framework.

  The `SmartContextLoader` SPI supersedes the `ContextLoader` SPI introduced in Spring 2.5: a `SmartContextLoader` can choose to process either resource locations or annotated classes. Furthermore, a `SmartContextLoader` can set active bean definition profiles in the context that it loads (see `MergedContextConfiguration.getActiveProfiles()` and `loadContext(MergedContextConfiguration)`).

  See the Javadoc for `@ContextConfiguration` for a definition of annotated class.

  Clients of a `SmartContextLoader` should call `processContextConfiguration()` prior to calling `loadContext()`. This gives a `SmartContextLoader` the opportunity to provide custom support for modifying resource locations or detecting default resource locations or default configuration classes. The results of `processContextConfiguration()` should be merged for all classes in the hierarchy of the root test class and then supplied to `loadContext()`.

  Even though `SmartContextLoader` extends `ContextLoader`, clients should favor `SmartContextLoader`-specific methods over those defined in `ContextLoader`, particularly because a `SmartContextLoader` may choose not to support methods defined in the `ContextLoader` SPI.

  Concrete implementations must provide a `public` no-args constructor.

  Spring provides the following out-of-the-box implementations:

  - `DelegatingSmartContextLoader`
  - `AnnotationConfigContextLoader`
  - `GenericXmlContextLoader`
  - `GenericPropertiesContextLoader`
  Since:
    3.1
  Author:
    Sam Brannen
  See Also:
    `ContextConfiguration`, `ActiveProfiles`, `ContextConfigurationAttributes`, `MergedContextConfiguration`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ApplicationContext` | `loadContext(MergedContextConfiguration mergedConfig)` Loads a new `context` based on the supplied `merged context configuration`, configures the context, and finally returns the context in a fully refreshed state.
    `void` | `processContextConfiguration(ContextConfigurationAttributes configAttributes)` Processes the `ContextConfigurationAttributes` for a given test class.

    - ### Methods inherited from interface org.springframework.test.context.ContextLoader

      `loadContext, processLocations`

- - ### Method Detail

    - #### processContextConfiguration

          void processContextConfiguration(ContextConfigurationAttributes configAttributes)

      Processes the `ContextConfigurationAttributes` for a given test class.

      Concrete implementations may choose to modify the `locations` or `classes` in the supplied `ContextConfigurationAttributes`, generate default configuration locations, or detect default configuration classes if the supplied values are `null` or empty.

      Note: in contrast to a standard `ContextLoader`, a `SmartContextLoader` must preemptively verify that a generated or detected default actually exists before setting the corresponding `locations` or `classes` property in the supplied `ContextConfigurationAttributes`. Consequently, leaving the `locations` or `classes` property empty signals that this `SmartContextLoader` was not able to generate or detect defaults.

      Parameters:
        `configAttributes` - the context configuration attributes to process

    - #### loadContext

          ApplicationContext loadContext(MergedContextConfiguration mergedConfig)
                                         throws Exception

      Loads a new `context` based on the supplied `merged context configuration`, configures the context, and finally returns the context in a fully refreshed state.

      Concrete implementations should register annotation configuration processors with bean factories of `application contexts` loaded by this `SmartContextLoader`. Beans will therefore automatically be candidates for annotation-based dependency injection using `@Autowired`, `@Resource`, and `@Inject`. In addition, concrete implementations should set the active bean definition profiles in the context's `Environment`.

      Any `ApplicationContext` loaded by a `SmartContextLoader` must register a JVM shutdown hook for itself. Unless the context gets closed early, all context instances will be automatically closed on JVM shutdown. This allows for freeing of external resources held by beans within the context (e.g., temporary files).

      Parameters:
        `mergedConfig` - the merged context configuration to use to load the application context
      Returns:
        a new application context
      Throws:
        `Exception` - if context loading failed
      See Also:
        `processContextConfiguration(ContextConfigurationAttributes)`, `#registerAnnotationConfigProcessors(org.springframework.beans.factory.support.BeanDefinitionRegistry)`, `MergedContextConfiguration.getActiveProfiles()`, `ConfigurableApplicationContext.getEnvironment()`