SPR-8803 Add UriComponentsBuilder methods to replace path/query.

spring-framework-reference/src/mvc.xml

@@ -1792,7 +1792,9 @@ public class EditPetForm {
         so no attributes should be passed on to
         <classname>RedirectView</classname>. Both the MVC namespace and the
         MVC Java config (via <interfacename>@EnableWebMvc</interfacename>)
-        automatically set this flag to <literal>true</literal>.</para>
+        keep this flag set to <literal>false</literal> in order to maintain
+        backwards compatibility. However, for new applications we recommend
+        setting it to <literal>true</literal></para>
 
         <para>The <interfacename>RedirectAttributes</interfacename> interface
         can also be used to add flash attributes. Unlike other redirect

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

@@ -467,5 +467,25 @@
       linkend="mvc-multipart-forms-non-browsers" /> and <xref
       linkend="mvc-multipart" />.</para>
     </section>
+
+    <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 
+      access to all contained URI components.
+      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> 
+      especially since <classname>UriTemplate</classname> relies on those
+      same classes internally.
+      </para>
+    </section>
+    
   </section>
 </chapter>

spring-framework-reference/src/remoting.xml

@@ -1434,6 +1434,56 @@ URI location = template.postForLocation(uri, booking, "1");
       information on using the execute method and the meaning of its other
       method arguments.</para>
 
+      <section>
+        <title>Working with the URI</title>
+
+        <para>For each of the main HTTP methods, the <classname>RestTemplate</classname>
+        provides variants that either take a String URI or <classname>java.net.URI</classname>
+        as the first argument.
+        </para>
+        
+        <para>The String URI variants accept template arguments as a
+        String variable length argument or as a <classname>Map&lt;String,String&gt;</classname>.
+        They also assume the URL String is not encoded and needs to be encoded. 
+        For example the following: 
+        </para>
+        
+        <programlisting language="java">restTemplate.getForObject("http://example.com/hotel list", String.class);</programlisting>
+        
+        <para>will perform a GET on <filename>http://example.com/hotel%20list</filename>.
+        That means if the input URL String is already encoded, it will be encoded twice -- 
+        i.e. <filename>http://example.com/hotel%20list</filename> will become 
+        <filename>http://example.com/hotel%2520list</filename>. 
+        If this is not the intended effect, use the 
+        <classname>java.net.URI</classname> method variant, which assumes
+        the URL is already encoded is also generally useful if you want
+        to reuse a single (fully expanded) <classname>URI</classname>
+        multiple times.</para>
+
+        <para>The <classname>UriComponentsBuilder</classname> class can be used
+        to build and encode the <classname>URI</classname> including support 
+        for URI templates. For example you can start with a URL String:
+        </para>
+        
+        <programlisting language="java">UriComponents uriComponents = 
+        UriComponentsBuilder.fromUriString("http://example.com/hotels/{hotel}/bookings/{booking}").build()
+            .expand("42", "21")
+            .encode();
+            
+URI uri = uriComponents.toUri();</programlisting>
+
+        <para>Or specify each URI component indiviudally:</para>
+        
+        <programlisting language="java">UriComponents uriComponents = 
+        UriComponentsBuilder.newInstance()
+            .scheme("http").host("example.com").path("/hotels/{hotel}/bookings/{booking}").build()
+            .expand("42", "21")
+            .encode();
+
+URI uri = uriComponents.toUri();</programlisting>
+        
+      </section>
+
       <section>
         <title>Dealing with request and response headers</title>