From 25f68fa208240db87b7a644011f5b592c0e8e6b5 Mon Sep 17 00:00:00 2001
From: Oliver Gierke <info@olivergierke.de>
Date: Wed, 19 Dec 2012 14:38:56 +0100
Subject: [PATCH] Polished EntityLinks documentation (previously non-existent).

---
 readme.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/readme.md b/readme.md
index 539f6838..7e3b6875 100644
--- a/readme.md
+++ b/readme.md
@@ -146,7 +146,55 @@ assertThat(link.getHref(), is("/people/2")));
 1. The return type has to be capable of proxying as we need to expose the method invocation on it.
 2. The parameters handed into the methods are generally neglected, except the ones referred to through `@PathVariable` as they make up the URI.
 
+## EntityLinks
+
+So far we have created links by pointing to the web-framework implementations (i.e. Spring MVC controllers or JAX-RS resource classes) and inspected the mapping. In many cases these classes essentially read and write representations backed by a model class.
+
+The `EntityLinks` interfaces now exposes API to lookup `Link`s or `LinkBuilder`s based on the model types. The methods essentially return links to either point to the collection resource (e.g. `/people`) or a single resource (e.g. `/people/1`).
+
+```
+EntityLinks links = …;
+LinkBuilder builder = links.linkFor(CustomerResource.class);
+Link link = links.linkToSingleResource(CustomerResource.class, 1L);
+```
+
+`EntityLinks` is available for dependency injection by activating `@EnableEntityLinks` in your Spring MVC configuration. Activating this functionality will cause all your Spring MVC controllers and JAX-RS resource implementations available in the current `ApplicationContext` being inspected for the `@ExposesResourceFor(…)` annotation. The annotation exposes which model type the controller manages. Beyond that we assume you follow the URI mapping convention of a class level base mapping and assuming you have controller methods handling an appended `/{id}`. Here's an example implementation of an `EntityLinks` capable controller:
+
+```java
+@Controller
+@ExposesResourceFor(Order.class)
+@RequestMapping("/orders")
+class OrderController {
+
+  @RequestMapping
+  ResponseEntity orders(…) { … }
+
+  @RequestMapping("/{id}")
+  ResponseEntity order(@PathVariable("id") … ) { … }
+}
+```
+
+The controller exposes that it manages `Order` instances and exposes handler methods that are mapped to our convention. Enabling `EntityLinks` through `@EnableEntityLinks` in your Spring MVC configuration you can now go ahead and create links to the just shown controller as follows.
+
+```java
+@Controller
+class PaymentController {
+
+  @Autowired EntityLinks entityLinks;
+
+  @RequestMapping(…, method = HttpMethod.PUT)
+  ResponseEntity payment(@PathVariable Long orderId) {
+
+	Link link = entityLinks.linkToSingleResource(Order.class, orderId);
+    …
+  }
+}
+```
+
+As you can see you can refer to the link `Order` instances are handled at without even referring to the `OrderController`.
+
 ## Resource assembler
+
 As the mapping from an entity to a resource type will have to be used in multiple places it makes sense to create a dedicated class responsible for doing so. The conversion will of course contain very custom steps but also a few boilerplate ones:
 
 1. Instantiation of the resource class