org.springframework.test.context.support Documentation Differences

This file contains all the changes in documentation in the package org.springframework.test.context.support as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Abstract application context loader that provides a basis for all concrete implementations of the ContextLoader SPI. Provides a Template Method based approach for processing resource locations.

As of Spring 3.1, AbstractContextLoader also provides a basis for all concrete implementations of the SmartContextLoader SPI. For backwards compatibility with the {@code ContextLoader} SPI, .processContextConfiguration(ContextConfigurationAttributes) delegatesdelegates to .processLocations(Class, String...). @author Sam Brannen @author Juergen Hoeller @since 2.5 @see #generateDefaultLocations @see #modifyLocations

Generate the default classpath resource locations array based on the supplied class.

For example, if the supplied class is com.example.MyTest, the generated locations will contain a single string with a value of "classpath:/com/example/MyTest<suffix>", where <suffix> is the value of the resource suffix string.

As of Spring 3.1, the implementation of this method adheres to the contract defined in the SmartContextLoader SPI. Specifically, this method will preemptively verify that the generated default location actually exists. If it does not exist, this method will log a warning and return an empty array.

Subclasses can override this method to implement a different default location generation strategy. @param clazz the class for which the default locations are to be generated @return an array of default application context resource locations @since 2.5 @see #getResourceSuffix()

Get the suffix to append to ApplicationContext resource locationsresource locations when generating default locations.

Must be implemented by subclasses. @return the resource suffix; should not be null or empty @since 2.5 @see #generateDefaultLocations(Class)

Determine whether or not default resource locations should be generated if the locations provided to .processLocations(Class, String...) are null or empty.

As of Spring 3.1, the semantics of this method have been overloaded to include detection of either default resource locations or default configuration classes. Consequently, this method can also be used to to determine whether or not default configuration classes should be detected if the classes present in the configuration attributes supplied to .processContextConfiguration(ContextConfigurationAttributes) are null or empty.

Can be overridden by subclasses to change the default behavior. @return always true by default @since 2.5

Generate a modified version of the supplied locations array and return it.

A plain path — for example, "context.xml" — will be treated as a classpath resource that is relative to the package in which the specified class is defined. A path starting with a slash is treated as an absolute classpath location, for example: "/org/springframework/whatever/foo.xml". A path which references a URL (e.g., a path prefixed with classpath:, file:, http:, etc.) will be added to the results unchanged.

Subclasses can override this method to implement a different location modification strategy. @param clazz the class with which the locations are associated @param locations the resource locations to be modified @return an array of modified application context resource locations @since 2.5

For backwards compatibility with the ContextLoader SPI, the default implementation simply delegates to .processLocations(Class, String...), passing it the declaring class and resource locations retrieved from the supplied configuration attributes. The processed locations are then set in the supplied configuration attributes.

Can be overridden in subclasses — for example, to process configurationannotated classes instead of resource locations. @since 3.1 @see #processLocations(Class, String...)

If the supplied locations are null or empty and .isGenerateDefaultLocations() returns true, default locations will be generated for the specified class and the configured resource suffix; otherwise, the supplied locations will be modified if necessary and returned. @param clazz the class with which the locations are associated: to be used when generating default locations @param locations the unmodified locations to use for loading the application context (can be null or empty) @return a processed array of application context resource locations @since 2.5 @see #isGenerateDefaultLocations() @see #generateDefaultLocations(Class) @see #modifyLocations(Class, String...) @see org.springframework.test.context.ContextLoader#processLocations(Class, String...) @see #processContextConfiguration(ContextConfigurationAttributes)

Abstract, generic extension of AbstractContextLoader that loads a GenericApplicationContext.

• If instances of concrete subclasses are invoked via the ContextLoader SPI, the context will be loaded from the locations provided to .loadContext(String...).
• If instances of concrete subclasses are invoked via the SmartContextLoader SPI, the context will be loaded from the MergedContextConfiguration provided to .loadContext(MergedContextConfiguration). In such cases, a a SmartContextLoader will decide whether to load the context from locations or or configurationannotated classes.

Concrete subclasses must provide an appropriate implementation of createBeanDefinitionReader(), potentially overriding loadBeanDefinitions() as well. @author Sam Brannen @author Juergen Hoeller @since 2.5 @see #loadContext(MergedContextConfiguration) @see #loadContext(String...)

Factory method for creating a new BeanDefinitionReader for loading bean definitions into the supplied context. @param context the context for which the BeanDefinitionReader should be created @return a BeanDefinitionReader for the supplied context @see #loadContext(String...) @see #loadBeanDefinitions @see BeanDefinitionReader @since 2.5

Customize the internal bean factory of the ApplicationContext created by this ContextLoader.

The default implementation is empty but can be overridden in subclasses to customize DefaultListableBeanFactory's standard settings. @param beanFactory the bean factory created by this ContextLoader @see #loadContext(MergedContextConfiguration) @see #loadContext(String...) @see DefaultListableBeanFactory#setAllowBeanDefinitionOverriding @see DefaultListableBeanFactory#setAllowEagerClassLoading @see DefaultListableBeanFactory#setAllowCircularReferences @see DefaultListableBeanFactory#setAllowRawInjectionDespiteWrapping @since 2.5

Customize the GenericApplicationContext created by this ContextLoader after bean definitions have been loaded into the context but before the context is refreshed.

The default implementation is empty but can be overridden in subclasses to customize the application context. @param context the newly created application context @see #loadContext(MergedContextConfiguration) @see #loadContext(String...) @since 2.5

Load bean definitions into the supplied context from the configuration locations or classes in the supplied supplied MergedContextConfiguration.

The default implementation delegates to the BeanDefinitionReader returned by .createBeanDefinitionReader(GenericApplicationContext) to to load the bean definitions.

Subclasses must provide an appropriate implementation of .createBeanDefinitionReader(GenericApplicationContext). Alternatively subclasses may subclasses may provide a no-op implementation of {@code createBeanDefinitionReader()} and override this method to provide a custom strategy for loading or registering bean definitions. @param context the context into which the bean definitions should be loaded @param mergedConfig the merged context configuration configuration @see #loadContext(MergedContextConfiguration) @since 3.1

Load a Spring ApplicationContext from the supplied MergedContextConfiguration.

Implementation details:

• Creates a GenericApplicationContext instance.
• Sets the active bean definition profiles from the supplied MergedContextConfiguration in the Environment of the context. Calls .prepareContext(GenericApplicationContext, MergedContextConfiguration) to allow for customizing the context context before bean definitions are loaded.
• Calls .customizeBeanFactory(DefaultListableBeanFactory) to allow for customizing the context's DefaultListableBeanFactory.
• Delegates to .loadBeanDefinitions(GenericApplicationContext, MergedContextConfiguration) to populate the context context from the configuration locations or classes in the supplied MergedContextConfiguration.
• Delegates to AnnotationConfigUtils for registering annotation configuration processors.
• Calls .customizeContext(GenericApplicationContext) to allow for customizing the context before it is refreshed.
• Refreshes the context and registers a JVM shutdown hook for it.

@return a new application context @see org.springframework.test.context.SmartContextLoader#loadContext(MergedContextConfiguration) @see GenericApplicationContext @since 3.1

Load a Spring ApplicationContext from the supplied locations.

Implementation details:

• Creates a GenericApplicationContext instance.
• Calls .prepareContext(GenericApplicationContext) to allow for customizing the context before bean definitions are loaded.
• Calls .customizeBeanFactory(DefaultListableBeanFactory) to allow for customizing the context's DefaultListableBeanFactory.
• Delegates to .createBeanDefinitionReader(GenericApplicationContext) to create a a BeanDefinitionReader which is then used to populate the context from the specified config locations.
• Delegates to AnnotationConfigUtils for registering annotation configuration processors.
• Calls .customizeContext(GenericApplicationContext) to allow for customizing the context before it is refreshed.
• Refreshes the context and registers a JVM shutdown hook for it.

Note: this method does not provide a means to set active bean definition profiles for the loaded context. See .loadContext(MergedContextConfiguration) and .prepareContext(GenericApplicationContext, MergedContextConfiguration) for an alternative. @return a new application context @see org.springframework.test.context.ContextLoader#loadContext @see GenericApplicationContext @see #loadContext(MergedContextConfiguration) @since 2.5

Prepare the GenericApplicationContext created by this ContextLoader. Called before bean definitions are read.

The default implementation is empty. Can be overridden in subclasses to customize GenericApplicationContext's standard settings. @param context the context that should be prepared @see #loadContext(MergedContextConfiguration) @see #loadContext(String...) @see GenericApplicationContext#setAllowBeanDefinitionOverriding @see GenericApplicationContext#setResourceLoader @see GenericApplicationContext#setId @since 2.5

Concrete implementation of AbstractGenericContextLoader that loads bean definitions from from configurationannotated classes.

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

Note: AnnotationConfigContextLoader supports supports configurationannotated classes rather than the String-based resource locations defined by the legacy ContextLoader API. Thus, although AnnotationConfigContextLoader extends AbstractGenericContextLoader, AnnotationConfigContextLoader does not support any String-based methods defined by AbstractContextLoader or AbstractGenericContextLoader. Consequently, AnnotationConfigContextLoader should chiefly be considered a SmartContextLoader rather than a ContextLoader. @author Sam Brannen @since 3.1 @see #processContextConfiguration(ContextConfigurationAttributes) @see #detectDefaultConfigurationClasses(Class) @see #loadBeanDefinitions(GenericApplicationContext, MergedContextConfiguration)

AnnotationConfigContextLoader should be used as a a SmartContextLoader, not as a legacy ContextLoader. Consequently, this method is not supported. @see #loadBeanDefinitions @see AbstractGenericContextLoader#createBeanDefinitionReader @throws UnsupportedOperationException

Detect the default configuration classes for the supplied test class.

The returned class array will contain all static inner classes of the supplied class that meet the requirements for {@code @Configuration} class implementations as specified in the documentation for @Configuration.

The implementation of this method adheres to the contract defined in the SmartContextLoader SPI. Specifically, this method uses introspection to detect default default configuration classes that comply with the constraints required of {@code @Configuration} class implementations. If a potential candidate configuration class does not meet these requirements, this method will log a warning, and the potential candidate class will be ignored. @param declaringClass the test class that declared {@code @ContextConfiguration} @return an array of default configuration classes, potentially empty but never null

AnnotationConfigContextLoader should be used as a SmartContextLoader, not as a legacy ContextLoader. Consequently, this method is not supported. @see AbstractContextLoader#generateDefaultLocations @throws UnsupportedOperationException

AnnotationConfigContextLoader should be used as a a SmartContextLoader, not as a legacy ContextLoader. Consequently, this method is not supported. @see AbstractContextLoader#getResourceSuffix @throws UnsupportedOperationException

Register configuration classes in the supplied context from the classes classes in the supplied MergedContextConfiguration.

Each class must represent an annotated configuration class or component. An AnnotatedBeanDefinitionReader is used to register the appropriate bean definitions.

Note that this method does not call .createBeanDefinitionReader() since AnnotatedBeanDefinitionReader is not an instance of BeanDefinitionReader. @param context the context in which the configurationannotated classes should be registered @param mergedConfig the merged configuration from which the classes should be retrieved retrieved @see AbstractGenericContextLoader#loadBeanDefinitions

AnnotationConfigContextLoader should be used as a SmartContextLoader, not as a legacy ContextLoader. Consequently, this method is not supported. @see AbstractContextLoader#modifyLocations @throws UnsupportedOperationException

Process configurationannotated classes in the supplied ContextConfigurationAttributes.

If the configurationannotated classes are null or empty and .isGenerateDefaultLocations() returns true, this SmartContextLoader will attempt to detect default configuration classes. If defaults are detected they will be set in the supplied configuration attributes. Otherwise, properties in the supplied configuration attributes will not be modified. @param configAttributes the context configuration attributes to process @see org.springframework.test.context.SmartContextLoader#processContextConfiguration(ContextConfigurationAttributes) @see #isGenerateDefaultLocations() @see #detectDefaultConfigurationClasses(Class)

{@code DelegatingSmartContextLoader} is an implementation of the SmartContextLoader SPI that delegates to a set of candidate SmartContextLoaders (i.e., GenericXmlContextLoader and AnnotationConfigContextLoader) 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 {@code @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 {@code @ContextConfiguration}, {@code DelegatingSmartContextLoader} will be used as the default loader, thus providing automatic support for either XML configuration files or configurationannotated 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 ContextConfiguration#initializers application context initializers. In such cases, an attempt will still be made to detect defaults, but their absence will not result an an exception. @author Sam Brannen @since 3.1 @see SmartContextLoader @see GenericXmlContextLoader @see AnnotationConfigContextLoader

Delegates to an appropriate candidate {@code SmartContextLoader} to load an ApplicationContext.

Delegation is based on explicit knowledge of the implementations of GenericXmlContextLoader and AnnotationConfigContextLoader. Specifically, the delegation algorithm is as follows:

• If the resource locations in the supplied {@code MergedContextConfiguration} are not empty and the configurationannotated classes are empty, {@code GenericXmlContextLoader} will load the {@code ApplicationContext}.
• If the configurationannotated classes in the supplied {@code MergedContextConfiguration} are not empty and the resource locations are empty, {@code AnnotationConfigContextLoader} will load the {@code ApplicationContext}.

@param mergedConfig the merged context configuration to use to load the application context @throws IllegalArgumentException if the supplied merged configuration is null @throws IllegalStateException if neither candidate loader is capable of loading an {@code ApplicationContext} from the supplied merged context configuration

Delegates to candidate {@code SmartContextLoaders} to process the supplied ContextConfigurationAttributes.

Delegation is based on explicit knowledge of the implementations of GenericXmlContextLoader and AnnotationConfigContextLoader. Specifically, the delegation algorithm is as follows:

• If the resource locations or configurationannotated classes in the supplied {@code 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, {@code GenericXmlContextLoader} will be allowed to process the configuration in order to detect default resource locations. If {@code GenericXmlContextLoader} detects default resource locations, an {@code info} message will be logged.
• Subsequently, {@code AnnotationConfigContextLoader} will be allowed to process the configuration in order to detect default configuration classes. If {@code AnnotationConfigContextLoader} detects default configuration classes, an {@code info} message will be logged.

@param 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 configurationannotated classes @throws IllegalStateException if {@code GenericXmlContextLoader} detects default configuration classes; if {@code AnnotationConfigContextLoader} 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

Marks the application context of the supplied test context as dirty, and sets the REINJECT_DEPENDENCIES_ATTRIBUTE in the test context to true .