Hyperlinking Support Issues

JSR 339 will provide Hypermedia support. A first proposal will be Jersey's optional / experimental HATEOAS and Hyperlinking support based on content filtering. There are two issues with that proposal and need to be solved to provide the best value to the programmer. Note that this particular RFE is not about HATEOAS (i. e. not about "Actions") but about Hperlinking (i. e. "Relations").

(1) Link injection

The Hypermedia sample is using XmlAdapters to replace JAXB references by URIs. This is not very smart, as it puts the burden on the programmer. As he has to implement the marshalling and unmarshalling for each reference, he has to implements things that a JAX-RS engine actually knows. Instead of enforcing the programmer to do that, it would be better if JAX-RS would specify a way that automates this.

There is an experimental annoation "@Ref" provided by Jersey, which does the work for the programmer, but it has shortcoming in two aspects.

(a) It is intended to work only with references of the Java types "String" and "URI", while typically JAXB object trees have references of any custom Java type but typically not "String" or "URI". Obviously linking should work with any XmlElement reference instead (or additionally), just as it is possible with XmlAdapters in the Hypermedia sample. In short: "@Ref" should do what @XmlJavaTypeAdapter does plus automatically writing the XmlAdapter.

(b) It seems "@Ref" doesn't guess the sub-resource locator on its own. It would be good if the JAX-RS specification would include an algorithm for automatic guessing of the sub-resource locator. For example, if there is only one method that has a return type of the referenced type and that method is annotated with @GET, it can be the only sub-resource locator suited for the need of "@Ref" reference-to-URI replacement and vice versay. So in that case, an algorithm is running, and that algorithm needs to be defined by the specification to prevent different results from different JAX-RS engines.

(2) Adressing fragments

In some cases it might be needed to references fragments, i. e. not entities but parts of entities. For example, there might be a sub-resource for "Order" which contains child elements of "Ordered Items". It could be the case that a different resource needs to reference not a complete order but one "Ordered Item" only (i. e. a row of the overall order containing the item's code and number of ordered items). Typically such references are implemented using URI fragments like "http://myserver/orders/12345#001" to identify within . A different example would be linking to employees being parts of an organization (not to standalone persons), or particular characteristics of items (not to general characteristics as standalone entities), etc. Just everything that couldn't live as a standalone object from a real world perspective.

When providing support for Hyperlinking in JAX-RS, it also makes sense to provide support for URI fragments. In our application for example we are using this using custom code in our product basing on Jersey 1.4 already, by the support of specialized XmlAdapters. The solution is rather simple and could be implemented ontop of (1) Link injection.
#### Affected Versions
[2.0]