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

org.springframework.test.context.support

## Class AbstractDelegatingSmartContextLoader

- java.lang.Object
- - org.springframework.test.context.support.AbstractDelegatingSmartContextLoader

- All Implemented Interfaces:
    ContextLoader, SmartContextLoader
  Direct Known Subclasses:
    DelegatingSmartContextLoader, WebDelegatingSmartContextLoader

      public abstract class AbstractDelegatingSmartContextLoader
      extends Object
      implements SmartContextLoader

  `AbstractDelegatingSmartContextLoader` serves as an abstract base class for implementations of the `SmartContextLoader` SPI that delegate to a set of candidate SmartContextLoaders (i.e., one that supports XML configuration files and one that supports annotated classes) to determine which context loader is appropriate for a given test class's configuration. Each candidate is given a chance to `process` the `ContextConfigurationAttributes` for each class in the test class hierarchy that is annotated with `@ContextConfiguration`, and the candidate that supports the merged, processed configuration will be used to actually `load` the context.

  Placing an empty `@ContextConfiguration` annotation on a test class signals that default resource locations (i.e., XML configuration files) or default `configuration classes` should be detected. Furthermore, if a specific `ContextLoader` or `SmartContextLoader` is not explicitly declared via `@ContextConfiguration`, a concrete subclass of `AbstractDelegatingSmartContextLoader` will be used as the default loader, thus providing automatic support for either XML configuration files or annotated classes, but not both simultaneously.

  As of Spring 3.2, a test class may optionally declare neither XML configuration files nor annotated classes and instead declare only application context initializers. In such cases, an attempt will still be made to detect defaults, but their absence will not result an an exception.

  Since:
    3.2
  Author:
    Sam Brannen
  See Also:
    `SmartContextLoader`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractDelegatingSmartContextLoader()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract SmartContextLoader` | `getAnnotationConfigLoader()` Get the delegate `SmartContextLoader` that supports annotated classes.
    `protected abstract SmartContextLoader` | `getXmlLoader()` Get the delegate `SmartContextLoader` that supports XML configuration files.
    `ApplicationContext` | `loadContext(MergedContextConfiguration mergedConfig)` Delegates to an appropriate candidate `SmartContextLoader` to load an `ApplicationContext`.
    `ApplicationContext` | `loadContext(String... locations)` `AbstractDelegatingSmartContextLoader` does not support the `ContextLoader.loadContext(String...)` method.
    `void` | `processContextConfiguration(ContextConfigurationAttributes configAttributes)` Delegates to candidate `SmartContextLoaders` to process the supplied `ContextConfigurationAttributes`.
    `String[]` | `processLocations(Class<?> clazz, String... locations)` `AbstractDelegatingSmartContextLoader` does not support the `ContextLoader.processLocations(Class, String...)` method.

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

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

- - ### Constructor Detail

    - #### AbstractDelegatingSmartContextLoader

          public AbstractDelegatingSmartContextLoader()

  - ### Method Detail

    - #### getXmlLoader

          protected abstract SmartContextLoader getXmlLoader()

      Get the delegate `SmartContextLoader` that supports XML configuration files.

    - #### getAnnotationConfigLoader

          protected abstract SmartContextLoader getAnnotationConfigLoader()

      Get the delegate `SmartContextLoader` that supports annotated classes.

    - #### processContextConfiguration

          public void processContextConfiguration(ContextConfigurationAttributes configAttributes)

      Delegates to candidate `SmartContextLoaders` to process the supplied `ContextConfigurationAttributes`.

      Delegation is based on explicit knowledge of the implementations of the default loaders for `XML configuration files` and `annotated classes`. Specifically, the delegation algorithm is as follows:

      - If the resource locations or annotated classes in the supplied `ContextConfigurationAttributes` are not empty, the appropriate candidate loader will be allowed to process the configuration as is, without any checks for detection of defaults.
      - Otherwise, the XML-based loader will be allowed to process the configuration in order to detect default resource locations. If the XML-based loader detects default resource locations, an `info` message will be logged.
      - Subsequently, the annotation-based loader will be allowed to process the configuration in order to detect default configuration classes. If the annotation-based loader detects default configuration classes, an `info` message will be logged.
      Specified by:
        `processContextConfiguration` in interface `SmartContextLoader`
      Parameters:
        `configAttributes` - the context configuration attributes to process
      Throws:
        `IllegalArgumentException` - if the supplied configuration attributes are `null`, or if the supplied configuration attributes include both resource locations and annotated classes
        `IllegalStateException` - if the XML-based loader detects default configuration classes; if the annotation-based loader detects default resource locations; if neither candidate loader detects defaults for the supplied context configuration; or if both candidate loaders detect defaults for the supplied context configuration

    - #### loadContext

          public ApplicationContext loadContext(MergedContextConfiguration mergedConfig)
                                         throws Exception

      Delegates to an appropriate candidate `SmartContextLoader` to load an `ApplicationContext`.

      Delegation is based on explicit knowledge of the implementations of the default loaders for `XML configuration files` and `annotated classes`. Specifically, the delegation algorithm is as follows:

      - If the resource locations in the supplied `MergedContextConfiguration` are not empty and the annotated classes are empty, the XML-based loader will load the `ApplicationContext`.
      - If the annotated classes in the supplied `MergedContextConfiguration` are not empty and the resource locations are empty, the annotation-based loader will load the `ApplicationContext`.
      Specified by:
        `loadContext` in interface `SmartContextLoader`
      Parameters:
        `mergedConfig` - the merged context configuration to use to load the application context
      Returns:
        a new application context
      Throws:
        `IllegalArgumentException` - if the supplied merged configuration is `null`
        `IllegalStateException` - if neither candidate loader is capable of loading an `ApplicationContext` from the supplied merged context configuration
        `Exception` - if context loading failed
      See Also:
        `SmartContextLoader.processContextConfiguration(ContextConfigurationAttributes)`, `#registerAnnotationConfigProcessors(org.springframework.beans.factory.support.BeanDefinitionRegistry)`, `MergedContextConfiguration.getActiveProfiles()`, `ConfigurableApplicationContext.getEnvironment()`

    - #### processLocations

          public final String[] processLocations(Class<?> clazz,
                                  String... locations)

      `AbstractDelegatingSmartContextLoader` does not support the `ContextLoader.processLocations(Class, String...)` method. Call `processContextConfiguration(ContextConfigurationAttributes)` instead.
      Specified by:
        `processLocations` in interface `ContextLoader`
      Parameters:
        `clazz` - the class with which the locations are associated: used to determine how to process the supplied locations
        `locations` - the unmodified locations to use for loading the application context (can be `null` or empty)
      Returns:
        an array of application context resource locations
      Throws:
        `UnsupportedOperationException`

    - #### loadContext

          public final ApplicationContext loadContext(String... locations)
                                               throws Exception

      `AbstractDelegatingSmartContextLoader` does not support the `ContextLoader.loadContext(String...)` method. Call `loadContext(MergedContextConfiguration)` instead.
      Specified by:
        `loadContext` in interface `ContextLoader`
      Parameters:
        `locations` - the resource locations to use to load the application context
      Returns:
        a new application context
      Throws:
        `UnsupportedOperationException`
        `Exception` - if context loading failed