root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

395
src/reference/docbook/new-in-3.2.xml
View File

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