[jax-rs-spec users] Re: Hypermedia API

From: Markus KARG <>
Date: Sun, 21 Dec 2014 19:10:17 +0100

>> About the missing metadata can you please elaborate what you think is
>> missing hence imposes a need to "guess"?
>The container has to guess how to resolve B in your example because you
>have not provided the resource class and method name that contains the
>@Path that resolves B.

Maybe I miss something, but I think it should be fairly straightforward to
implement "lookupLink" given an instance of class "B" at runtime using a
dumb brute force algorithm:

* Iterate over all resources
* For each resource iterate over all resource methods
* If resource method's return type is "B", add it to candidates list.
* After that, iterate over all candidates
* If candidate is "@GET" then return this one as the final result.
* If no candidate is "@GET" then return the first one as the final result.
* If there are no candidates, then this application has a programming error,
because the application vendor wants to link "B" but has no resource method
for it.

As JAX-RS implementations already know the absolute URI for each resource
(otherwise they couldn't route a request to a resource method), the
algorithm's last step would be to use that URI and build a link from it.

There certainly could be more sophisticated algorithms, or we could use
annotations to explicitly mark that resource method that shall be used as
final resolution, so please do not see that algorithm as the one and only. I
think it would best if the JAX-RS vendors chime in here and provide
alternative ideas which we could discuss.

>> About the necessarity of this API: Better support for hypermedia is a
>> static item on the JSR 370 charter. Hypermedia is about structural
>> links and transitional links. My proposal was announced as an example
>> how structural links could be supported in future, IF THIS IS WANTED.
>> If you ask me: Build it and they will come. My experience is that
>> people did not use it in the past, because it was not there. It was
>> there in your product, but it was not there in the standard. And many
>> people are reluctant with non-standard features.
>This is an untrue statement. Users will use proprietary vendor-specific
>JAX-RS extensions. Before JAX-RS 2.0 our interceptor model was widely
>used. Our client proxy support (added like 5 years ago) is probably our
>most popular feature even to this day. Our linking extension? Well,
>again, not many questions on it so I assume it is not popular.

Not all the users behave the same, and users do not deal the same with all
APIs or technologies: For example, we used some proprietary APIs from Jersey
but were reluctant with others. You simply cannot generalize it. The
question still is: Does _JSR 370_ want structural links or not. Until this
question is answered, I do not see a benefit in discussing deeper details of
my or any other proposals in this particular area.

>> About building links by hand: This is only possible if the application
>> vendor and the MBW author are the same.
> Not sure why that is important. So what if the vendor and MBW author are
> not the same?

It is important for component vendors. Currently JAX-RS provides a good
separation of concerns, so applications can be written by picking
third-party components (like some we provide and work with any JAX-RS
implementation and any JAX-RS application). This is a big benefit of JAX-RS
and we don't like to give it up. About the roles model I'd like to refer to
what I already explained in an earlier posting.

>> But -at least- in my case, these are
>This is my biggest concern. That this is specific to your use case.

It is not. There are three different solutions (at least): Yours, mine, and
Casey's. Possibly there are lots more which are application specific. What I
like to reach is an open discussion to get an open standard in the end. So
how could that be specific to my particular case?

>> So the question is: Do we want to support structural links, yes or no? If
>> the answer is yes and my proposal doesn't fulfil all needs, the question
>> who proposes an alternative? And if the answer is no then the question is
>> why asking me for a proposal in the end? ;-)
>You just want to add the annotation and the lookup methods but require
>nothing else. While some form of lookup methods would be a nice add to
>the spec (see above), I don't see the point in adding the annotation if
>we're not going to add a facility to automatically build (or even
>expand) links.

The annotation does no harm to you or your product, but it allows model
designers to get rid of vendor-specific and / or technology-specific
annotation and opens the way for a better separation of development roles.
Ain't that a valuable aim?

>>Looking at your MBW example again, I don't see why you need a specific
>>method for Link lookup. Can't you just use UriBuilder?

Scenario: I am a third-party MBW vendor for document schema "FOO". I do not
know who will ever use my MBW. There is some application vendor who picks my
MBW because he has to add support for schema "FOO" to his existing
application. He doesn't know how my MBW works internally (whether he uses
JAXB, JSONB, or no such API at all). How should my MBW ever be technically
able to find out the URI where "@GET" provides "B", in a pure JAX-RS
solution, without any vendor-specific APIs, and how should my MBW know where
in the model it shall replace object references by URIs? If you post a code
example for that, I will agree with you. If not, you know the answer why a
UriBuilder cannot be "just" used.