Polishing

spring-test/src/main/java/org/springframework/test/context/cache/ContextCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,8 +22,8 @@ import org.springframework.test.context.MergedContextConfiguration;
 
 /**
  * {@code ContextCache} defines the SPI for caching Spring
- * {@link ApplicationContext ApplicationContexts} within the <em>Spring
- * TestContext Framework</em>.
+ * {@link ApplicationContext ApplicationContexts} within the
+ * <em>Spring TestContext Framework</em>.
  *
  * <p>A {@code ContextCache} maintains a cache of {@code ApplicationContexts}
  * keyed by {@link MergedContextConfiguration} instances.
@@ -47,7 +47,7 @@ public interface ContextCache {
 	 * The name of the logging category used for reporting {@code ContextCache}
 	 * statistics.
 	 */
-	public static final String CONTEXT_CACHE_LOGGING_CATEGORY = "org.springframework.test.context.cache";
+	String CONTEXT_CACHE_LOGGING_CATEGORY = "org.springframework.test.context.cache";
 
 
 	/**
@@ -59,8 +59,8 @@ public interface ContextCache {
 
 	/**
 	 * Obtain a cached {@code ApplicationContext} for the given key.
-	 * <p>The {@link #getHitCount() hit} and {@link #getMissCount() miss} counts
-	 * must be updated accordingly.
+	 * <p>The {@linkplain #getHitCount() hit} and {@linkplain #getMissCount() miss}
+	 * counts must be updated accordingly.
 	 * @param key the context key (never {@code null})
 	 * @return the corresponding {@code ApplicationContext} instance, or {@code null}
 	 * if not found in the cache
@@ -70,7 +70,7 @@ public interface ContextCache {
 
 	/**
 	 * Explicitly add an {@code ApplicationContext} instance to the cache
-	 * under the given key.
+	 * under the given key, potentially honoring a custom eviction policy.
 	 * @param key the context key (never {@code null})
 	 * @param context the {@code ApplicationContext} instance (never {@code null})
 	 */
@@ -80,9 +80,10 @@ public interface ContextCache {
 	 * Remove the context with the given key from the cache and explicitly
 	 * {@linkplain org.springframework.context.ConfigurableApplicationContext#close() close}
 	 * it if it is an instance of {@code ConfigurableApplicationContext}.
-	 * <p>Generally speaking, this method should be called if the state of
-	 * a singleton bean has been modified, potentially affecting future
-	 * interaction with the context.
+	 * <p>Generally speaking, this method should be called to properly evict
+	 * a context from the cache (e.g., due to a custom eviction policy) or if
+	 * the state of a singleton bean has been modified, potentially affecting
+	 * future interaction with the context.
 	 * <p>In addition, the semantics of the supplied {@code HierarchyMode} must
 	 * be honored. See the Javadoc for {@link HierarchyMode} for details.
 	 * @param key the context key; never {@code null}