[SPR-8240] polishing the "Context management and caching" section of the reference manual and related Javadoc.
This commit is contained in:
Sam Brannen
parent
1bb5b21881
commit
5db7cca9a7
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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 — for example, "context.xml" —
|
||||
* will be treated as a classpath resource from the same package in which
|
||||
* <p>A plain path — for example, "context.xml" — 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:
|
||||
* "/org/springframework/whatever/foo.xml". A path which
|
||||
* references a URL (e.g., a path prefixed with
|
||||
* {@link ResourceUtils#CLASSPATH_URL_PREFIX classpath:},
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue