users@jax-rs-spec.java.net

[jax-rs-spec users] Re: [jsr339-experts] Re: Re: Re: Re: Re: Re: Re: Improving Hypermedia Support

From: Mattias Arthursson <mattias.arthursson_at_gmail.com>
Date: Mon, 5 Dec 2011 09:11:45 +0100

CoC is excellent, but only if what is regarded as the convention is
actually applicable in the majority of cases. We initially had the same
approach as you, i.e. that the same rel will usually be applicable when
referring to one specific resource method. The more we played around with
it however, the more it turned out that this was not the case. What
initially appeared to be a convenient convention instead turned out to
*add*unnecessary work and confusion, since the default rel would
rarely be
applicable anyway.

What we *did* find very useful however, was to add convenience methods to
generate "self" links, since this is something you will very often want to
do. So we basically have two ways of generating links:

   - link(String linkableId, String rel, Object... params)
   - selfLink(String linkableId, Object... params)

Mattias

On Fri, Dec 2, 2011 at 5:02 PM, Santiago Pericas-Geertsen <
Santiago.PericasGeertsen_at_oracle.com> wrote:

> Mattias,
>
> I tend to agree with your analysis, and as you pointed out, this can also
> be concluded by studying the example. However, the point of @Rel (or
> attribute in @Linkable) is CoC. I think in the majority of cases
> (convention) it will be applicable, and in those that it isn't
> (configuration) you'd be able to update it using the builder.
>
> Would you agree with this rationale?
>
> -- Santiago
>
> On Nov 30, 2011, at 9:46 AM, Mattias Arthursson wrote:
>
> Santiago,
> I'm getting more and more doubts about the proposed @Rel annotation. From
> what I understand (this might be a misunderstanding, but it seems like a
> logical interpretation to me), the 'rel' attribute is supposed to indicate
> the link's relation to the enclosing element (e.g. this is what the Atom
> format RFC states). This means that the 'rel' attribute might very well
> (and will very often) differ in links to the same resource depending on the
> context. More specifically it means that it's not the target that knows the
> rel; the relation can only be known by the referring resource.
>
> The most obvious example of this is (from your example on the wiki) where
> a machine in the cluster list is referred to as rel='item', but when
> referring to it from the machine resource itself it has rel='self'. It's
> not hard to think of similar examples where the same resource method would
> be referred to using several different rels depending on from where in the
> application it might be referred to.
>
> Considering this I lean towards the opinion that @Rel would be explicitly
> unsuitable to use as the basis for resource link identification in a
> framework, or even to be specified in any way on the target method (e.g. as
> an attribute of @Linkable). It becomes confusing, because the specified
> relation (the value of the @Rel) is only locally relevant (i.e. in the same
> resource). In the vast majority of cases the rel will still need to be
> explicitly specified in the link anyway.
>
> We had this discussion in jax-rs-hateoas, and the conclusion that it's
> only the referring resource that knows the relation has now lead us to
> remove the rel attribute from @Linkable. Instead we now require the rel to
> be specified for each generated link.
>
> Regards,
> /Mattias
>
> On Tue, Nov 22, 2011 at 7:07 PM, Santiago Pericas-Geertsen <
> Santiago.PericasGeertsen_at_oracle.com> wrote:
>
>> Hello Experts,
>>
>> The hypermedia page has been updated based on the feedback received so
>> far. There are two new sections related to @Linkable and the use of Link
>> in models/representations towards the end of the page.
>>
>> I think it's worth pointing out that the use of link headers _does not
>> prevent_ using links in representations. We are proposing an API to create
>> instances of Link, how these are used (headers or representations) is up to
>> the application. The last section talks about Link instances in JAXB
>> models, and what we could do about that.
>>
>> -- Santiago
>>
>> On Nov 16, 2011, at 1:02 PM, Markus KARG wrote:
>>
>> Santiago,****
>> ** **
>> I actually thought I already sent your example in my proposed form. Ok,
>> give me some time, I'll post it in more elaborate form so you will see that
>> my proposal is not so far from yours, but solves the problems I outlined.
>> But you have to wait for next week for that, since I am out of office for
>> the rest of this week. Sorry.****
>> ** **
>> Regards****
>> Markus****
>> ** **
>> *From:* Santiago Pericas-Geertsen [mailto:
>> Santiago.PericasGeertsen_at_oracle.com]
>> *Sent:* Mittwoch, 16. November 2011 00:22
>> *To:* jsr339-experts_at_jax-rs-spec.java.net
>> *Subject:* [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re: Re: Re:
>> Improving Hypermedia Support****
>> ** **
>> Markus,****
>> ** **
>> Inlined ****
>> ** **
>>
>> your proposal expects the client software to know the literals "onliner"
>> and "offliner" and their actual meaning. No machine can ever understand
>> that this will take machines offline. So at least these two words and their
>> actual intention must be known to the programmer of the client.****
>>
>> ** **
>> Loose coupling does not mean no coupling. All solutions would have some
>> degree of coupling. However, a solution in which the client needs to
>> understand the structure of all the links out-of-band simply does not
>> satisfy the most basic requirement of hypermedia IMO.****
>>
>>
>> ****
>> Also, he must know definitively how to apply the "item" template. As he
>> must know that, I cannot see what is more "loosely" and more "hypermedia"
>> than just sending the list of links directly? Just do not see the
>> difference here wrt to "hypermedia" and "coupling". So I do not agree to
>> your point here. What your proposal does better than mine is supporting
>> "bad" design, as I described later. With my proposal, there is less chance
>> to do "bad" design. And I think an API should prevent "bad" design if any
>> possible.****
>> ** **
>> Unless you show me a completely fleshed out example (like the one in the
>> wiki) using "your proposal", I simply cannot comment on whether mine is bad
>> and yours is good. ****
>>
>>
>> ****
>> Please also not that my prosposal was not (a) and (b) as you cited, but
>> using the "anchor" attribute, which, BTW, I actually understand as the
>> intended solution to exactly this problem (separating target and method
>> without the need to invent another means of tempting).****
>> ** **
>> As I said above, show us a complete example using "anchors" including
>> the Client code and I (and perhaps others on this alias) will be happy to
>> evaluate it.****
>> ** **
>> -- Santiago****
>>
>>
>> ****
>> *
>> From:* Santiago Pericas-Geertsen [
>> mailto:Santiago.PericasGeertsen_at_oracle.com<Santiago.PericasGeertsen_at_oracle.com>
>> ]
>> *Sent:* Montag, 14. November 2011 16:06
>> *To:* jsr339-experts_at_jax-rs-spec.java.net
>> *Subject:* [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re: Re:
>> Improving Hypermedia Support****
>> ****
>> ****
>> On Nov 12, 2011, at 9:53 AM, Markus KARG wrote:****
>>
>>
>>
>> ****
>> But, as a machine can neither guess nor understand tooltips, it just
>> could pick one of two strategies: (a) It is explicitly written to
>> orchestrate this particular service, so it just knows the syntax of the URI
>> (I mean, if I write an eBay client I obviously know the API, which contains
>> the particular URI syntax).****
>> ****
>> This strategy seems to be against hypermedia and loose coupling.
>> Ideally, we want clients to only know a single URI and then be dynamically
>> informed of the rest (as these may change even from run to run). I'm not
>> saying that URI templates is the best solution, but it's certainly better
>> than clients needing to know the exact URI structure to follow a link.
>> Templates only assume that clients know how to identify a machine and can
>> call a method to instantiate the template.****
>> ****
>>
>> One doesn't need a template then (you only need a template, if you *do
>> not* know the syntax and want some background magic to handle this).****
>>
>> ****
>> That's precisely the point, not knowing the syntax. If I know the exact
>> syntax, then there's no point of including these links in the
>> representations as they are already known to the client.****
>> ****
>>
>> (a) Polymorhy: Maybe there are "machine" instances that need to have
>> differnent URIs! You would need to provide a different template, but how to?
>> ****
>> ****
>> (b) Binary content: Maybe the machine "name" is not (or not easily)
>> parseable from the content! How would your client software guess the
>> machine name to pass into the template?****
>>
>> ****
>> Agree, it isn't perfect. But I can't agree that the strategy you outline
>> above is better.****
>>
>>
>>
>> ****
>> But, actually, if I were you, I would provide a different model in fact
>> to solve your task: Not sending all the transition links for all the
>> machines inside of the cluster document, but let the cluster document
>> contain only the machines "self" URIs****
>> ****
>> This is certainly an option. In fact, given that what has been proposed
>> are all API calls, you could design your application this way --this is the
>> reason why I don't want to "bake" anything in annotations and framework
>> logic. ****
>> ****
>> -- Santiago****
>>
>>
>>
>> ****
>> (so you only learn the list of machines in the first step -- maybe you
>> neither want to know the state nor want to shut down a machine, so you
>> don't really lose anything in the first step). If a link is needed for a
>> machine (since you then want to know the status or want to shutdown one
>> machine), I can request the machine's representation in a second roundtrip
>> and find it's transition links inside that document. This imposes one more
>> http request, but it provides self-controlled machines, which in fact
>> solves not only the templates problem, the polymorphy problem and the
>> binary content problem, but it is also more scalable as for lots of
>> machines you would only ask for as much state as you can see on the screen
>> (not requesting machines states you won't read ever), and it is much more
>> object oriented: If I want to shut down a machine, I press it's power
>> switch. I do not press a swith on a different device. :-)****
>> ****
>> Regards****
>> Markus****
>> ****
>> *From:* Santiago Pericas-Geertsen [
>> mailto:Santiago.PericasGeertsen_at_oracle.com<Santiago.PericasGeertsen_at_oracle.com>
>> ]
>> *Sent:* Dienstag, 8. November 2011 20:09
>> *To:* jsr339-experts_at_jax-rs-spec.java.net
>> *Subject:* [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re: Re:
>> Improving Hypermedia Support****
>> ****
>> ****
>> On Nov 8, 2011, at 12:39 PM, Markus KARG wrote:****
>>
>>
>>
>>
>> ****
>> Can you please post the WIKI link again? Thanks.****
>> ****
>> Here it is: http://java.net/projects/jax-rs-spec/pages/HypermediaExample
>> ****
>> ****
>> -- Santiago****
>>
>>
>>
>>
>> ****
>> ****
>> *From:* Santiago Pericas-Geertsen [
>> mailto:Santiago.PericasGeertsen_at_oracle.com<Santiago.PericasGeertsen_at_oracle.com>
>> ]
>> *Sent:* Montag, 7. November 2011 19:11
>> *To:* jsr339-experts_at_jax-rs-spec.java.net
>> *Subject:* [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re:
>> Improving Hypermedia Support****
>> ****
>> Hi Markus,****
>> ****
>> Could you apply this to the example we have on the wiki? In particular,
>> given a collection item Y, how can I get the link to Y? I may want to start
>> machine A and stop machine B; so getting the links to all the machines in
>> the cluster is not enough.****
>> ****
>> -- Santiago****
>> ****
>> On Nov 6, 2011, at 8:45 AM, Markus KARG wrote:****
>>
>>
>>
>>
>>
>> ****
>> Santiago,****
>> ****
>> this way:****
>> ****
>> Link: <absolute-uri-A1>; rel="name-of-collection-A"****
>> Link: <absolute-uri-A2>; rel="name-of-collection-A"****
>> Link: <absolute-uri-B1>; rel="name-of-collection-B"****
>> Link: <absolute-uri-B2>; rel="name-of-collection-B"****
>> ****
>> Here you have four absolute URIs. A1 and A2 are part of collection A, B1
>> and B2 are part of collection B.****
>> ****
>> If the client wants to visit all resources references by collection B, it
>> would just have to invoke A1 and A2, identified via collection A.****
>> ****
>> An alternative way would be using the anchor attribute to identify the
>> resource as a fragment of the source resource (e. g.
>> anchor="#name-of-collection-A").****
>> ****
>> A third option would be a link-extension like "Link: <absolute-uri>;
>> collection="name-of-collection".****
>> ****
>> Where do you see a problem? No need for neither templates nor client side
>> application logic.****
>> ****
>> Regards****
>> Markus****
>> ****
>> *From:* Santiago Pericas-Geertsen [
>> mailto:Santiago.PericasGeertsen_at_oracle.com<Santiago.PericasGeertsen_at_oracle.com>
>> ]
>> *Sent:* Dienstag, 1. November 2011 20:17
>> *To:* jsr339-experts_at_jax-rs-spec.java.net
>> *Subject:* [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Improving
>> Hypermedia Support****
>> ****
>> * I do not understand the problem with the collection. Why not sending
>> just several URIs with the same relation in that case (one for each item of
>> the collection)?****
>> ****
>> As link headers? How would you know which one corresponds to which item
>> in the collection? There's no ordering for link headers. ****
>> ****
>> -- Santiago****
>>
>>
>>
>>
>>
>>
>> ****
>> ****
>> ****
>> ****
>> ****
>>
>>
>>
>
>