From a93f68e22732d95f1b6011b8581fddf3684658d2 Mon Sep 17 00:00:00 2001
From: Greg Turnquist <gturnquist@pivotal.io>
Date: Wed, 23 Sep 2015 16:49:54 -0500
Subject: [PATCH] DATAREST-684 - Added details on how to return a HAL document
 in reference documentation.

Original pull request: #199.
---
 .../overriding-sdr-response-handlers.adoc         | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/main/asciidoc/overriding-sdr-response-handlers.adoc b/src/main/asciidoc/overriding-sdr-response-handlers.adoc
index daf92cae2..3b79364f8 100644
--- a/src/main/asciidoc/overriding-sdr-response-handlers.adoc
+++ b/src/main/asciidoc/overriding-sdr-response-handlers.adoc
@@ -16,14 +16,20 @@ public class ScannerController {
     }
 
     @RequestMapping(method = GET, value = "/scanners/search/listProducers") // <2>
-    public @ResponseBody List<String> getProducers() {
+    public @ResponseBody ResponseEntity<?> getProducers() {
         List<String> producers = repository.listProducers(); // <3>
 
         //
         // do some intermediate processing, logging, etc. with the producers
         //
 
-        return producers; // or some filtered/altered/mapped version
+        Resources<String> resources = new Resources<String>(producers); // <4>
+
+        resources.add(linkTo(methodOn(ScannerController.class).getProducers()).withSelfRel()); // <5>
+
+        // add other links as needed
+
+        return ResponseEntity.ok(resources); // <6>
     }
 
 }
@@ -34,6 +40,11 @@ This controller will be served from the same API base path defined in `Repositor
 <1> This example uses constructor injection.
 <2> This handler plugs in a custom handler for a Spring Data finder method.
 <3> This handler is using the underlying repository to fetch data, but will tehn do some form of post processing before returning the final data set to the client.
+<4> The results need to be wrapped up in a Spring HATEOAS `Resources` object to return a collection, but only a `Resource` for a single item.
+<5> Add a link back to this exact method as a "self" link.
+<6> Returning the collection using Spring MVC's `ResponseEntity` wrapper ensure the collection is properly wrapped and rendered in the proper accept type.
+
+`Resources` is for a collection while `Resource` is for a single item. These types can be combined. If you know the links for each item in a collection, use `Resources<Resource<String>>` (or whatever the core domain type is). This lets you assembled links for each item as well as for the whole collection.
 
 IMPORTANT: In this example, the combined path will be `RepositoryRestConfiguration.getBasePath()` + `/scanners/search/listProducers`.