|
35 | 35 | * <p>As of Spring Framework 6.1, this SPI includes optional support for
|
36 | 36 | * {@linkplain #getFailureCount(MergedContextConfiguration) tracking} and
|
37 | 37 | * {@linkplain #incrementFailureCount(MergedContextConfiguration) incrementing}
|
38 |
| - * failure counts. |
| 38 | + * failure counts. As of Spring Framework 7.0, this SPI includes optional support for |
| 39 | + * {@linkplain #registerContextUsage(MergedContextConfiguration, Class) registering} and |
| 40 | + * {@linkplain #unregisterContextUsage(MergedContextConfiguration, Class) unregistering} |
| 41 | + * context usage. |
39 | 42 | *
|
40 | 43 | * <h3>Rationale</h3>
|
41 | 44 | * <p>Context caching can have significant performance benefits if context
|
@@ -88,13 +91,19 @@ public interface ContextCache {
|
88 | 91 | boolean contains(MergedContextConfiguration key);
|
89 | 92 |
|
90 | 93 | /**
|
91 |
| - * Obtain a cached {@code ApplicationContext} for the given key. |
92 |
| - * <p>The {@linkplain #getHitCount() hit} and {@linkplain #getMissCount() miss} |
93 |
| - * counts must be updated accordingly. |
| 94 | + * Obtain a cached {@link ApplicationContext} for the given key. |
| 95 | + * <p>If the cached application context was previously |
| 96 | + * {@linkplain org.springframework.context.Lifecycle#stop() stopped}, it |
| 97 | + * must be |
| 98 | + * {@linkplain org.springframework.context.support.AbstractApplicationContext#restart() |
| 99 | + * restarted}. This applies to parent contexts as well. |
| 100 | + * <p>In addition, the {@linkplain #getHitCount() hit} and |
| 101 | + * {@linkplain #getMissCount() miss} counts must be updated accordingly. |
94 | 102 | * @param key the context key (never {@code null})
|
95 | 103 | * @return the corresponding {@code ApplicationContext} instance, or {@code null}
|
96 | 104 | * if not found in the cache
|
97 |
| - * @see #remove |
| 105 | + * @see #unregisterContextUsage(MergedContextConfiguration, Class) |
| 106 | + * @see #remove(MergedContextConfiguration, HierarchyMode) |
98 | 107 | */
|
99 | 108 | @Nullable ApplicationContext get(MergedContextConfiguration key);
|
100 | 109 |
|
@@ -151,6 +160,64 @@ default int getFailureCount(MergedContextConfiguration key) {
|
151 | 160 | * @see #getFailureCount(MergedContextConfiguration)
|
152 | 161 | */
|
153 | 162 | default void incrementFailureCount(MergedContextConfiguration key) {
|
| 163 | + /* no-op */ |
| 164 | + } |
| 165 | + |
| 166 | + /** |
| 167 | + * Register usage of the {@link ApplicationContext} for the supplied |
| 168 | + * {@link MergedContextConfiguration} and any of its parents. |
| 169 | + * <p>The default implementation of this method does nothing. Concrete |
| 170 | + * implementations are therefore highly encouraged to override this |
| 171 | + * method, {@link #unregisterContextUsage(MergedContextConfiguration, Class)}, |
| 172 | + * and {@link #getContextUsageCount()} with appropriate behavior. Note that |
| 173 | + * the standard {@code ContextContext} implementation in Spring overrides |
| 174 | + * these methods appropriately. |
| 175 | + * @param key the context key; never {@code null} |
| 176 | + * @param testClass the test class that is using the application context(s) |
| 177 | + * @since 7.0 |
| 178 | + * @see #unregisterContextUsage(MergedContextConfiguration, Class) |
| 179 | + * @see #getContextUsageCount() |
| 180 | + */ |
| 181 | + default void registerContextUsage(MergedContextConfiguration key, Class<?> testClass) { |
| 182 | + /* no-op */ |
| 183 | + } |
| 184 | + |
| 185 | + /** |
| 186 | + * Unregister usage of the {@link ApplicationContext} for the supplied |
| 187 | + * {@link MergedContextConfiguration} and any of its parents. |
| 188 | + * <p>If no other test classes are actively using the same application |
| 189 | + * context(s), the application context(s) should be |
| 190 | + * {@linkplain org.springframework.context.Lifecycle#stop() stopped}. |
| 191 | + * <p>The default implementation of this method does nothing. Concrete |
| 192 | + * implementations are therefore highly encouraged to override this |
| 193 | + * method, {@link #registerContextUsage(MergedContextConfiguration, Class)}, |
| 194 | + * and {@link #getContextUsageCount()} with appropriate behavior. Note that |
| 195 | + * the standard {@code ContextContext} implementation in Spring overrides |
| 196 | + * these methods appropriately. |
| 197 | + * @param key the context key; never {@code null} |
| 198 | + * @param testClass the test class that is no longer using the application context(s) |
| 199 | + * @since 7.0 |
| 200 | + * @see #registerContextUsage(MergedContextConfiguration, Class) |
| 201 | + * @see #getContextUsageCount() |
| 202 | + */ |
| 203 | + default void unregisterContextUsage(MergedContextConfiguration key, Class<?> testClass) { |
| 204 | + /* no-op */ |
| 205 | + } |
| 206 | + |
| 207 | + /** |
| 208 | + * Determine the number of contexts within the cache that are currently in use. |
| 209 | + * <p>The default implementation of this method always returns {@code 0}. |
| 210 | + * Concrete implementations are therefore highly encouraged to override this |
| 211 | + * method, {@link #registerContextUsage(MergedContextConfiguration, Class)}, |
| 212 | + * and {@link #unregisterContextUsage(MergedContextConfiguration, Class)} with |
| 213 | + * appropriate behavior. Note that the standard {@code ContextContext} |
| 214 | + * implementation in Spring overrides these methods appropriately. |
| 215 | + * @since 7.0 |
| 216 | + * @see #registerContextUsage(MergedContextConfiguration, Class) |
| 217 | + * @see #unregisterContextUsage(MergedContextConfiguration, Class) |
| 218 | + */ |
| 219 | + default int getContextUsageCount() { |
| 220 | + return 0; |
154 | 221 | }
|
155 | 222 |
|
156 | 223 | /**
|
@@ -204,6 +271,7 @@ default void incrementFailureCount(MergedContextConfiguration key) {
|
204 | 271 | * <ul>
|
205 | 272 | * <li>name of the concrete {@code ContextCache} implementation</li>
|
206 | 273 | * <li>{@linkplain #size}</li>
|
| 274 | + * <li>{@linkplain #getContextUsageCount() context usage count}</li> |
207 | 275 | * <li>{@linkplain #getParentContextCount() parent context count}</li>
|
208 | 276 | * <li>{@linkplain #getHitCount() hit count}</li>
|
209 | 277 | * <li>{@linkplain #getMissCount() miss count}</li>
|
|
0 commit comments