jsr339-experts@jax-rs-spec.java.net

[jsr339-experts] Re: Hypermedia - Take 2

From: Markus KARG <markus_at_headcrashing.eu>
Date: Sun, 24 Jul 2011 14:28:20 +0200

> > * Structural Links:
> > If order contains items (<order><item/><item/><item/></order>, e. g.
> > class @XmlElement Order { private List<Item> items; }, then it is
> rather
> > simple to turn this into XML links by using one single annotation:
> >
> > @XmlElement Order { @Ref private List<Item> items; }
> >
> > where @Ref is nothing but providing some sugar around an Xml Java
> Type
> > Adapter replacing Item by URI and vice versa on the fly at
> marshalling /
> > unmarshalling. This is the most typical use case for structural links
> > from my experience (using this for months now and works pretty good)
> and
> > in fact this is what I expect to make most users happy in the first
> > draft. BTW, I personally would be more fluent and not name it @Ref
> but
> > @Externalize (like it is "@Inject" to have a verb what the processor
> > does) -- "externalize" since this is what the sugar will do: It
> replaces
> > the Java "internal" link by an "external" URL representation. The
> "only"
> > question is what to do with those not using JAXB? (Actually, how many
> > are not using JAXB actually?)
> >
> >
> Sorry - would really appreciate some more information at the wiki page.
> I did follow the links there and read the Declarative Hyperlinking in
> Jersey page and yes, it was interesting but I thought a bit too
> involved
> and this is what I expressed in the other email.
>
> At the moment it's more like a conversation of Jersey users - I just
> don't follow what is being discussed.
>
> Personally, I like the idea of introducing Linkable interface as well.
> I believe Jersey does try to offer a lot of flexibility - but I'm not
> sure, unless I see more or less realistic examples at the wiki, that
> all
> of that needs to be supported in 2.0. Explicit EL links to specific
> representation and/or entity methods seems brittle and a bit complex.
> Things can be changing all the time and updating the EL expressions
> seems unavoidable. Linkable interface would 'protect' @Ref/_at_Externalize
> annotations from being regularly updated
>
> Sergey

In the application we are already shipping ontop of JAX-RS 1.x we have
solved structural links as described above. It works pretty well and we
never found a need for EL, String based expressions, or anything like that.
Our implementation is just using pure JAXB to replace entity instances by
URLs and vice versa on the fly. Thus my proposal: Just adding @Externalize
at any arbitrary property should instruct a MessdageBodyReader/Write to
replace on the fly, and have some very simple kind of convention or
declarative relation between entity instances and their factory (= JAX-RS
resource method) to know the URL pattern need to resolve this (in our
application we have simply a HashMap for that but a JAX-RS implementation
certainly has better access to that information). We think that the
replacement must happen on the level of document rendering and has not to be
done on the level of model. This, the type used in an Order is List<Item>
but not List<URL>, and everthing must go "under the hood". BTW, as the web
is the prototype of REST, and the web typically is using relative URLs in a
massive way, we should really discuss the benefit of relative URLs (better
security as both parts must be in the same domain, less data to transfer and
process). Every browser comes with a resolver for that, so it should be
fairly easy for the Client API implementation to resolve relative URLs
received in responses (as it knows the base URL that the request was sent
to).

Regards
Markus