Document context hierarchy support in the TCF

This commit adds examples to the Javadoc for @ContextHierarchy and
updates the Javadoc for @ContextConfiguration accordingly.

Issue: SPR-10357

Author: sbrannen

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -287,13 +287,14 @@
 	/**
 	 * The name of the context hierarchy level represented by this configuration.
 	 *
-	 * <p>If not specified the name will be inferred based on the numerical level within all
-	 * declared contexts within the hierarchy.
+	 * <p>If not specified the name will be inferred based on the numerical level
+	 * within all declared contexts within the hierarchy.
 	 *
-	 * <p>This attribute is only applicable when used within a test class hierarchy that is
-	 * configured using {@link ContextHierarchy @ContextHierarchy}, in which case the name
-	 * can be used for merging or overriding this configuration with configuration of the
-	 * same name in hierarchy levels defined in superclasses.
+	 * <p>This attribute is only applicable when used within a test class hierarchy
+	 * that is configured using {@code @ContextHierarchy}, in which case the name
+	 * can be used for <em>merging</em> or <em>overriding</em> this configuration
+	 * with configuration of the same name in hierarchy levels defined in superclasses.
+	 * See the Javadoc for {@link ContextHierarchy @ContextHierarchy} for details.
 	 *
 	 * @since 3.2.2
 	 */

spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java

@@ -28,6 +28,109 @@
  * a hierarchy of {@link org.springframework.context.ApplicationContext
  * ApplicationContexts} for integration tests.
  *
+ * <h2>Examples</h2>
+ * <p>The following JUnit-based examples demonstrate common configuration
+ * scenarios for integration tests that require the use of context hierarchies.
+ *
+ * <h3>Single Test Class with Context Hierarchy</h3>
+ * <p>{@code ControllerIntegrationTests} represents a typical integration testing
+ * scenario for a Spring MVC web application by declaring a context hierarchy
+ * consisting of two levels, one for the <em>root</em> {@code WebApplicationContext}
+ * (with {@code TestAppConfig}) and one for the <em>dispatcher servlet</em>
+ * {@code WebApplicationContext} (with {@code WebConfig}). The {@code
+ * WebApplicationContext} that is <em>autowired</em> into the test instance is
+ * the one for the child context (i.e., the lowest context in the hierarchy).
+ *
+ * <pre class="code">
+ * &#064;RunWith(SpringJUnit4ClassRunner.class)
+ * &#064;WebAppConfiguration
+ * &#064;ContextHierarchy({
+ *     &#064;ContextConfiguration(classes = TestAppConfig.class),
+ *     &#064;ContextConfiguration(classes = WebConfig.class)
+ * })
+ * public class ControllerIntegrationTests {
+ *
+ *     &#064;Autowired
+ *     private WebApplicationContext wac;
+ *
+ *     // ...
+ * }</pre>
+ *
+ * <h3>Class Hierarchy with Implicit Parent Context</h3>
+ * <p>The following test classes define a context hierarchy within a test class
+ * hierarchy. {@code AbstractWebTests} declares the configuration for a root
+ * {@code WebApplicationContext} in a Spring-powered web application. Note,
+ * however, that {@code AbstractWebTests} does not declare {@code @ContextHierarchy};
+ * consequently, subclasses of {@code AbstractWebTests} can optionally participate
+ * in a context hierarchy or follow the standard semantics for {@code @ContextConfiguration}.
+ * {@code SoapWebServiceTests} and {@code RestWebServiceTests} both extend
+ * {@code AbstractWebTests} and define a context hierarchy via {@code @ContextHierarchy}.
+ * The result is that three application contexts will be loaded (one for each
+ * declaration of {@code @ContextConfiguration}, and the application context
+ * loaded based on the configuration in {@code AbstractWebTests} will be set as
+ * the parent context for each of the contexts loaded for the concrete subclasses. 
+ *
+ * <pre class="code">
+ * &#064;RunWith(SpringJUnit4ClassRunner.class)
+ * &#064;WebAppConfiguration
+ * &#064;ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml")
+ * public abstract class AbstractWebTests {}
+ *
+ * &#064;ContextHierarchy(&#064;ContextConfiguration("/spring/soap-ws-config.xml")
+ * public class SoapWebServiceTests extends AbstractWebTests {}
+ *
+ * &#064;ContextHierarchy(&#064;ContextConfiguration("/spring/rest-ws-config.xml")
+ * public class RestWebServiceTests extends AbstractWebTests {}</pre>
+ *
+ * <h3>Class Hierarchy with Merged Context Hierarchy Configuration</h3>
+ * <p>The following classes demonstrate the use of <em>named</em> hierarchy levels
+ * in order to <em>merge</em> the configuration for specific levels in a context
+ * hierarchy. {@code BaseTests} defines two levels in the hierarchy, {@code parent}
+ * and {@code child}. {@code ExtendedTests} extends {@code BaseTests} and instructs
+ * the Spring TestContext Framework to merge the context configuration for the
+ * {@code child} hierarchy level, simply by ensuring that the names declared via
+ * {@link ContextConfiguration#name} are both {@code "child"}. The result is that
+ * three application contexts will be loaded: one for {@code "/app-config.xml"},
+ * one for {@code "/user-config.xml"}, and one for <code>{"/user-config.xml",
+ * "/order-config.xml"}</code>. As with the previous example, the application
+ * context loaded from {@code "/app-config.xml"} will be set as the parent context
+ * for the contexts loaded from {@code "/user-config.xml"} and <code>{"/user-config.xml",
+ * "/order-config.xml"}</code>.
+ *
+ * <pre class="code">
+ * &#064;RunWith(SpringJUnit4ClassRunner.class)
+ * &#064;ContextHierarchy({
+ *     &#064;ContextConfiguration(name = "parent", locations = "/app-config.xml"),
+ *     &#064;ContextConfiguration(name = "child",  locations = "/user-config.xml")
+ * })
+ * public class BaseTests {}
+ * 
+ * &#064;ContextHierarchy(
+ *     &#064;ContextConfiguration(name = "child",  locations = "/order-config.xml")
+ * )
+ * public class ExtendedTests extends BaseTests {}</pre>
+ *
+ * <h3>Class Hierarchy with Overridden Context Hierarchy Configuration</h3>
+ * <p>In contrast to the previous example, this example demonstrates how to
+ * <em>override</em> the configuration for a given named level in a context hierarchy
+ * by setting the {@link ContextConfiguration#inheritLocations} flag to {@code false}.
+ * Consequently, the application context for {@code ExtendedTests} will be loaded
+ * only from {@code "/test-user-config.xml"} and will have its parent set to the
+ * context loaded from {@code "/app-config.xml"}. 
+ *
+ * <pre class="code">
+ * &#064;RunWith(SpringJUnit4ClassRunner.class)
+ * &#064;ContextHierarchy({
+ *     &#064;ContextConfiguration(name = "parent", locations = "/app-config.xml"),
+ *     &#064;ContextConfiguration(name = "child",  locations = "/user-config.xml")
+ * })
+ * public class BaseTests {}
+ * 
+ * &#064;ContextHierarchy(
+ *     &#064;ContextConfiguration(name = "child",  locations = "/test-user-config.xml", inheritLocations=false)
+ * )
+ * public class ExtendedTests extends BaseTests {}</pre>
+ *
  * @author Sam Brannen
  * @since 3.2.2
  * @see ContextConfiguration
@@ -47,7 +150,7 @@
 	 * of the context hierarchy within a test class hierarchy, you must explicitly
 	 * name that level by supplying the same value to the {@link ContextConfiguration#name
 	 * name} attribute in {@code @ContextConfiguration} at each level in the
-	 * class hierarchy.
+	 * class hierarchy. See the class-level Javadoc for examples.
 	 */
 	ContextConfiguration[] value();