<?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.1">
  <title>New Features and Enhancements in Spring 3.1</title>

  <para>Building on the support introduced in Spring 3.0, Spring 3.1 is
  currently under development, and at the time of this writing Spring 3.1 RC1
  is being prepared for release.</para>

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

    <para>This is a list of new features for Spring 3.1. Most features do not
    yet have dedicated reference documentation but do have Javadoc. In such
    cases, fully-qualified class names are given.</para>

    <section id="new-in-3.1-cache-abstraction">
      <title>Cache Abstraction</title>

      <itemizedlist>
        <listitem>
          <para><xref linkend="cache" /></para>
        </listitem>

        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/02/23/spring-3-1-m1-caching/">
          Cache Abstraction</ulink> (SpringSource team blog)</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-bean-definition-profiles">
      <title>Bean Definition Profiles</title>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/02/11/spring-framework-3-1-m1-released/">
          XML profiles</ulink> (SpringSource Team Blog)</para>
        </listitem>

        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/02/14/spring-3-1-m1-introducing-profile/">
          Introducing @Profile</ulink> (SpringSource Team Blog)</para>
        </listitem>

        <listitem>
          <para>See org.springframework.context.annotation.Configuration
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.context.annotation.Profile
          Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-environment-abstraction">
      <title>Environment Abstraction</title>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/02/11/spring-framework-3-1-m1-released/">
          Environment Abstraction</ulink> (SpringSource Team Blog)</para>
        </listitem>

        <listitem>
          <para>See org.springframework.core.env.Environment Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-property-source-abstraction">
      <title>PropertySource Abstraction</title>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/02/15/spring-3-1-m1-unified-property-management/">
          Unified Property Management</ulink> (SpringSource Team Blog)</para>
        </listitem>

        <listitem>
          <para>See org.springframework.core.env.Environment Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.core.env.PropertySource Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.context.annotation.PropertySource
          Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-code-equivalent-xml-namespaces">
      <title>Code equivalents for Spring's XML namespaces</title>

      <para>Code-based equivalents to popular Spring XML namespace elements
      &lt;context:component-scan/&gt;, &lt;tx:annotation-driven/&gt;
      and &lt;mvc:annotation-driven&gt; have been developed, most in the
      form of <interfacename>@Enable</interfacename> annotations. These are
      designed for use in conjunction with Spring's
      <interfacename>@Configuration</interfacename> classes, which were
      introduced in Spring 3.0.</para>

      <itemizedlist>
        <listitem>
          <para>See org.springframework.context.annotation.Configuration
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.context.annotation.ComponentScan
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.transaction.annotation.EnableTransactionManagement
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.cache.annotation.EnableCaching Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.web.servlet.config.annotation.EnableWebMvc
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.scheduling.annotation.EnableScheduling
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See org.springframework.scheduling.annotation.EnableAsync
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.context.annotation.EnableAspectJAutoProxy
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.context.annotation.EnableLoadTimeWeaving
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.beans.factory.aspectj.EnableSpringConfigured
          Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-hibernate-4-support">
      <title>Support for Hibernate 4.x</title>

      <itemizedlist>
        <listitem>
          <para>See Javadoc for classes within the new
          org.springframework.orm.hibernate4 package</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-test-context-profiles">
      <title>TestContext framework support for @Configuration classes and bean
      definition profiles</title>

      <para>The <interfacename>@ContextConfiguration</interfacename>
      annotation now supports supplying
      <interfacename>@Configuration</interfacename> classes for configuring
      the Spring <classname>TestContext</classname>. In addition, a new
      <interfacename>@ActiveProfiles</interfacename> annotation has been
      introduced to support declarative configuration of active bean
      definition profiles in <interfacename>ApplicationContext</interfacename>
      integration tests.</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://blog.springsource.com/2011/06/21/spring-3-1-m2-testing-with-configuration-classes-and-profiles/">Spring
          3.1 M2: Testing with @Configuration Classes and Profiles</ulink>
          (SpringSource Team Blog)</para>
        </listitem>

        <listitem>
          <para>See <xref linkend="testcontext-framework" /></para>
        </listitem>

        <listitem>
          <para>See <xref linkend="testcontext-ctx-management-javaconfig" />
          and
          <interfacename>org.springframework.test.context.ContextConfiguration</interfacename>
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          <interfacename>org.springframework.test.context.ActiveProfiles</interfacename>
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          <interfacename>org.springframework.test.context.SmartContextLoader</interfacename>
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          <interfacename>org.springframework.test.context.support.DelegatingSmartContextLoader</interfacename>
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          <interfacename>org.springframework.test.context.support.AnnotationConfigContextLoader</interfacename>
          Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-c-namespace">
      <title>c: namespace for more concise constructor injection</title>

      <itemizedlist>
        <listitem>
          <para><xref linkend="beans-c-namespace" /></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-injection-non-javabeans-setters">
      <title>Support for injection against non-standard JavaBeans
      setters</title>

      <para>Prior to Spring 3.1, in order to inject against a property method
      it had to conform strictly to JavaBeans property signature rules, namely
      that any 'setter' method must be void-returning. It is now possible in
      Spring XML to specify setter methods that return any object type. This
      is useful when considering designing APIs for method-chaining, where
      setter methods return a reference to 'this'.</para>
    </section>

    <section id="new-in-3.1-servlet-3-code-config">
      <title>Support for Servlet 3 code-based configuration of Servlet
      Container</title>

      <para>The new <interfacename>WebApplicationInitializer</interfacename>
      builds atop Servlet 3.0's
      <interfacename>ServletContainerInitializer</interfacename> support to
      provide a programmatic alternative to the traditional web.xml.</para>

      <itemizedlist>
        <listitem>
          <para>See org.springframework.web.WebApplicationInitializer
          Javadoc</para>
        </listitem>

        <listitem>
          <para><ulink url="http://bit.ly/lrDHja">Diff from Spring's
          Greenhouse reference application</ulink> demonstrating migration
          from web.xml to
          <interfacename>WebApplicationInitializer</interfacename></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-servlet-3-multipart-resolver">
      <title>Support for Servlet 3 MultipartResolver</title>

      <itemizedlist>
        <listitem>
          <para>See
          org.springframework.web.multipart.support.StandardServletMultipartResolver
          Javadoc</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="new-in-3.1-jpa-without-xml">
      <title>JPA EntityManagerFactory bootstrapping without
      persistence.xml</title>

      <para>In standard JPA, persistence units get defined through
      <literal>META-INF/persistence.xml</literal> files in specific jar files
      which will in turn get searched for <literal>@Entity</literal> classes.
      In many cases, persistence.xml does not contain more than a unit name
      and relies on defaults and/or external setup for all other concerns
      (such as the DataSource to use, etc). For that reason, Spring 3.1
      provides an alternative:
      <classname>LocalContainerEntityManagerFactoryBean</classname> accepts a
      'packagesToScan' property, specifying base packages to scan for
      <literal>@Entity</literal> classes. This is analogous to
      <classname>AnnotationSessionFactoryBean</classname>'s property of the
      same name for native Hibernate setup, and also to Spring's
      component-scan feature for regular Spring beans. Effectively, this
      allows for XML-free JPA setup at the mere expense of specifying a base
      package for entity scanning: a particularly fine match for Spring
      applications which rely on component scanning for Spring beans as well,
      possibly even bootstrapped using a code-based Servlet 3.0
      initializer.</para>
    </section>

    <section id="new-in-3.1-handler-method-controller-processing">
      <title>New HandlerMethod-based Support Classes For Annotated Controller
      Processing</title>

      <para>Spring 3.1 introduces a new set of support classes for processing
      requests with annotated controllers:</para>

      <itemizedlist>
        <listitem>
          <para><classname>RequestMappingHandlerMapping</classname></para>
        </listitem>

        <listitem>
          <para><classname>RequestMappingHandlerAdapter</classname></para>
        </listitem>

        <listitem>
          <para><classname>ExceptionHandlerExceptionResolver</classname></para>
        </listitem>
      </itemizedlist>

      <para>These classes are a replacement for the existing:</para>

      <itemizedlist>
        <listitem>
          <para><classname>DefaultAnnotationHandlerMapping</classname></para>
        </listitem>

        <listitem>
          <para><classname>AnnotationMethodHandlerAdapter</classname></para>
        </listitem>

        <listitem>
          <para><classname>AnnotationMethodHandlerExceptionResolver</classname></para>
        </listitem>
      </itemizedlist>

      <para>The new classes were developed in response to many requests to
      make annotation controller support classes more customizable and open
      for extension. Whereas previously you could configure a custom annotated
      controller method argument resolver, with the new support classes you
      can customize the processing for any supported method argument or return
      value type.</para>

      <itemizedlist>
        <listitem>
          <para>See
          org.springframework.web.method.support.HandlerMethodArgumentResolver
          Javadoc</para>
        </listitem>

        <listitem>
          <para>See
          org.springframework.web.method.support.HandlerMethodReturnValueHandler
          Javadoc</para>
        </listitem>
      </itemizedlist>

      <para>A second notable difference is the introduction of a
      <classname>HandlerMethod</classname> abstraction to represent an
      <interface>@RequestMapping</interface> method. This abstraction is used
      throughout by the new support classes as the <literal>handler</literal>
      instance. For example a <classname>HandlerInterceptor</classname> can
      cast the <literal>handler</literal> from <classname>Object</classname>
      to <classname>HandlerMethod</classname> and get access to the target
      controller method, its annotations, etc.</para>

      <para>The new classes are enabled by default by the MVC namespace and by
      Java-based configuration via <interface>@EnableWebMvc</interface>. The
      existing classes will continue to be available but use of the new
      classes is recommended going forward.</para>

      <para>See <xref linkend="mvc-ann-requestmapping-31-vs-30"/> for additional
      details and a list of features not available with the new support classes.</para>

    </section>

    <section id="new-in-3.1-request-mapping-consumes-produces">
      <title>"consumes" and "produces" conditions in
      <interface>@RequestMapping</interface></title>

      <para>Improved support for specifying media types consumed by a method
      through the <literal>'Content-Type'</literal> header as well as for
      producible types specified through the <literal>'Accept'</literal>
      header. See <xref linkend="mvc-ann-requestmapping-consumes" /> and <xref
      linkend="mvc-ann-requestmapping-produces" /></para>
    </section>

    <section id="new-in-3.1-flash-redirect-attributes">
      <title>Flash Attributes and
      <interfacename>RedirectAttributes</interfacename></title>

      <para>Flash attributes can now be stored in a
      <classname>FlashMap</classname> and saved in the HTTP session to survive
      a redirect. For an overview of the general support for flash attributes
      in Spring MVC see <xref linkend="mvc-flash-attributes" />.</para>

      <para>In annotated controllers, an
      <interfacename>@RequestMapping</interfacename> method can add flash
      attributes by declaring a method argument of type
      <interfacename>RedirectAttributes</interfacename>. This method argument
      can now also be used to get precise control over the attributes used in
      a redirect scenario. See <xref linkend="mvc-ann-redirect-attributes" />
      for more details.</para>
    </section>

    <section id="new-in-3.1-uri-template-var-enhancements">
      <title>URI Template Variable Enhancements</title>

      <para>URI template variables from the current request are used in more
      places: <itemizedlist>
          <listitem>
            <para>URI template variables are used in addition to request
            parameters when binding a request to
            <interfacename>@ModelAttribute</interfacename> method
            arguments.</para>
          </listitem>

          <listitem>
            <para>@PathVariable method argument values are merged into the
            model before rendering, except in views that generate content in
            an automated fashion such as JSON serialization or XML
            marshalling.</para>
          </listitem>

          <listitem>
            <para>A redirect string can contain placeholders for URI variables
            (e.g. <literal>"redirect:/blog/{year}/{month}"</literal>). When
            expanding the placeholders, URI template variables from the
            current request are automatically considered.</para>
          </listitem>

          <listitem>
            <para>An <interfacename>@ModelAttribute</interfacename> method
            argument can be instantiated from a URI template variable provided
            there is a registered Converter or PropertyEditor to convert from
            a String to the target object type.</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section id="new-in-3.1-mvc-valid-requestbody">
      <title><interfacename>@Valid</interfacename> On
      <interface>@RequestBody</interface> Controller Method Arguments</title>

      <para>An <interface>@RequestBody</interface> method argument can be
      annotated with <interface>@Valid</interface> to invoke automatic
      validation similar to the support for
      <interface>@ModelAttribute</interface> method arguments. A resulting
      <classname>MethodArgumentNotValidException</classname> is handled in the
      <classname>DefaultHandlerExceptionResolver</classname> and results in a
      <literal>400</literal> response code.</para>
    </section>

    <section id="new-in-3.1-mvc-requestpart">
      <title><interfacename>@RequestPart</interfacename> Annotation On
      Controller Method Arguments</title>

      <para>This new annotation provides access to the content of a
      "multipart/form-data" request part. See <xref
      linkend="mvc-multipart-forms-non-browsers" /> and <xref
      linkend="mvc-multipart" />.</para>
    </section>

    <section id="new-in-3.1-mvc-uricomponentsbuilder">
      <title><classname>UriComponentsBuilder</classname> and <classname>UriComponents</classname></title>

      <para>A new <classname>UriComponents</classname> class has been added,
      which is an immutable container of URI components providing
      access to all contained URI components.
      A new <classname>UriComponentsBuilder</classname> class is also
      provided to help create <classname>UriComponents</classname> instances.
      Together the two classes give fine-grained control over all
      aspects of preparing a URI including construction, expansion
      from URI template variables, and encoding.</para>

      <para>In most cases the new classes can be used as a more flexible
      alternative to the existing <classname>UriTemplate</classname>
      especially since <classname>UriTemplate</classname> relies on those
      same classes internally.
      </para>

      <para>A <classname>ServletUriComponentsBuilder</classname> sub-class
      provides static factory methods to copy information from
      a Servlet request. See <xref linkend="mvc-construct-encode-uri"/>.
      </para>

    </section>

  </section>
</chapter>
