From d16d8984a8dada0270a7ebf831a39e6b56b3688a Mon Sep 17 00:00:00 2001
From: Mark Pollack <mpollack@vmware.com>
Date: Sat, 11 Apr 2009 05:59:12 +0000
Subject: [PATCH] REST documentation

---
 spring-framework-reference/src/rest.xml | 59 ++++++++++++-------------
 1 file changed, 29 insertions(+), 30 deletions(-)

diff --git a/spring-framework-reference/src/rest.xml b/spring-framework-reference/src/rest.xml
index 6b0debad794..e3dba834263 100644
--- a/spring-framework-reference/src/rest.xml
+++ b/spring-framework-reference/src/rest.xml
@@ -2,7 +2,7 @@
 <chapter id="rest">
   <title>REST support</title>
 
-  <section>
+  <section id="rest-introduction">
     <title>Introduction</title>
 
     <para>The goal of Spring's REST support is to make the development of
@@ -32,7 +32,7 @@
     model.</para>
   </section>
 
-  <section>
+  <section id="rest-creating-services">
     <title>Creating RESTful services</title>
 
     <para>Spring's annotation-based MVC framework serves as the basis for
@@ -40,7 +40,7 @@
     container as you would for a Spring MVC application using Spring's <link
     linkend="mvc-servlet">DispatcherServlet</link>.</para>
 
-    <section>
+    <section id="rest-uritemplate">
       <title>URI templates</title>
 
       <para>RESTful services use URIs to name resourses. To faciliate
@@ -75,7 +75,7 @@ public String getUser(@PathVariable String userId) {
       <para>The request <literal>http://www.example.com/users/fred</literal>
       will bind the userId method parameter to the String value 'fred'.</para>
 
-      <section id="path-variable">
+      <section id="rest-path-variable">
         <title>Mapping RESTful URLs with the @PathVariable annotation</title>
 
         <para>The <classname>@PathVariable</classname> method level annotation
@@ -159,7 +159,7 @@ public class RelativePathUriTemplateController {
       </section>
     </section>
 
-    <section>
+    <section id="rest-multiple-representations">
       <title>Returning multiple representations</title>
 
       <para>A RESTful architecture may expose multiple representations of a
@@ -273,7 +273,7 @@ public class RelativePathUriTemplateController {
       <classname>SampleContentAtomView</classname> if the view name returned
       is 'content'. Alternatively, client requests could be made without a
       file extension and setting the Accept header to the preferred media-type
-      and the same resolution of request to views would be occur.</para>
+      and the same resolution of request to views would occur.</para>
 
       <note>
         <para>If <classname>ContentNegotiatingViewResolver</classname>'s list
@@ -306,19 +306,19 @@ public class ContentController {
       <para></para>
     </section>
 
-    <section>
+    <section id="rest-views">
       <title>Views</title>
 
       <para>blah</para>
     </section>
 
-    <section>
+    <section id="rest-method-conversion">
       <title>HTTP Method Conversion</title>
 
-      <para>Another key principle of REST is the use of the Uniform Interface.
-      This means that all resources (URLs) can be manipulated using the same
-      four HTTP method: GET, PUT, POST, and DELETE. For each of methods, the
-      HTTP specification defines exact semantics. For instance, a GET should
+      <para>A key principle of REST is the use of the Uniform Interface. This
+      means that all resources (URLs) can be manipulated using the same four
+      HTTP method: GET, PUT, POST, and DELETE. For each methods, the HTTP
+      specification defines the exact semantics. For instance, a GET should
       always be a safe operation, meaning that is has no side effects, and a
       PUT or DELETE should be idempotent, meaning that you can repeat these
       operations over and over again, but the end result should be the same.
@@ -326,15 +326,14 @@ public class ContentController {
       POST. Fortunately, there are two possible workarounds: you can either
       use JavaScript to do your PUT or DELETE, or simply do a POST with the
       'real' method as an additional parameter (modeled as a hidden input
-      field in an HTML form). This latter trick is what the
-      <classname>HiddenHttpMethodFilter</classname> does. This filter was
-      introduced in Spring 3.0 M1, and is a plain Servlet Filter. As such, it
-      can be used in combination with any web framework (not just Spring MVC).
-      Simply add this filter to your web.xml, and a POST with a hidden _method
-      parameter will be converted into the corresponding HTTP method
-      request.</para>
+      field in an HTML form). This latter trick is what Spring's
+      <classname>HiddenHttpMethodFilter</classname> does. This filter is a
+      plain Servlet Filter and therefore it can be used in combination with
+      any web framework (not just Spring MVC). Simply add this filter to your
+      web.xml, and a POST with a hidden _method parameter will be converted
+      into the corresponding HTTP method request.</para>
 
-      <section>
+      <section id="rest-form-tags">
         <title>Supporting Spring form tags</title>
 
         <para>To support HTTP method conversion the Spring MVC form tag was
@@ -358,7 +357,7 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
       </section>
     </section>
 
-    <section>
+    <section id="rest-etag">
       <title>ETag support</title>
 
       <para>An <ulink
@@ -397,30 +396,30 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
       or an AspectJ aspect.</para>
     </section>
 
-    <section>
+    <section id="rest-exception">
       <title>Exception Handling</title>
 
       <para>@ExceptionHandler</para>
     </section>
   </section>
 
-  <section>
+  <section id="rest-client-access">
     <title>Accessing RESTful services on the Client</title>
 
     <para>Spring provides a client-side API blah blah</para>
 
-    <section>
+    <section id="rest-resttemplate">
       <title>RestTemplate</title>
 
       <para>blah blah</para>
     </section>
 
-    <section>
+    <section id="rest-message-conversion">
       <title>HTTP Message Conversion</title>
 
       <para>blah blah</para>
 
-      <section>
+      <section id="rest-string-converter">
         <title>StringHttpMessageConverter</title>
 
         <para></para>
@@ -428,7 +427,7 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
         <para></para>
       </section>
 
-      <section>
+      <section id="rest-form-converter">
         <title>FormHttpMessageConverter</title>
 
         <para></para>
@@ -436,7 +435,7 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
         <para></para>
       </section>
 
-      <section>
+      <section id="rest-byte-converter">
         <title>ByteArrayMessageConverter</title>
 
         <para></para>
@@ -444,7 +443,7 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
         <para></para>
       </section>
 
-      <section>
+      <section label="rest-marhsalling-converter">
         <title>MarshallingHttpMessageConverter</title>
 
         <para></para>
@@ -452,7 +451,7 @@ public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {
         <para></para>
       </section>
 
-      <section>
+      <section id="rest-source-converter">
         <title>SourceHttpMessageConverter</title>
 
         <para></para>