Santiago,
please find my comments inlined.
From: Santiago Pericas-Geertsen
[mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Donnerstag, 7. Juli 2011 21:19
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: Hypermedia Proposals
Markus,
Thanks for the feedback. Please note that there are a few defaults that I
didn't use or talk about in the write-up in order to show all the steps.
I'm also not the original designer of this API so I don't know the
rationale of all the decisions made. See inline.
@Ref.resource -- It should be possible to omit this, and instead declare
*once* the sole resource used for resolving this reference. That means,
rather than always giving the resource here, I instead would prefer to mark
one resource as the "main resolver" for references of this type in *all*
@Refs. Reason: An apple is an apple and will not become a peach at some
particular link. So it makes no sense to enforce repeating of the apple
resolver. In our already shipping application we solved this using a
registry that maps resources on reference types, but obviously it is much
smarter to just mark a resource using an annotation as "the apple resolver".
I see your point. Let me think about this a bit more.
@Ref.style -- Typically in the web resources are virtually always
relatively addressed (ever wrote <http://> http:// into <img src>?), so
the default should be RELATIVE. Also I think it is not dependend of the
particular link but should be a global setting. That means, I want to omit
this parameter and instead tell the resource "whenever you need to resolve
@Ref, then please use RELATIVE links". This reduces a lot of clutter. If
anybody would ever want ABSOLUTE style I assume he wants it for anything
the resource does, not just for one particular link.
Default is ABSOLUTE in Jersey. Wouldn't it be simpler for Client APIs if
URI's were absolute? I'm thinking about hypermedia clients too.
Markus> The REST principle is a prototype of the web. Looking at the web,
most intra-domain links found in documents are RELATIVE. For good reason:
It clearly says that the link MUST be from the same RESOURCE but not
necessarily from the same IP ADDRESS (think of DNS-controlled load
balancing for example). Also, the documents are getting rather short (and
such faster to transfer) - think of a document consisting solely of 100
links, and each link having either twenty characters or 200. A real RESTful
client MUST be able to process relative URIs, just as any browser can do.
As long as the application programmer only deals with Link instances but
not with URI instances, there is no difference for him. And the fact that
the vendors must provide a resolver cannot be an excuse to clutter
documents with ultra-fat prefixes always reproducing the same 200
characters.
@Ref.bindings -- In our already shipping application we are not using
implicit bindings, i. e. we expect (unless otherwise specified) that the
parameter names are matching the JAXB's property names. It would reduce a
lot of clutter if we could agree upon such a fallback, so people only need
to give the bindings parameter in case of differing names.
Seems reasonable. Are you suggesting that "foo" in a URI template
"...{foo}..." be defaulted to "{instance.foo}"? Where "instance" refers to
the representation instance.
Markus> Yes, exactly this is how our current solution is working like
(using JAXB adapters and JavaBeans custom code to hide the complexity from
the author of the JAXB document / the JAX-RS resource). But see, our
solution is only working with JAXB. I wonder how it could be done using
even custom MessageBodyWriters?
Using this defaults it would be possible to enable HATEOAS with just an
unparameterized @Ref written into the JAXB document. This is how we
implemented it in our current app, and we would be not very happy to get a
more flexible but more cluttering standard… :-)
Right.
@Ref.condition -- Interesting idea, but the question is, whether there
will be any other conditions besides "is null"? If not, we can omit that,
since null will not get rendered by a JAXB marshaller anyways.
This condition can be used even if there's no reference, e.g., in a Link
header declaration. If we force developers to use URI variables, regardless
of whether these are rendered inline or as link headers, then we should
revisit this. A suitable default could be defined too.
Markus> I didn't get the point. What shall a condition be good for if there
is no reference? And what shall a Link header be good for if there is no
reference? Both, <a href> and Link: are purely means of transport for
references.
@Binding -- I would prefer not using String syntax here, too, due to the
same reasons.
You mean EL expressions? EL expressions are used in many other places in
the EE world.
Markus> Yes, but that doesn justify using a String based API in a place
where a compile time check could be made instead. Java EE introduced it
mainly for places where a compile time check is not possible, like in JSPs
(as one can create the references dynamically at runtime there). We should
not turn Java EE into a scripting environment, unless we have a good need
for it. Scripting might be nice for projects where one needs to go live
sooner than later. But our customers instead expect to get high speed and
stability. The latter is better served using compiled syntax.
@Link -- Actually this looks scary. If I want to make the JAXB marshaller
render LINK headers instead of XML URLs, it should be sufficient to
configure that in one line instead of that huge code block. Something like
a boolean parameter set at the marshaller or like that. I do not think that
it should be part of the representation class itself, but more a general
rendering configuration.
Yes, I tend to agree. You're suggestion is to always use URI (or Link ;)
variables in the representation and declare the type of rendering desired
externally. Correct?
Markus> No, I am neither using URI or Link in the representation but the
original referenced class. If we are referencing an Apple, the reference
will be using class Apple. This is just natural for Java programmers. Our
current application is using that (using JAXB adapters replacing Apple by
URI and vice versa on the fly). Currently we always replace by URL at
marshalling, but it would be rather simple for us to replace by virtually
anything (like Link). For us, there is clear separation between the data
model (JAXB class) and the transported document (rendered representation).
The data model is an Apple always. But the transferred representation is
either rendered using an "Link Header Renderer" or an "XML URI Renderer".
Again, this works pretty simple with JAXB, but it might get complex for
custom MessageBodyWriters. But, it is the most natural for Java, and so we
should try to do that.
-- Santiago
From: Santiago Pericas-Geertsen
[mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Mittwoch, 6. Juli 2011 21:09
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: Hypermedia Proposals
Hi All,
I've updated the wiki [1] to describe the type of declarative hyperlinking
supported in Jersey using @Ref and @Link. Declarative hyperlinking in
Jersey supports both links in representations and link headers.
Hyperlinking is a first step, but HATEOAS is more than that. I've also
added some links to related work towards the end of the page. Please feel
free to include other links there.
Guilherme: I came across [2]. Is this the latest on your research in this
area?
-- Santiago
[1]
http://java.net/projects/jax-rs-spec/pages/Hypermedia
[2]
https://github.com/caelum/restfulie-java/wiki/java_hypermedia
On Jul 5, 2011, at 12:47 PM, Guilherme Silveira wrote:
Cant we support link headers? Would already incentivate people doing
rest... Even if limited to links.
Cant we also incentivate response based links and forms as in
Response.getLinksFor(myEntity)
An http api withou hypermedia is, in the best case, an http api - not a
rest one.
Regards
Guilherme Silveira
2011. 7. 5. 오후 12:40에 "Bill Burke" <bburke_at_redhat.com>님이 작성:
Hypermedia is entity body driven, so, other than Link header support, I
don't see what we can be done in regards to a specification. XML/JAXB is
the only standardized media type JCP has dealt with and I'm very doubtful
meaningful integration can be done with it considering JAXB's limitations.
On 7/1/11 1:47 PM, Santiago Pericas-Geertsen wrote:
>
> Hello Experts,
>
> Even though we are stil...
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com <http://bill.burkecentral.com/>