Interface ContextCache

All Known Implementing Classes:

DefaultContextCache

public interface ContextCache

ContextCache defines the SPI for caching Spring ApplicationContexts within the Spring TestContext Framework.

A ContextCache maintains a cache of ApplicationContexts keyed by MergedContextConfiguration instances, potentially configured with a maximum size, pause mode, and custom eviction policy.

As of Spring Framework 6.1, this SPI includes optional support for tracking and incrementing failure counts. As of Spring Framework 7.0, this SPI includes optional support for registering and unregistering context usage.

Rationale

Context caching can have significant performance benefits if context initialization is complex. Although the initialization of a Spring context itself is typically very quick, some beans in a context — for example, an embedded database or a LocalContainerEntityManagerFactoryBean for working with JPA — may take several seconds to initialize. Hence, it often makes sense to perform that initialization only once per test suite or JVM process.

Since:

4.2

Author:

Sam Brannen, Juergen Hoeller

See Also:

• ContextCacheUtils.retrieveMaxCacheSize()
• ContextCacheUtils.retrievePauseMode()

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ContextCache.LoadFunction	Represents a function that loads an ApplicationContext.
static enum	ContextCache.PauseMode	Enumeration of modes that dictate whether inactive application contexts stored in the ContextCache should be paused.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CONTEXT_CACHE_LOGGING_CATEGORY	The name of the logging category used for reporting ContextCache statistics.
static final String	CONTEXT_CACHE_PAUSE_PROPERTY_NAME	System property used to configure whether inactive application contexts stored in the ContextCache should be paused: "spring.test.context.cache.pause".
static final int	DEFAULT_MAX_CONTEXT_CACHE_SIZE	The default maximum size of the context cache: 32.
static final String	MAX_CONTEXT_CACHE_SIZE_PROPERTY_NAME	System property used to configure the maximum size of the ContextCache as a positive integer: "spring.test.context.cache.maxSize".

Method Summary

Modifier and Type	Method	Description
void	clear()	Clear all contexts from the cache, clearing context hierarchy information as well.
void	clearStatistics()	Clear hit count and miss count statistics for the cache (i.e., reset counters to zero).
boolean	contains(MergedContextConfiguration key)	Determine whether there is a cached context for the given key.
@Nullable org.springframework.context.ApplicationContext	get(MergedContextConfiguration key)	Obtain a cached ApplicationContext for the given key.
default int	getContextUsageCount()	Determine the number of contexts within the cache that are currently in use.
default int	getFailureCount(MergedContextConfiguration key)	Get the failure count for the given key.
int	getHitCount()	Get the overall hit count for this cache.
int	getMissCount()	Get the overall miss count for this cache.
int	getParentContextCount()	Determine the number of parent contexts currently tracked within the cache.
default void	incrementFailureCount(MergedContextConfiguration key)	Increment the failure count for the given key.
void	logStatistics()	Log the statistics for this ContextCache at DEBUG level using the "org.springframework.test.context.cache" logging category.
void	put(MergedContextConfiguration key, org.springframework.context.ApplicationContext context)	Deprecated. since Spring Framework 7.0 in favor of put(MergedContextConfiguration, LoadFunction)
default org.springframework.context.ApplicationContext	put(MergedContextConfiguration key, ContextCache.LoadFunction loadFunction)	Explicitly add an ApplicationContext to the cache under the given key, potentially honoring a custom eviction policy.
default void	registerContextUsage(MergedContextConfiguration key, Class<?> testClass)	Register usage of the ApplicationContext for the supplied MergedContextConfiguration and any of its parents.
void	remove(MergedContextConfiguration key, @Nullable DirtiesContext.HierarchyMode hierarchyMode)	Remove the context with the given key from the cache and explicitly close it if it is an instance of ConfigurableApplicationContext.
void	reset()	Reset all state maintained by this cache including statistics.
int	size()	Determine the number of contexts currently stored in the cache.
default void	unregisterContextUsage(MergedContextConfiguration key, Class<?> testClass)	Unregister usage of the ApplicationContext for the supplied MergedContextConfiguration and any of its parents.

Field Details

CONTEXT_CACHE_LOGGING_CATEGORY

static final String CONTEXT_CACHE_LOGGING_CATEGORY

The name of the logging category used for reporting ContextCache statistics.

See Also:

• Constant Field Values

DEFAULT_MAX_CONTEXT_CACHE_SIZE

static final int DEFAULT_MAX_CONTEXT_CACHE_SIZE

The default maximum size of the context cache: 32.

Since:

4.3

See Also:

• MAX_CONTEXT_CACHE_SIZE_PROPERTY_NAME
• Constant Field Values

MAX_CONTEXT_CACHE_SIZE_PROPERTY_NAME

static final String MAX_CONTEXT_CACHE_SIZE_PROPERTY_NAME

System property used to configure the maximum size of the ContextCache as a positive integer: "spring.test.context.cache.maxSize".

May alternatively be configured via the SpringProperties mechanism.

Note that implementations of ContextCache are not required to actually support a maximum cache size. Consult the documentation of the corresponding implementation for details.

Since:

4.3

See Also:

• DEFAULT_MAX_CONTEXT_CACHE_SIZE
• Constant Field Values

CONTEXT_CACHE_PAUSE_PROPERTY_NAME

static final String CONTEXT_CACHE_PAUSE_PROPERTY_NAME

System property used to configure whether inactive application contexts stored in the ContextCache should be paused: "spring.test.context.cache.pause".

Defaults to on_context_switch. Can be set to always or never to disable pausing of inactive application contexts — for example:

-Dspring.test.context.cache.pause=never

May alternatively be configured via the SpringProperties mechanism.

Note that implementations of ContextCache are not required to support context pausing. Consult the documentation of the corresponding implementation for details.

Since:

7.0.3

See Also:

• ContextCache.PauseMode
• ConfigurableApplicationContext.pause()
• unregisterContextUsage(MergedContextConfiguration, Class)
• Constant Field Values

Method Details

contains

boolean contains(MergedContextConfiguration key)

Determine whether there is a cached context for the given key.

Parameters:

key - the context key; never null

Returns:

true if the cache contains a context with the given key

get

@Nullable org.springframework.context.ApplicationContext get(MergedContextConfiguration key)

Obtain a cached ApplicationContext for the given key.

If the cached application context was previously paused, it must be restarted. This applies to parent contexts as well.

In addition, the hit and miss counts must be updated accordingly.

Parameters:

key - the context key; never null

Returns:

the corresponding ApplicationContext instance, or null if not found in the cache

See Also:

• put(MergedContextConfiguration, LoadFunction)
• unregisterContextUsage(MergedContextConfiguration, Class)
• remove(MergedContextConfiguration, HierarchyMode)

put

@Deprecated(since="7.0")
void put(MergedContextConfiguration key,
 org.springframework.context.ApplicationContext context)

Deprecated.

since Spring Framework 7.0 in favor of put(MergedContextConfiguration, LoadFunction)

Explicitly add an ApplicationContext to the cache under the given key, potentially honoring a custom eviction policy.

Parameters:

key - the context key; never null

context - the ApplicationContext; never null

See Also:

• get(MergedContextConfiguration)
• put(MergedContextConfiguration, LoadFunction)

put

default org.springframework.context.ApplicationContext put(MergedContextConfiguration key,
 ContextCache.LoadFunction loadFunction)

Explicitly add an ApplicationContext to the cache under the given key, potentially honoring a custom eviction policy.

The supplied ContextCache.LoadFunction will be invoked to load the ApplicationContext.

Concrete implementations which honor a custom eviction policy must override this method to ensure that an evicted context is removed from the cache and closed before a new context is loaded via the supplied LoadFunction.

Parameters:

key - the context key; never null

loadFunction - a function which loads the context for the supplied key; never null

Returns:

the ApplicationContext; never null

Since:

7.0

See Also:

• get(MergedContextConfiguration)
• put(MergedContextConfiguration, ApplicationContext)

remove

void remove(MergedContextConfiguration key,
 @Nullable DirtiesContext.HierarchyMode hierarchyMode)

Remove the context with the given key from the cache and explicitly close it if it is an instance of ConfigurableApplicationContext.

Generally speaking, this method should be called to properly evict a context from the cache (for example, due to a custom eviction policy) or if the state of a singleton bean has been modified, potentially affecting future interaction with the context.

In addition, the semantics of the supplied HierarchyMode must be honored. See the Javadoc for DirtiesContext.HierarchyMode for details.

Parameters:

key - the context key; never null

hierarchyMode - the hierarchy mode; may be null if the context is not part of a hierarchy

getFailureCount

default int getFailureCount(MergedContextConfiguration key)

Get the failure count for the given key.

A failure is any attempt to load the ApplicationContext for the given key that results in an exception.

The default implementation of this method always returns 0. Concrete implementations are therefore highly encouraged to override this method and incrementFailureCount(MergedContextConfiguration) with appropriate behavior. Note that the standard ContextContext implementation in Spring overrides these methods appropriately.

Parameters:

key - the context key; never null

Since:

6.1

See Also:

• incrementFailureCount(MergedContextConfiguration)

incrementFailureCount

default void incrementFailureCount(MergedContextConfiguration key)

Increment the failure count for the given key.

The default implementation of this method does nothing. Concrete implementations are therefore highly encouraged to override this method and getFailureCount(MergedContextConfiguration) with appropriate behavior. Note that the standard ContextContext implementation in Spring overrides these methods appropriately.

Parameters:

key - the context key; never null

Since:

6.1

See Also:

• getFailureCount(MergedContextConfiguration)

registerContextUsage

default void registerContextUsage(MergedContextConfiguration key,
 Class<?> testClass)

Register usage of the ApplicationContext for the supplied MergedContextConfiguration and any of its parents.

The default implementation of this method does nothing. Concrete implementations are therefore highly encouraged to override this method, unregisterContextUsage(MergedContextConfiguration, Class), and getContextUsageCount() with appropriate behavior. Note that the standard ContextContext implementation in Spring overrides these methods appropriately.

Parameters:

key - the context key; never null

testClass - the test class that is using the application context(s)

Since:

7.0

See Also:

• unregisterContextUsage(MergedContextConfiguration, Class)
• getContextUsageCount()

unregisterContextUsage

default void unregisterContextUsage(MergedContextConfiguration key,
 Class<?> testClass)

Unregister usage of the ApplicationContext for the supplied MergedContextConfiguration and any of its parents.

If no other test classes are actively using the same application context(s), the application context(s) should be paused according to the configured ContextCache.PauseMode.

The default implementation of this method does nothing. Concrete implementations are therefore highly encouraged to override this method, registerContextUsage(MergedContextConfiguration, Class), and getContextUsageCount() with appropriate behavior. Note that the standard ContextContext implementation in Spring overrides these methods appropriately.

Parameters:

key - the context key; never null

testClass - the test class that is no longer using the application context(s)

Since:

7.0

See Also:

• registerContextUsage(MergedContextConfiguration, Class)
• getContextUsageCount()

getContextUsageCount

default int getContextUsageCount()

Determine the number of contexts within the cache that are currently in use.

The default implementation of this method always returns 0. Concrete implementations are therefore highly encouraged to override this method, registerContextUsage(MergedContextConfiguration, Class), and unregisterContextUsage(MergedContextConfiguration, Class) with appropriate behavior. Note that the standard ContextContext implementation in Spring overrides these methods appropriately.

Since:

7.0

See Also:

• registerContextUsage(MergedContextConfiguration, Class)
• unregisterContextUsage(MergedContextConfiguration, Class)

size

int size()

Determine the number of contexts currently stored in the cache.

If the cache contains more than Integer.MAX_VALUE elements, this method must return Integer.MAX_VALUE.

getParentContextCount

int getParentContextCount()

Determine the number of parent contexts currently tracked within the cache.

getHitCount

int getHitCount()

Get the overall hit count for this cache.

A hit is any access to the cache that returns a non-null context for the queried key.

getMissCount

int getMissCount()

Get the overall miss count for this cache.

A miss is any access to the cache that returns a null context for the queried key.

reset

void reset()

Reset all state maintained by this cache including statistics.

See Also:

• clear()
• clearStatistics()

clear

void clear()

Clear all contexts from the cache, clearing context hierarchy information as well.

clearStatistics

void clearStatistics()

Clear hit count and miss count statistics for the cache (i.e., reset counters to zero).

logStatistics

void logStatistics()

Log the statistics for this ContextCache at DEBUG level using the "org.springframework.test.context.cache" logging category.

The following information should be logged.

• name of the concrete ContextCache implementation
• size()
• context usage count
• parent context count
• hit count
• miss count
• any other information useful for monitoring the state of this cache