From 72548f7611d16b925158a1e6964c3bca91a0451c Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Tue, 2 Aug 2022 13:48:53 +0300 Subject: [PATCH] Improve documentation of SmartContextLoader contracts --- .../test/context/SmartContextLoader.java | 82 +++++++++++-------- 1 file changed, 48 insertions(+), 34 deletions(-) diff --git a/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java index d0e7e5351d..6faf0c5105 100644 --- a/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java @@ -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. * *

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()}. * *

See the Javadoc for {@link ContextConfiguration @ContextConfiguration} * for a definition of annotated class. @@ -45,11 +47,8 @@ import org.springframework.lang.Nullable; * hierarchy of the root test class and then supplied to * {@link #loadContext(MergedContextConfiguration) loadContext()}. * - *

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. + *

NOTE: As of Spring Framework 6.0, {@code SmartContextLoader} no longer + * supports methods defined in the {@code ContextLoader} SPI. * *

Concrete implementations must provide a {@code public} no-args constructor. * @@ -58,43 +57,45 @@ import org.springframework.lang.Nullable; *

  • {@link org.springframework.test.context.support.DelegatingSmartContextLoader DelegatingSmartContextLoader}
    • *
  • {@link org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader}
    • *
  • {@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}
    • + *
  • {@link org.springframework.test.context.support.GenericGroovyXmlContextLoader GenericGroovyXmlContextLoader}
    • *
  • {@link org.springframework.test.context.web.WebDelegatingSmartContextLoader WebDelegatingSmartContextLoader}
    • *
  • {@link org.springframework.test.context.web.AnnotationConfigWebContextLoader AnnotationConfigWebContextLoader}
    • *
  • {@link org.springframework.test.context.web.GenericXmlWebContextLoader GenericXmlWebContextLoader}
    • + *
  • {@link org.springframework.test.context.web.GenericGroovyXmlWebContextLoader GenericGroovyXmlWebContextLoader}
    • * * * @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. *

    Concrete implementations may choose to modify the {@code locations} - * or {@code classes} in the supplied {@link ContextConfigurationAttributes}, + * or {@code classes} in the supplied {@code ContextConfigurationAttributes}, * generate default configuration locations, or detect * default configuration classes if the supplied values are {@code null} * or empty. - *

    Note: in contrast to a standard {@code ContextLoader}, a - * {@code SmartContextLoader} must preemptively 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. + *

    Note: a {@code SmartContextLoader} must preemptively + * 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 - * refreshed state. + * configure the context, and return the context in a fully refreshed + * state. *

    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}. - *

    Any {@code ApplicationContext} loaded by a - * {@code 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). + * should perform the following actions. + *

    * @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;