Package org.springframework.test.context.cache

# 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 and a custom eviction policy.

As of Spring Framework 6.1, this SPI includes optional support for tracking and incrementing failure counts.

### 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()`

## 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 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.
`org.springframework.context.ApplicationContext`
`get(MergedContextConfiguration key)`
Obtain a cached `ApplicationContext` for the given key.
`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)`
Explicitly add an `ApplicationContext` instance to the cache under the given key, potentially honoring a custom eviction policy.
`void`
`remove(MergedContextConfiguration key, 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.

## 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

## 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.

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:
  - `remove(org.springframework.test.context.MergedContextConfiguration, org.springframework.test.annotation.DirtiesContext.HierarchyMode)`

### put

void put(MergedContextConfiguration key, org.springframework.context.ApplicationContext context)
Explicitly add an `ApplicationContext` instance to the cache under the given key, potentially honoring a custom eviction policy.

Parameters:
  `key` - the context key (never `null`)
  `context` - the `ApplicationContext` instance (never `null`)

### 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)`

### 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()
- parent context count
- hit count
- miss count
- any other information useful for monitoring the state of this cache