Improve documentation of SmartContextLoader contracts
This commit is contained in:
Sam Brannen
parent
ee33aa6117
commit
72548f7611
|
|
@ -20,15 +20,17 @@ import org.springframework.context.ApplicationContext;
|
|||
import org.springframework.lang.Nullable;
|
||||
|
||||
/**
|
||||
* Strategy interface for loading an {@link ApplicationContext application context}
|
||||
* for an integration test managed by the Spring TestContext Framework.
|
||||
* Strategy interface for loading an {@link ApplicationContext} for an integration
|
||||
* test managed by the Spring TestContext Framework.
|
||||
*
|
||||
* <p>The {@code SmartContextLoader} SPI supersedes the {@link ContextLoader} SPI
|
||||
* introduced in Spring 2.5: a {@code SmartContextLoader} can choose to process
|
||||
* either resource locations or annotated classes. Furthermore, a
|
||||
* {@code SmartContextLoader} can set active bean definition profiles in the
|
||||
* context that it loads (see {@link MergedContextConfiguration#getActiveProfiles()}
|
||||
* and {@link #loadContext(MergedContextConfiguration)}).
|
||||
* resource locations, annotated classes, or a combination of both. Furthermore, a
|
||||
* {@code SmartContextLoader} can configure the context that it
|
||||
* {@linkplain #loadContext(MergedContextConfiguration) loads} based on any
|
||||
* properties available in the provided {@link MergedContextConfiguration}. For
|
||||
* example, active bean definition profiles can be configured for the context
|
||||
* based on {@link MergedContextConfiguration#getActiveProfiles()}.
|
||||
*
|
||||
* <p>See the Javadoc for {@link ContextConfiguration @ContextConfiguration}
|
||||
* for a definition of <em>annotated class</em>.
|
||||
|
|
@ -45,11 +47,8 @@ import org.springframework.lang.Nullable;
|
|||
* hierarchy of the root test class and then supplied to
|
||||
* {@link #loadContext(MergedContextConfiguration) loadContext()}.
|
||||
*
|
||||
* <p>Even though {@code SmartContextLoader} extends {@code ContextLoader},
|
||||
* clients should favor {@code SmartContextLoader}-specific methods over those
|
||||
* defined in {@code ContextLoader}, particularly because a
|
||||
* {@code SmartContextLoader} may choose not to support methods defined in the
|
||||
* {@code ContextLoader} SPI.
|
||||
* <p>NOTE: As of Spring Framework 6.0, {@code SmartContextLoader} no longer
|
||||
* supports methods defined in the {@code ContextLoader} SPI.
|
||||
*
|
||||
* <p>Concrete implementations must provide a {@code public} no-args constructor.
|
||||
*
|
||||
|
|
@ -58,43 +57,45 @@ import org.springframework.lang.Nullable;
|
|||
* <li>{@link org.springframework.test.context.support.DelegatingSmartContextLoader DelegatingSmartContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.support.GenericGroovyXmlContextLoader GenericGroovyXmlContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.web.WebDelegatingSmartContextLoader WebDelegatingSmartContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.web.AnnotationConfigWebContextLoader AnnotationConfigWebContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.web.GenericXmlWebContextLoader GenericXmlWebContextLoader}</li>
|
||||
* <li>{@link org.springframework.test.context.web.GenericGroovyXmlWebContextLoader GenericGroovyXmlWebContextLoader}</li>
|
||||
* </ul>
|
||||
*
|
||||
* @author Sam Brannen
|
||||
* @since 3.1
|
||||
* @see ContextConfiguration
|
||||
* @see ActiveProfiles
|
||||
* @see TestPropertySource
|
||||
* @see ContextConfigurationAttributes
|
||||
* @see MergedContextConfiguration
|
||||
*/
|
||||
public interface SmartContextLoader extends ContextLoader {
|
||||
|
||||
/**
|
||||
* Processes the {@link ContextConfigurationAttributes} for a given test class.
|
||||
* Process the {@link ContextConfigurationAttributes} for a given test class.
|
||||
* <p>Concrete implementations may choose to <em>modify</em> the {@code locations}
|
||||
* or {@code classes} in the supplied {@link ContextConfigurationAttributes},
|
||||
* or {@code classes} in the supplied {@code ContextConfigurationAttributes},
|
||||
* <em>generate</em> default configuration locations, or <em>detect</em>
|
||||
* default configuration classes if the supplied values are {@code null}
|
||||
* or empty.
|
||||
* <p><b>Note</b>: in contrast to a standard {@code ContextLoader}, a
|
||||
* {@code SmartContextLoader} <b>must</b> <em>preemptively</em> verify that
|
||||
* a generated or detected default actually exists before setting the corresponding
|
||||
* {@code locations} or {@code classes} property in the supplied
|
||||
* {@link ContextConfigurationAttributes}. Consequently, leaving the
|
||||
* {@code locations} or {@code classes} property empty signals that
|
||||
* this {@code SmartContextLoader} was not able to generate or detect defaults.
|
||||
* <p><b>Note</b>: a {@code SmartContextLoader} must <em>preemptively</em>
|
||||
* verify that a generated or detected default actually exists before setting
|
||||
* the corresponding {@code locations} or {@code classes} property in the
|
||||
* supplied {@code ContextConfigurationAttributes}. Consequently, leaving the
|
||||
* {@code locations} or {@code classes} property empty signals that this
|
||||
* {@code SmartContextLoader} was not able to generate or detect defaults.
|
||||
* @param configAttributes the context configuration attributes to process
|
||||
*/
|
||||
void processContextConfiguration(ContextConfigurationAttributes configAttributes);
|
||||
|
||||
/**
|
||||
* Loads a new {@link ApplicationContext context} based on the supplied
|
||||
* Load a new {@linkplain ApplicationContext context} based on the supplied
|
||||
* {@link MergedContextConfiguration merged context configuration},
|
||||
* configures the context, and finally returns the context in a fully
|
||||
* <em>refreshed</em> state.
|
||||
* configure the context, and return the context in a fully <em>refreshed</em>
|
||||
* state.
|
||||
* <p>Concrete implementations should register annotation configuration
|
||||
* processors with bean factories of
|
||||
* {@link ApplicationContext application contexts} loaded by this
|
||||
|
|
@ -103,22 +104,35 @@ public interface SmartContextLoader extends ContextLoader {
|
|||
* {@link org.springframework.beans.factory.annotation.Autowired @Autowired},
|
||||
* {@link jakarta.annotation.Resource @Resource}, and
|
||||
* {@link jakarta.inject.Inject @Inject}. In addition, concrete implementations
|
||||
* should set the active bean definition profiles in the context's
|
||||
* {@link org.springframework.core.env.Environment Environment}.
|
||||
* <p>Any {@code ApplicationContext} loaded by a
|
||||
* {@code SmartContextLoader} <strong>must</strong> 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).
|
||||
* should perform the following actions.
|
||||
* <ul>
|
||||
* <li>Set the parent {@code ApplicationContext} if appropriate (see
|
||||
* {@link MergedContextConfiguration#getParent()}).</li>
|
||||
* <li>Set the active bean definition profiles in the context's
|
||||
* {@link org.springframework.core.env.Environment Environment} (see
|
||||
* {@link MergedContextConfiguration#getActiveProfiles()}).</li>
|
||||
* <li>Add test {@link org.springframework.core.env.PropertySource PropertySources}
|
||||
* to the {@code Environment} (see
|
||||
* {@link MergedContextConfiguration#getPropertySourceLocations()},
|
||||
* {@link MergedContextConfiguration#getPropertySourceProperties()}, and
|
||||
* {@link org.springframework.test.context.support.TestPropertySourceUtils
|
||||
* TestPropertySourceUtils}).</li>
|
||||
* <li>Invoke {@link org.springframework.context.ApplicationContextInitializer
|
||||
* ApplicationContextInitializers} (see
|
||||
* {@link MergedContextConfiguration#getContextInitializerClasses()}).</li>
|
||||
* <li>Invoke {@link ContextCustomizer ContextCustomizers} (see
|
||||
* {@link MergedContextConfiguration#getContextCustomizers()}).</li>
|
||||
* <li>Register a JVM shutdown hook for the {@link ApplicationContext}. 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 — for example, temporary files.</li>
|
||||
* </ul>
|
||||
* @param mergedConfig the merged context configuration to use to load the
|
||||
* application context
|
||||
* @return a new application context
|
||||
* @throws Exception if context loading failed
|
||||
* @see #processContextConfiguration(ContextConfigurationAttributes)
|
||||
* @see org.springframework.context.annotation.AnnotationConfigUtils
|
||||
* #registerAnnotationConfigProcessors(org.springframework.beans.factory.support.BeanDefinitionRegistry)
|
||||
* @see MergedContextConfiguration#getActiveProfiles()
|
||||
* @see org.springframework.context.annotation.AnnotationConfigUtils#registerAnnotationConfigProcessors(org.springframework.beans.factory.support.BeanDefinitionRegistry)
|
||||
* @see org.springframework.context.ConfigurableApplicationContext#getEnvironment()
|
||||
*/
|
||||
ApplicationContext loadContext(MergedContextConfiguration mergedConfig) throws Exception;
|
||||
|
|
|
|||
Loading…
Reference in New Issue