[SPR-8240] polishing the "Context management and caching" section of the...

[SPR-8240] polishing the "Context management and caching" section of the reference manual and related Javadoc.

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

@@ -116,19 +116,19 @@ public @interface ContextConfiguration {
 	 * {@link #classes configuration classes} from superclasses should be
 	 * <em>inherited</em>.
 	 * 
-	 * <p>The default value is <code>true</code>, which means that an annotated
+	 * <p>The default value is <code>true</code>. This means that an annotated
 	 * class will <em>inherit</em> the resource locations or configuration
-	 * classes defined by an annotated superclass. Specifically, the resource
+	 * classes defined by annotated superclasses. Specifically, the resource
 	 * locations or configuration classes for an annotated class will be
 	 * appended to the list of resource locations or configuration classes
-	 * defined by an annotated superclass. Thus, subclasses have the option of
+	 * defined by annotated superclasses. Thus, subclasses have the option of
 	 * <em>extending</em> the list of resource locations or configuration
 	 * classes.
 	 * 
 	 * <p>If <code>inheritLocations</code> is set to <code>false</code>, the
 	 * resource locations or configuration classes for the annotated class
 	 * will <em>shadow</em> and effectively replace any resource locations 
-	 * or configuration classes defined by a superclass.
+	 * or configuration classes defined by superclasses.
 	 * 
 	 * <p>In the following example that uses path-based resource locations, the
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}

org.springframework.test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java

@@ -152,10 +152,10 @@ public abstract class AbstractContextLoader implements SmartContextLoader {
 
 	/**
 	 * Generate a modified version of the supplied locations array and return it.
-	 * <p>A plain path &mdash; for example, &quot;context.xml&quot; &mdash;
-	 * will be treated as a classpath resource from the same package in which
+	 * <p>A plain path &mdash; for example, &quot;context.xml&quot; &mdash; will
+	 * be treated as a classpath resource that is relative to the package in which
 	 * the specified class is defined. A path starting with a slash is treated
-	 * as a fully qualified classpath location, for example:
+	 * as an absolute classpath location, for example:
 	 * &quot;/org/springframework/whatever/foo.xml&quot;. A path which
 	 * references a URL (e.g., a path prefixed with
 	 * {@link ResourceUtils#CLASSPATH_URL_PREFIX classpath:},

spring-framework-reference/src/testing.xml

@@ -1101,8 +1101,8 @@ public class MyTest {
         <para>In contrast to the deprecated JUnit 3.8 legacy class hierarchy,
         test classes that use the TestContext framework do not need to
         override any <literal>protected</literal> instance methods to
-        configure their application context. Rather, configuration is achieved
-        merely by declaring the
+        configure their application context. Instead, configuration is
+        achieved merely by declaring the
         <interfacename>@ContextConfiguration</interfacename> annotation at the
         class level. If your test class does not explicitly declare
         application context resource <literal>locations</literal> or
@@ -1111,9 +1111,9 @@ public class MyTest {
         context from a default location or default configuration
         classes.</para>
 
-        <para>The following sections explain how to configure and manage
-        <interfacename>ApplicationContext</interfacename>s via XML
-        configuration files and <interfacename>@Configuration</interfacename>
+        <para>The following sections explain how to configure and manage an
+        <interfacename>ApplicationContext</interfacename> via XML
+        configuration files or <interfacename>@Configuration</interfacename>
         classes using Spring's
         <interfacename>@ContextConfiguration</interfacename>
         annotation.</para>
@@ -1121,28 +1121,28 @@ public class MyTest {
         <section id="testcontext-ctx-management-xml">
           <title>Context management with XML resources</title>
 
-          <para>To load an
-          <interfacename>ApplicationContextAware</interfacename> for your
-          tests from XML configuration files, annotate your test class with
-          <interfacename>@ContextConfiguration</interfacename> and configure
-          the <literal>locations</literal> attribute with an array that
-          contains the resource locations of XML configuration metadata. A
-          plain path — for example <literal>"context.xml"</literal> — will be
-          treated as a classpath resource from the package in which the test
-          class is defined. A path starting with a slash is treated as a fully
-          qualified classpath location, for example
+          <para>To load an <interfacename>ApplicationContext</interfacename>
+          for your tests from XML configuration files, annotate your test
+          class with <interfacename>@ContextConfiguration</interfacename> and
+          configure the <literal>locations</literal> attribute with an array
+          that contains the resource locations of XML configuration metadata.
+          A plain path — for example <literal>"context.xml"</literal> — will
+          be treated as a classpath resource that is relative to the package
+          in which the test class is defined. A path starting with a slash is
+          treated as an absolute classpath location, for example
           <literal>"/org/example/config.xml"</literal>. A path which
-          represents a URL (i.e., a path prefixed with
+          represents a resource URL (i.e., a path prefixed with
           <literal>classpath:</literal>, <literal>file:</literal>,
           <literal>http:</literal>, etc.) will be used <emphasis>as
           is</emphasis>. Alternatively, you can implement and configure your
-          own custom <interfacename>ContextLoader</interfacename> for advanced
-          use cases.</para>
+          own custom <interfacename>ContextLoader</interfacename> or
+          <interfacename>SmartContextLoader</interfacename> for advanced use
+          cases.</para>
 
           <programlisting language="java">@RunWith(SpringJUnit4ClassRunner.class)
-<lineannotation>// ApplicationContext will be loaded from "/applicationContext.xml" and
-// "/applicationContext-test.xml" in the root of the classpath</lineannotation>
-<emphasis role="bold">@ContextConfiguration(locations={"/applicationContext.xml", "/applicationContext-test.xml"})</emphasis>
+<lineannotation>// ApplicationContext will be loaded from "/app-config.xml" and
+// "/test-config.xml" in the root of the classpath</lineannotation>
+<emphasis role="bold">@ContextConfiguration(locations={"/app-config.xml", "/test-config.xml"})</emphasis>
 public class MyTest {
     <lineannotation>// class body...</lineannotation>
 }</programlisting>
@@ -1157,7 +1157,7 @@ public class MyTest {
           demonstrated in the following example.</para>
 
           <programlisting language="java">@RunWith(SpringJUnit4ClassRunner.class)
-<emphasis role="bold">@ContextConfiguration({"/applicationContext.xml", "/applicationContext-test.xml"})</emphasis>
+<emphasis role="bold">@ContextConfiguration({"/app-config.xml", "/test-config.xml"})</emphasis>
 public class MyTest {
     <lineannotation>// class body...</lineannotation>
 }</programlisting>
@@ -1187,20 +1187,20 @@ public class MyTest {
         <section id="testcontext-ctx-management-javaconfig">
           <title>Context management with @Configuration classes</title>
 
-          <para>To load an
-          <interfacename>ApplicationContextAware</interfacename> for your
-          tests from <interfacename>@Configuration</interfacename> classes,
-          annotate your test class with
+          <para>To load an <interfacename>ApplicationContext</interfacename>
+          for your tests from <interfacename>@Configuration</interfacename>
+          classes, annotate your test class with
           <interfacename>@ContextConfiguration</interfacename> and configure
           the <literal>classes</literal> attribute with an array that contains
           class references to configuration classes. Alternatively, you can
           implement and configure your own custom
-          <interfacename>ContextLoader</interfacename> for advanced use
+          <interfacename>ContextLoader</interfacename> or
+          <interfacename>SmartContextLoader</interfacename> for advanced use
           cases.</para>
 
           <programlisting language="java">@RunWith(SpringJUnit4ClassRunner.class)
-<lineannotation>// ApplicationContext will be loaded from AppConfig and TestAppConfig</lineannotation>
-<emphasis role="bold">@ContextConfiguration(classes={AppConfig.class, TestAppConfig.class})</emphasis>
+<lineannotation>// ApplicationContext will be loaded from AppConfig and TestConfig</lineannotation>
+<emphasis role="bold">@ContextConfiguration(classes={AppConfig.class, TestConfig.class})</emphasis>
 public class MyTest {
     <lineannotation>// class body...</lineannotation>
 }</programlisting>
@@ -1259,32 +1259,42 @@ public class OrderServiceTest {
           a boolean <literal>inheritLocations</literal> attribute that denotes
           whether resource locations or configuration classes declared by
           superclasses should be <emphasis>inherited</emphasis>. The default
-          value is <literal>true</literal>, which means that an annotated
-          class inherits the resource locations or configuration classes
-          declared by an annotated superclass. Specifically, the resource
-          locations or configuration classes for an annotated test class are
-          appended to the list of resource locations or configuration classes
-          declared by an annotated superclass. Thus, subclasses have the
-          option of <emphasis>extending</emphasis> the list of resource
-          locations or configuration classes. In the following example that
-          uses XML resource locations, the
+          value is <literal>true</literal>. This means that an annotated class
+          inherits the resource locations or configuration classes declared by
+          any annotated superclasses. Specifically, the resource locations or
+          configuration classes for an annotated test class are appended to
+          the list of resource locations or configuration classes declared by
+          annotated superclasses. Thus, subclasses have the option of
+          <emphasis>extending</emphasis> the list of resource locations or
+          configuration classes.</para>
+
+          <para>If <interfacename>@ContextConfiguration</interfacename>'s
+          <literal>inheritLocations</literal> attribute is set to
+          <literal>false</literal>, the resource locations or configuration
+          classes for the annotated class <emphasis>shadow</emphasis> and
+          effectively replace any resource locations or configuration classes
+          defined by superclasses.</para>
+
+          <para>In the following example that uses XML resource locations, the
           <interfacename>ApplicationContext</interfacename> for
           <classname>ExtendedTest</classname> will be loaded from
-          "base-context.xml" <emphasis role="bold">and</emphasis>
-          "extended-context.xml", in that order. Beans defined in
-          "extended-context.xml" may therefore <emphasis>override</emphasis>
-          (i.e., replace) those defined in "base-context.xml".</para>
+          <emphasis>"base-config.xml"</emphasis> <emphasis
+          role="bold">and</emphasis>
+          <emphasis>"extended-config.xml"</emphasis>, in that order. Beans
+          defined in <emphasis>"extended-config.xml"</emphasis> may therefore
+          <emphasis>override</emphasis> (i.e., replace) those defined in
+          <emphasis>"base-config.xml"</emphasis>.</para>
 
           <programlisting language="java">@RunWith(SpringJUnit4ClassRunner.class)
-<lineannotation>// ApplicationContext will be loaded from <literal>"/base-context.xml"</literal> in the root of the classpath</lineannotation>
-<emphasis role="bold">@ContextConfiguration("/base-context.xml")</emphasis>
+<lineannotation>// ApplicationContext will be loaded from <literal>"/base-config.xml"</literal> in the root of the classpath</lineannotation>
+<emphasis role="bold">@ContextConfiguration("/base-config.xml")</emphasis>
 public class BaseTest {
     <lineannotation>// class body...</lineannotation>
 }
 
-<lineannotation>// ApplicationContext will be loaded from <literal>"/base-context.xml"</literal> and <literal>"/extended-context.xml"</literal></lineannotation>
+<lineannotation>// ApplicationContext will be loaded from <literal>"/base-config.xml"</literal> and <literal>"/extended-config.xml"</literal></lineannotation>
 <lineannotation>// in the root of the classpath</lineannotation>
-<emphasis role="bold">@ContextConfiguration("/extended-context.xml")</emphasis>
+<emphasis role="bold">@ContextConfiguration("/extended-config.xml")</emphasis>
 public class ExtendedTest extends BaseTest {
     <lineannotation>// class body...</lineannotation>
 }</programlisting>
@@ -1299,24 +1309,17 @@ public class ExtendedTest extends BaseTest {
           replace) those defined in <classname>BaseConfig</classname>.</para>
 
           <programlisting language="java">@RunWith(SpringJUnit4ClassRunner.class)
-<lineannotation>// ApplicationContext will be loaded from <literal>"/base-context.xml"</literal> in the root of the classpath</lineannotation>
+<lineannotation>// ApplicationContext will be loaded from BaseConfig</lineannotation>
 <emphasis role="bold">@ContextConfiguration(classes=BaseConfig.class)</emphasis>
 public class BaseTest {
     <lineannotation>// class body...</lineannotation>
 }
 
-<lineannotation>// ApplicationContext will be loaded from <literal>"/base-context.xml"</literal> and <literal>"/extended-context.xml"</literal></lineannotation>
-<lineannotation>// in the root of the classpath</lineannotation>
+<lineannotation>// ApplicationContext will be loaded from BaseConfig and ExtendedConfig</lineannotation>
 <emphasis role="bold">@ContextConfiguration(classes=ExtendedConfig.class)</emphasis>
 public class ExtendedTest extends BaseTest {
     <lineannotation>// class body...</lineannotation>
 }</programlisting>
-
-          <para>If <interfacename>@ContextConfiguration</interfacename>'s
-          <literal>inheritLocations</literal> attribute is set to
-          <literal>false</literal>, the resource locations or configuration
-          classes for the annotated class shadow and effectively replace any
-          resource locations defined by a superclass.</para>
         </section>
 
         <section id="testcontext-ctx-management-caching">
@@ -1327,20 +1330,23 @@ public class ExtendedTest extends BaseTest {
           for a test it will be reused for <emphasis
           role="bold">all</emphasis> subsequent tests that declare the same
           unique context configuration within the same process — for example,
-          all tests run in a suite in an IDE or all tests run for the same
-          project from a build framework like Ant or Maven. Thus the setup
-          cost for loading the application context is incurred only once (per
+          all tests run in a suite within an IDE or all tests run for the same
+          project with a build framework like Ant or Maven. Thus the setup
+          cost for loading an application context is incurred only once (per
           test suite), and subsequent test execution is much faster.</para>
 
           <para>In the unlikely case that a test corrupts the application
           context and requires reloading — for example, by modifying a bean
           definition or the state of an application object — you can annotate
           your test class or test method with
-          <interfacename>@DirtiesContext</interfacename> (assuming
-          <classname>DirtiesContextTestExecutionListener</classname> has been
-          configured, which is the default). This instructs Spring to reload
-          the configuration and rebuild the application context before
-          executing the next test.</para>
+          <interfacename>@DirtiesContext</interfacename> (see the discussion
+          of <interfacename>@DirtiesContext</interfacename> in <xref
+          linkend="integration-testing-annotations-spring" />). This instructs
+          Spring to reload the configuration and rebuild the application
+          context before executing the next test. Note that support for the
+          <interfacename>@DirtiesContext</interfacename> annotation is enabled
+          via the <classname>DirtiesContextTestExecutionListener</classname>
+          which is enabled by default.</para>
         </section>
       </section>