Document testing in "New in Spring 3.2" sect.

This commit adds documentation to the "New Features and Enhancements in
Spring 3.2" section of the reference manual regarding new testing
features.

Issue: SPR-9941
This commit is contained in:
Sam Brannen 2012-12-12 01:38:23 +01:00
parent a1053d4364
commit d4c55838ad
1 changed files with 216 additions and 179 deletions

View File

@ -1,225 +1,262 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="new-in-3.2"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<chapter version="5.0"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
xml:id="new-in-3.2" xmlns="http://docbook.org/ns/docbook"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:ns="http://docbook.org/ns/docbook">
<title>New Features and Enhancements in Spring 3.2</title>
<section xml:id="new-in-3.2-features-overview">
<title>Overview of new features</title>
<section xml:id="new-in-3.2-webmvc-async">
<title>Support for Servlet 3 based asynchronous request processing</title>
<section xml:id="new-in-3.2-webmvc-async">
<title>Support for Servlet 3 based asynchronous request processing</title>
<para>The Spring MVC programming model now provides explicit Servlet 3
async support. <interfacename>@RequestMapping</interfacename> methods can
return one of:</para>
<para>The Spring MVC programming model now provides explicit Servlet 3 async support.
<interfacename>@RequestMapping</interfacename> methods can return one of:</para>
<itemizedlist>
<listitem>
<para><interfacename>java.util.concurrent.Callable</interfacename> to
complete processing in a separate thread managed by a task executor
within Spring MVC.</para>
</listitem>
<itemizedlist>
<listitem>
<para><interfacename>java.util.concurrent.Callable</interfacename> to
complete processing in a separate thread managed by a task executor
within Spring MVC.</para>
</listitem>
<listitem>
<para><classname>org.springframework.web.context.request.async.DeferredResult</classname>
to complete processing at a later time from a thread not known to
Spring MVC, e.g. in response to some external event (JSM, AMQP, etc.)</para>
</listitem>
<listitem>
<para><classname>org.springframework.web.context.request.async.AsyncTask</classname>
to wrap a <interfacename>Callable</interfacename> and
customize the timeout value or the task executor to use.</para>
</listitem>
</itemizedlist>
<listitem>
<para><classname>org.springframework.web.context.request.async.DeferredResult</classname>
to complete processing at a later time from a thread not known to
Spring MVC — for example, in response to some external event (JMS,
AMQP, etc.)</para>
</listitem>
<para>See <link
xl:href="http://blog.springsource.org/2012/05/06/spring-mvc-3-2-preview-introducing-servlet-3-async-support/">
Introducing Servlet 3 Async Support</link> (SpringSource team blog).</para>
<listitem>
<para><classname>org.springframework.web.context.request.async.AsyncTask</classname>
to wrap a <interfacename>Callable</interfacename> and customize the
timeout value or the task executor to use.</para>
</listitem>
</itemizedlist>
</section>
<para>See <link
xl:href="http://blog.springsource.org/2012/05/06/spring-mvc-3-2-preview-introducing-servlet-3-async-support/">
Introducing Servlet 3 Async Support</link> (SpringSource team
blog).</para>
</section>
<section xml:id="new-in-3.2-spring-mvc-test">
<title>Spring MVC Test framework</title>
<section xml:id="new-in-3.2-spring-mvc-test">
<title>Spring MVC Test framework</title>
<para>First-class support for testing Spring MVC applications with a
fluent API and without a servlet container. Server-side tests involve
use of the <classname>DispatcherServlet</classname> while client-side
REST tests rely on the <classname>RestTemplate</classname>.
See <xref linkend="spring-mvc-test-framework"/>.
</para>
<para>First-class support for testing Spring MVC applications with a
fluent API and without a Servlet container. Server-side tests involve use
of the <classname>DispatcherServlet</classname> while client-side REST
tests rely on the <classname>RestTemplate</classname>. See <xref
linkend="spring-mvc-test-framework" />.</para>
</section>
</section>
<section xml:id="new-in-3.2-webmvc-content-negotiation">
<title>Content negotiation improvements</title>
<section xml:id="new-in-3.2-webmvc-content-negotiation">
<title>Content negotiation improvements</title>
<para>A <interfacename>ContentNeogtiationStrategy</interfacename> is now
available for resolving the requested media types from an incoming
request. The available implementations are based on path extension,
request parameter, 'Accept' header, and a fixed default content type.
Equivalent options were previously available only in the
ContentNegotiatingViewResolver but are now available throughout.</para>
<para>A <interfacename>ContentNeogtiationStrategy</interfacename> is now
available for resolving the requested media types from an incoming request.
The available implementations are based on path extension, request parameter,
'Accept' header, and a fixed default content type. Equivalent options were
previously available only in the ContentNegotiatingViewResolver but are now
available throughout.</para>
<para><classname>ContentNegotiationManager</classname> is the central
class to use when configuring content negotiation options. It accepts one
or more ContentNeogtiationStrategy instances and delegates to them. It can
be plugged into <classname>RequestMappingHandlerMapping</classname>,
<classname>RequestMappingHandlerAdapter</classname>,
<classname>ExceptionHandlerExceptionResolver</classname>, and
<classname>ContentNegotiatingViewResolver</classname>. The MVC namespace
and the MVC JavaConfig provide convenient options to configure all
that.</para>
<para><classname>ContentNegotiationManager</classname> is the central class to
use when configuring content negotiation options. It accepts one or
more ContentNeogtiationStrategy instances and delegates to them. It can be
plugged into <classname>RequestMappingHandlerMapping</classname>,
<classname>RequestMappingHandlerAdapter</classname>,
<classname>ExceptionHandlerExceptionResolver</classname>,
and <classname>ContentNegotiatingViewResolver</classname>. The MVC
namespace and the MVC Java config provide convenient options to configure
all that.</para>
<para>The introduction of <classname>ContentNegotiationManger</classname>
also enables smart suffix pattern matching for incoming requests. See
<link
xl:href="https://github.com/SpringSource/spring-framework/commit/4fd7645">commit
message.</link></para>
</section>
<para>The introduction of <classname>ContentNegotiationManger</classname>
also enables smart suffix pattern matching for incoming requests.
See <link xl:href="https://github.com/SpringSource/spring-framework/commit/4fd7645">
commit message</link></para>
<section xml:id="new-in-3.2-webmvc-controller-advice">
<title><interfacename>@ControllerAdvice</interfacename> annotation</title>
</section>
<para>Classes annotated with
<interfacename>@ControllerAdvice</interfacename> can contain
<interfacename>@ExceptionHandler</interfacename>,
<interfacename>@InitBinder</interfacename>, and
<interfacename>@ModelAttribute</interfacename> methods and those will
apply to <interfacename>@RequestMapping</interfacename> methods across
controller hierarchies as opposed to the controller hierarchy within which
they are declared. <interfacename>@ControllerAdvice</interfacename> is a
component annotation allowing implementation classes to be auto-detected
through classpath scanning.</para>
</section>
<section xml:id="new-in-3.2-webmvc-controller-advice">
<title><interfacename>@ControllerAdvice</interfacename> annotation</title>
<section xml:id="new-in-3.2-matrix-variables">
<title>Matrix variables</title>
<para>Classes annotated with <interfacename>@ControllerAdvice</interfacename>
can contain <interfacename>@ExceptionHandler</interfacename>,
<interfacename>@InitBinder</interfacename>, and
<interfacename>@ModelAttribute</interfacename> methods and those will apply
to <interfacename>@RequestMapping</interfacename> methods across controller
hierarchies as opposed to the controller hierarchy within which they are declared.
<interfacename>@ControllerAdvice</interfacename> is
a component annotation allowing implementation classes to be auto-detected
through classpath scanning.</para>
<para>A new <interfacename>@MatrixVariable</interfacename> annotation adds
support for extracting matrix variables from the request URI. For more
details see <xref linkend="mvc-ann-matrix-variables" />.</para>
</section>
</section>
<section xml:id="new-in-3.2-dispatcher-servlet-initializer">
<title>Abstract base class for code-based Servlet 3+ container
initialization</title>
<section xml:id="new-in-3.2-matrix-variables">
<title>Matrix variables</title>
<para>An abstract base class implementation of the
<interfacename>WebApplicationInitializer</interfacename> interface is
provided to simplify code-based registration of a DispatcherServlet and
filters mapped to it. The new class is named
<classname>AbstractDispatcherServletInitializer</classname> and its
sub-class
<classname>AbstractAnnotationConfigDispatcherServletInitializer</classname>
can be used with Java-based Spring configuration. For more details see
<xref linkend="mvc-container-config" />.</para>
</section>
<para>A new <interfacename>@MatrixVariable</interfacename> annotation
adds support for extracting matrix variables from the request URI.
For more details see <xref linkend="mvc-ann-matrix-variables"/>.</para>
</section>
<section xml:id="new-in-3.2-webmvc-exception-handler-support">
<title><classname>ResponseEntityExceptionHandler</classname> class</title>
<section xml:id="new-in-3.2-dispatcher-servlet-initializer">
<title>Abstract base class for code-based Servlet 3+ container initialization</title>
<para>A convenient base class with an
<interfacename>@ExceptionHandler</interfacename> method that handles
standard Spring MVC exceptions and returns a
<classname>ResponseEntity</classname> that allowing customizing and
writing the response with HTTP message converters. This servers as an
alternative to the <classname>DefaultHandlerExceptionResolver</classname>,
which does the same but returns a <classname>ModelAndView</classname>
instead.</para>
<para>An abstract base class implementation of the
<interfacename>WebApplicationInitializer</interfacename> interface is provided to
simplify code-based registration of a DispatcherServlet and filters
mapped to it. The new class is named
<classname>AbstractDispatcherServletInitializer</classname> and its
sub-class <classname>AbstractAnnotationConfigDispatcherServletInitializer</classname>
can be used with Java-based Spring configuration.
For more details see <xref linkend="mvc-container-config"/>.</para>
</section>
<para>See the revised <xref linkend="mvc-exceptionhandlers" /> including
information on customizing the default Servlet container error
page.</para>
</section>
<section xml:id="new-in-3.2-webmvc-exception-handler-support">
<title><classname>ResponseEntityExceptionHandler</classname> class</title>
<section xml:id="new-in-3.2-webmvc-generic-types-rest-template">
<title>Support for generic types in the
<classname>RestTemplate</classname> and in
<interfacename>@RequestBody</interfacename> arguments</title>
<para>A convenient base class with an
<interfacename>@ExceptionHandler</interfacename>
method that handles standard Spring MVC exceptions and returns a
<classname>ResponseEntity</classname> that allowing customizing and writing
the response with HTTP message converters. This servers as an alternative
to the <classname>DefaultHandlerExceptionResolver</classname>, which does
the same but returns a <classname>ModelAndView</classname> instead.</para>
<para>The <classname>RestTemplate</classname> can now read an HTTP
response to a generic type (e.g. <code>List&lt;Account&gt;</code>). There
are three new <code>exchange()</code> methods that accept
<classname>ParameterizedTypeReference</classname>, a new class that
enables capturing and passing generic type info.</para>
<para>See the revised <xref linkend="mvc-exceptionhandlers"/>
including information on customizing the default Servlet container error page.</para>
<para>In support of this feature, the
<interfacename>HttpMessageConverter</interfacename> is extended by
<interfacename>GenericHttpMessageConverter</interfacename> adding a method
for reading content given a specified parameterized type. The new
interface is implemented by the
<classname>MappingJacksonHttpMessageConverter</classname> and also by a
new <classname>Jaxb2CollectionHttpMessageConverter</classname> that can
read read a generic <interfacename>Collection</interfacename> where the
generic type is a JAXB type annotated with
<interfacename>@XmlRootElement</interfacename> or
<interfacename>@XmlType</interfacename>.</para>
</section>
</section>
<section xml:id="new-in-3.2-webmvc-jackson-json">
<title>Jackson JSON 2 and related improvements</title>
<section xml:id="new-in-3.2-webmvc-generic-types-rest-template">
<title>Support for generic types in the <classname>RestTemplate</classname> and in
<interfacename>@RequestBody</interfacename> arguments</title>
<para>The Jackson JSON 2 library is now supported. Due to packaging
changes in the Jackson library, there are separate classes in Spring MVC
as well. Those are
<classname>MappingJackson2HttpMessageConverter</classname> and
<classname>MappingJackson2JsonView</classname>. Other related
configuration improvements include support for pretty printing as well as
a <classname>JacksonObjectMapperFactoryBean</classname> for convenient
customization of an <classname>ObjectMapper</classname> in XML
configuration.</para>
</section>
<para>The <classname>RestTemplate</classname> can now read an HTTP
response to a generic type (e.g. <code>List&lt;Account&gt;</code>).
There are three new <code>exchange()</code> methods that accept
<classname>ParameterizedTypeReference</classname>, a
new class that enables capturing and passing generic type info.</para>
<section xml:id="new-in-3.2-webmvc-request-body-arg-with-binding-result">
<title><interfacename>@RequestBody</interfacename> improvements</title>
<para>In support of this feature, the <interfacename>HttpMessageConverter</interfacename>
is extended by <interfacename>GenericHttpMessageConverter</interfacename>
adding a method for reading content given a specified parameterized type.
The new interface is implemented by the
<classname>MappingJacksonHttpMessageConverter</classname> and also
by a new <classname>Jaxb2CollectionHttpMessageConverter</classname> that can
read read a generic <interfacename>Collection</interfacename> where the
generic type is a JAXB type annotated with
<interfacename>@XmlRootElement</interfacename> or
<interfacename>@XmlType</interfacename>.</para>
<para>An <interfacename>@RequestBody</interfacename> or an
<interfacename>@RequestPart</interfacename> argument can now be followed
by an <interfacename>Errors</interfacename> argument making it possible to
handle validation errors (as a result of an
<interfacename>@Valid</interfacename> annotation) locally within the
<interfacename>@RequestMapping</interfacename> method.
<interfacename>@RequestBody</interfacename> now also supports a required
flag.</para>
</section>
</section>
<section xml:id="new-in-3.2-webmvc-http-patch">
<title>HTTP PATCH method</title>
<section xml:id="new-in-3.2-webmvc-jackson-json">
<title>Jackson JSON 2 and related improvements</title>
<para>The HTTP request method <code>PATCH</code> may now be used in
<interfacename>@RequestMapping</interfacename> methods as well as in the
<classname>RestTemplate</classname> in conjunction with Apache
HttpComponents HttpClient version 4.2 or later. The JDK
<classname>HttpURLConnection</classname> does not support the
<code>PATCH</code> method.</para>
</section>
<para>The Jackson Json 2 library is now supported. Due to packaging changes in
the Jackson library, there are separate classes in Spring MVC as well. Those are
<classname>MappingJackson2HttpMessageConverter</classname> and
<classname>MappingJackson2JsonView</classname>.
Other related configuration improvements include support for
pretty printing as well as a
<classname>JacksonObjectMapperFactoryBean</classname> for convenient
customization of an <classname>ObjectMapper</classname> in
XML configuration.</para>
<section xml:id="new-in-3.2-webmvc-mapped-interceptor-exclude-patterns">
<title>Excluded patterns in mapped interceptors</title>
</section>
<para>Mapped interceptors now support URL patterns to be excluded. The MVC
namespace and the MVC JavaConfig both expose these options.</para>
</section>
<section xml:id="new-in-3.2-webmvc-request-body-arg-with-binding-result">
<title><interfacename>@RequestBody</interfacename> improvements</title>
<section xml:id="new-in-3.2-date-time-format-without-joda">
<title>Support for <interfacename>@DateTimeFormat</interfacename> without
Joda Time</title>
<para>An <interfacename>@RequestBody</interfacename> or an
<interfacename>@RequestPart</interfacename> argument can now be followed by an
<interfacename>Errors</interfacename> argument making it possible to handle
validation errors (as a result of an <interfacename>@Valid</interfacename>
annotation) locally within the <interfacename>@RequestMapping</interfacename> method.
<interfacename>@RequestBody</interfacename> now also supports
a required flag.</para>
<para>The <interfacename>@DateTimeFormat</interfacename> annotation can
now be used without needing a dependency on the Joda Time library. If Joda
Time is not present the JDK <classname>SimpleDateFormat</classname> will
be used to parse and print date patterns. When Joda Time is present it
will continue to be used in preference to
<classname>SimpleDateFormat</classname>.</para>
</section>
</section>
<section xml:id="new-in-3.2-global-date-time-format">
<title>Global date &amp; time formatting</title>
<section xml:id="new-in-3.2-webmvc-http-patch">
<title>HTTP PATCH method</title>
<para>It is now possible to define global formats that will be used when
parsing and printing date and time types. See <xref
linkend="format-configuring-formatting-globaldatetimeformat" /> for
details.</para>
</section>
<para>The HTTP request method <code>PATCH</code> may now be used in
<interfacename>@RequestMapping</interfacename> methods as well as in
the <classname>RestTemplate</classname> in conjunction with
Apache HttpComponents HttpClient version 4.2 or later.
The JDK <classname>HttpURLConnection</classname> does not support the
<code>PATCH</code> method.</para>
<section xml:id="new-in-3.2-testing">
<title>New Testing Features</title>
</section>
<para>In addition to the aforementioned inclusion of the <link
linkend="spring-mvc-test-framework">Spring MVC Test Framework</link> in
the <literal>spring-test</literal> module, the <emphasis>Spring
TestContext Framework</emphasis> has been revised with support for
integration testing web applications as well as configuring application
contexts with context initializers. For further details, consult the
following.</para>
<section xml:id="new-in-3.2-webmvc-mapped-interceptor-exclude-patterns">
<title>Excluded patterns in mapped interceptors</title>
<itemizedlist>
<listitem>
<para>Configuring and <link
linkend="testcontext-ctx-management-web">loading a
WebApplicationContext</link> in integration tests</para>
</listitem>
<para>Mapped interceptors now support URL patterns to be excluded.
The MVC namespace and the MVC Java config both expose these options.</para>
<listitem>
<para>Testing <link linkend="testcontext-web-scoped-beans">request and
session scoped beans</link></para>
</listitem>
</section>
<listitem>
<para>Improvements to <link linkend="mock-objects-servlet">Servlet API
mocks</link></para>
</listitem>
<section xml:id="new-in-3.2-date-time-format-without-joda">
<title>Support for <interfacename>@DateTimeFormat</interfacename> without Joda Time</title>
<para>The <interfacename>@DateTimeFormat</interfacename> annotation can now be
used without needing a dependency on the Joda Time library. If Joda Time is not
present the JDK <classname>SimpleDateFormat</classname> will be used to parse and
print date patterns. When Joda time is present it will continue to be used in
preference to <classname>SimpleDateFormat</classname>.
</para>
</section>
<section xml:id="new-in-3.2-global-date-time-format">
<title>Global date &amp; time formatting</title>
<para>It is now possible to define global formats that will be used when parsing
and printing date and time types. See
<xref linkend="format-configuring-formatting-globaldatetimeformat"/> for details.
</para>
</section>
<listitem>
<para>Configuring test application contexts with <link
linkend="testcontext-ctx-management-initializers">ApplicationContextInitializers</link></para>
</listitem>
</itemizedlist>
</section>
</chapter>