Update documentation with regards to differences between @MVC 3.0/3.1

Although the reference documentation listed the new @MVC support
classes and their benefits, it did not explicitly mention a few
use cases that are no longer supported. There is now a specific
section on the new support classes listing exactly what is not
supported.

Similary the @RequestMapping annotation never refered explicitly
to the existence of old and new support and never made it clear
exactly what the differences are.

Both have not been corrected.

SPR-9063, SPR-9042

spring-framework-reference/src/mvc.xml

@@ -857,6 +857,69 @@ public class ClinicController {
         mechanisms see <xref linkend="aop-proxying" />.</para>
       </tip>
 
+      <section id="mvc-ann-requestmapping-31-vs-30">
+        <title>New Support Classes for <classname>@RequestMapping</classname> methods in Spring MVC 3.1</title>
+
+        <para>Spring 3.1 introduced a new set of support classes for
+        <classname>@RequestMapping</classname> methods called
+        <classname>RequestMappingHandlerMapping</classname> and
+        <classname>RequestMappingHandlerAdapter</classname> respectively.
+        They are recommended for use and even required to take advantage of
+        new features in Spring MVC 3.1 and going forward. The new support
+        classes are enabled by default by the MVC namespace and MVC Java
+        config (<classname>@EnableWebMvc</classname>) but must be configured
+        explicitly if using neither. This section describes a few
+        important differences between the old and the new support classes.
+        </para>
+
+        <para>Prior to Spring 3.1, type and method-level request mappings were
+        examined in two separate stages -- a controller was selected first
+        by the <classname>DefaultAnnotationHandlerMapping</classname> and the
+        actual method to invoke was narrowed down second by
+        the <classname>AnnotationMethodHandlerAdapter</classname>.</para>
+
+        <para>With the new support classes in Spring 3.1, the
+        <classname>RequestMappingHandlerMapping</classname> is the only place
+        where a decision is made about which method should process the request.
+        Think of controller methods as a collection of unique endpoints
+        with mappings for each method derived from type and method-level
+        <classname>@RequestMapping</classname> information.</para>
+
+        <para>This enables some new possibilities. For once a
+        <classname>HandlerInterceptor</classname> or a
+        <classname>HandlerExceptionResolver</classname> can now expect the
+        Object-based handler to be a <classname>HandlerMethod</classname>,
+        which allows them to examine the exact method, its parameters and
+        associated annotations. The processing for a URL no longer needs to
+        be split across different controllers.
+        </para>
+
+        <para>There are also several things no longer possible:</para>
+        <itemizedlist>
+            <listitem><para>Select a controller first with a
+            <classname>SimpleUrlHandlerMapping</classname> or
+            <classname>BeanNameUrlHandlerMapping</classname> and then narrow
+            the method based on <classname>@RequestMapping</classname>
+            annotations.</para></listitem>
+            <listitem><para>Rely on method names as a fall-back mechanism to
+            disambiguate between two <classname>@RequestMapping</classname> methods
+            that don't have an explicit path mapping URL path but otherwise
+            match equally, e.g. by HTTP method. In the new support classes
+            <classname>@RequestMapping</classname> methods have to be mapped
+            uniquely.</para></listitem>
+            <listitem><para>Have a single default method (without an explicit
+            path mapping) with which requests are processed if no other
+            controller method matches more concretely. In the new support
+            classes if a matching method is not found a 404 error
+            is raised.</para></listitem>
+        </itemizedlist>
+
+        <para>The above features are still supported with the existing support
+        classes. However to take advantage of new Spring MVC 3.1 features
+        you'll need to use the new support classes.</para>
+
+      </section>
+
       <section id="mvc-ann-requestmapping-uri-templates">
         <title>URI Template Patterns</title>
 
@@ -1104,6 +1167,17 @@ public class RelativePathUriTemplateController {
       <classname>BindingResult</classname> arguments. This is described in the
       next section.</para>
 
+      <note><para>Spring 3.1 introduced a new set of support classes for
+      <classname>@RequestMapping</classname> methods called
+      <classname>RequestMappingHandlerMapping</classname> and
+      <classname>RequestMappingHandlerAdapter</classname> respectively.
+      They are recommended for use and even required to take advantage
+      of new features in Spring MVC 3.1 and going forward.
+      The new support classes are enabled by default from the MVC namespace and
+      with use of the MVC Java config (<code>@EnableWebMvc</code>) but must be
+      configured explicitly if using neither.
+      </para></note>
+
       <section id="mvc-ann-arguments">
         <title>Supported method argument types</title>
 

spring-framework-reference/src/new-in-3.1.xml

@@ -390,6 +390,10 @@
       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>
@@ -482,27 +486,27 @@
     <section>
       <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 
+      <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 nenw <classname>UriComponentsBuilder</classname> class is also 
+      A nenw <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> 
+
+      <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 
+      provides static factory methods to copy information from
       a Servlet request. See <xref linkend="mvc-construct-encode-uri"/>.
       </para>
-      
+
     </section>
-    
+
   </section>
 </chapter>