Markus,
Inline.
> * In the times of annotation based APIs, the need to implement a method (getTransitional) to provide links more or less looks like an anachronism.
There's no need to implement that method, there is no interface, no annotation. It's just a convention of that sample as stated on the wiki. You can write that code anywhere you want.
> * There is a separation between resource and entity since the early days of JAX-RS, but the question is since, whether in REST this is natural? In fact, fromResourceMethod("self"), is showing the need to consolidate both as what it actually does *is* mapping resource methods URI paths to entity instances in the end, and it looks rather odd that one has to tell JAX-RS what the URI of the producer actually is (it would be just natural to expect that a RESTful framework knows how to produce a representation of an entity, as it actually is already able to do it... but this is a different discussion and senseless past V1.0 of a spec) Yes, your proposal is aligned to the existing JAX-RS API. But it is not looking smart. I understand that there will be no way to align resource and entity (not for the sake of flexibility, and not for the sake of backwards compatibiity), but, in my opinion it would be better to have some kind of annotation instead of that method. Like @Linkable. From that @Linkable take the value of @Path and you have the "self" URI (and, due to CoC, the root for all other transitions of "this" entity).
Introducing another annotation is certainly a possibility, if it helps.
> * It looks a bit odd that the client must build the links to the machines manually using a local UriBuilder.
Yes, this is sort of different from the status quo. The idea of using URI templates is because it's the only way to convey this information in the form of link headers when the entity is a collection (one link header, multiple items). Alternatively, we could use links in entities, but as we discussed before, that brings a bunch of other problems. I would rather have applications deal with links in entities (in which case, they may decide not to use link headers at all).
> It would be more convenient if the client would get the ready-built URIs for all machines instead (either sent by the server, or built by the client's JAX-RS implementation from the received template). I mean, in the human-readable web, people do not see IDs and fiddle them into some form, but the form already has the pre-built links when I click on "Send". So in the machine-readable web, the client application should not have a need to understand that it received a template and guess where to find the IDs to fill in. Or is that templating meant to be an additional feature?
No, it isn't and additional feature. As explained above, it's to provide link information on collections. Of course, this does not prevent the application to provide other links in the entities and follow them in the client; it is just building on the notion of using link headers to guide client bots.
-- Santiago
>
> From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
> Sent: Dienstag, 1. November 2011 18:51
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Improving Hypermedia Support
>
> Hello Expert,
>
> The following wiki page [1] contains some ideas that build on the existing hypermedia support, making it a lot more useful. Please provide feedback.
>
> The server part is based around a new method Link.fromResourceMethod(Class<?>, String). The client part simply provides some minor extensions to take advantage of the extended meta-data. The example uses relative links for convenience; if possible, let's delay the discussion on relative links for a separate e-mail thread.
>
> -- Santiago
>
> [1] http://java.net/projects/jax-rs-spec/pages/HypermediaExample