new-in-3.2.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xml:id="new-in-3.2">
  <title>New Features and Enhancements in Spring 3.2</title>

  <section id="new-in-3.2-features-overview">
    <title>Overview of new features</title>

    <section 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>
      
      <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>
            
      <para>See <ulink
          url="http://blog.springsource.org/2012/05/06/spring-mvc-3-2-preview-introducing-servlet-3-async-support/">
          Introducing Servlet 3 Async Support</ulink> (SpringSource team blog).</para>
    
    </section>

    <section 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><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 <ulink url="https://github.com/SpringSource/spring-framework/commit/4fd7645">
      commit message</ulink></para>

    </section>

    <section id="new-in-3.2-webmvc-controller-advice">
      <title><interfacename>@ControllerAdvice</interfacename> annotation</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>
       
    </section>

    <section id="new-in-3.2-matrix-variables">
      <title>Matrix variables</title>

      <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 id="new-in-3.2-dispatcher-servlet-initializer">
      <title>Abstract base class for code-based Servlet 3+ container initialization</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>

    <section id="new-in-3.2-webmvc-exception-handler-support">
      <title><classname>ResponseEntityExceptionHandler</classname> class</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>See the revised <xref linkend="mvc-exceptionhandlers"/>
      including information on customizing the default Servlet container error page.</para>

    </section>

    <section 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 <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>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 id="new-in-3.2-webmvc-jackson-json">
      <title>Jackson JSON 2 and related improvements</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>

    <section id="new-in-3.2-webmvc-request-body-arg-with-binding-result">
      <title><interfacename>@RequestBody</interfacename> improvements</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>

    </section>

    <section id="new-in-3.2-webmvc-http-patch">
      <title>HTTP PATCH method</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>

    <section id="new-in-3.2-webmvc-mapped-interceptor-exclude-patterns">
      <title>Excluded patterns in mapped interceptors</title>

      <para>Mapped interceptors now support URL patterns to be excluded.
      The MVC namespace and the MVC Java config both expose these options.</para>

    </section>

  </section>
</chapter>