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

From: Markus KARG <>
Date: Wed, 17 Dec 2014 13:38:16 +0100


(1) "MyMBW" is independent of any other existing MBWs: Unfortunately I
forgot to add @Produces("application/xml+a") when I hacked that pseudo code!
Sorry for the confusion. In fact, "MyMBW" is _not_ intended for _generic_
XML or JSON. It is explicitly written for one _particular_ schema (here:
"xml+a"), as we use a lot of specialized schemas in our application but
never _generic_ XML or JSON. Hence, all generic XML is simply still
processed by the JAX-RS implementation's MBW, while _solely_ "xml+a" is
processed by "MyMBW". I think the same solution could also work with entity
interceptors as long as they get access to "lookupLink" methods, but in fact
it was developed on JAX-RS 2.1, where no interceptors existed. In fact
interceptors might be a superior approach, but we have not migrated our
solution to that already.

(2) Same as (1): Forgot @Consumes("application/xml+a"). Yes, "MyMBW",
"MyMBR" and the data model do exist on the client side, too. But this is not
mandatory, as one could decide to use JAX-RS server with non-Java client,
certainly. About JSON-LD please note that our solution is representation
independent: It currently supports "application/xml+a" but if we decide to
support JSON, we could simply provide an alternative implementation of
"MyMBW" that @Produces("application/ld+json+a"). The client can then send
"Accept: application/ld+json+a, 1.0; application/xml+0.5" to indicate type
preference, and the server would choose "MyMBW_XML" vs. "MyMBW_JSONLD"
automatically. The solution itself is the same -- the MBW knows that schema
"...+a" is used, hence can replace objects by links. :-)

Regarding your summary, you missed what my actual proposal is about: I do
_not_ propose that any JAX-RS implementation comes with "MyMBW / MyMBR"
pre-bundled or that the existing XML-MBW shall get replaced or enhanced.
What I ask for _solely_ is that JAX-RS 2.1 support application programmers
and MBW vendors by defining...
(A) ...the "@StructuralLink" annotation as a model-independent and
MBW-independent way to identify structural links,
(B) ...the methods "lookupLink" and "lookupObject" to allow MBWs / MBRs to
be able to do the replacements without knowledge of the actual application /
resource hierarchy, third party vendors of MBW / MBR (like me) and / or application
vendors can build the depicted solution _easier_.

Without (A) the model author needs to know the technology used in the entity
provider, so the model needs to be added with more annotations when more
entity providers are getting bundled. For example, when V1 of an application
supports "application/xml+a" then JAXB's @XmlAdapter is used, but when V2
shall _additionally_ support JSON-LD, then an _additional_ annotation for
JSON-B is to be added to the _model_! WITH (A) the model is untouched

Without (B) an MBW cannot be written by sole knowledge of the schema
"...+a", but in fact the MBW's author MUST know all @Path's and
@ApplicationPath's values, hence the MBW is then application-specific. WITH
(B) the MBW's author doesn't need to know anything besides the schema
"...+a", hence the MBW is application-independent and reusable!

I hope it is clear now. If not, don't hesitate to ask more questions! :-)


-----Original Message-----
From: Santiago Pericas-Geertsen []

Sent: Dienstag, 16. Dezember 2014 19:48
Subject: Re: [jax-rs-spec users] Hypermedia API


 Thanks for the example. I don't know if it helped reduced the number of
questions that I have by much ;) So here they go:

 (1) MyMBW: How does this MBW interact with the existing (or future) MBW's
for XML and JSON? I would have expected you to use an entity interceptor
instead to produce another model in which somehow references are replaced by
URIs in order to pass them to the standard MBWs. If you define a MBW
instead, I don't know how it plays ball with those for JAXB and JSON-B since
only one can be active.

 (2) MyMBR: Same comment as for (1). I think you allude to the next comment
on your e-mail, presumably this reader will know when to map URIs to objects
based on @StructuralLink, which means that the same classes need to be
available on the client side for this to work. This, in essence, is
augmenting the client-server contract; JSON-LD solves this by including
meta-data in the representation at the obvious cost of more verbosity and
performance --but frankly that is the only way.

 To summarize, I can only see this working at the framework level (modulo
the issue of extending contracts) using interceptors and mapping application
models before an existing MBW is called and after an existing MBR returns.
Likely, application models would need to be "designed" with these
transformations in mind as well (and we'd need XmlAdapters for JAXB and
something equivalent for the upcoming JSON-B).

 I may be missing something in your proposal; hopefully others can comment
as well.
-- Santiago

On Dec 16, 2014, at 12:41 PM, Markus KARG <> wrote:

> Santiago,
> I hacked a short pseudo code to illustrate what our current solution
> works
> like:
> ---snip---
> @Path("demo")
> public class StructuralLinksDemo {
> public class A {
> int a_id = 0;
> @StructuralLink B b_ref;
> A(int id, B ref) {
> this.a_id = id;
> this.b_ref = ref;
> }
> }
> public class B {
> int b_id;
> B(int id) {
> this.b_id = id;
> }
> }
> public class MyMBW implements MessageBodyWriter<A> {
> @Override
> public void writeTo(A a, Class<?> type, Type genericType,
> Annotation[] annotations,
> MediaType mediaType, MultivaluedMap<String,
> Object> httpHeaders,
> OutputStream entityStream) throws
> IOException, WebApplicationException {
> /*
> * When rendering instance of 'A' then reference
'b_ref' shall get
> replaced
> * by '.../demo/b/1' in this demo application!
> *
> * As MyMBW is provided by a third party vendor, it
can neither
> know
> * (1) what URI pattern is used in this application
/ resource for
> 'GET B',
> * (2) nor whether 'b_ref' actually is intended by
the application
> vendor to be a structural link or not,
> * which can be tricky in case multiple
> alternative MBW (e. g. JAXB vs. JSON-B) are to be used with
> * the same data model.
> * (3) nor what @ApplicationPath or resource's @Path
> *
> * Hence a JAX-RS API is needed which is neutral
w.r.t to vendor of
> MyMBW, data format, and
> * application. This API will...
> * (1, 3) allow the MBW to 'lookupLink(Object,
params);', which
> returns link of ".../demo/b/1"
> * taken from that resource method in this
> application which has '_at_GET' and returns 'B'.
> * (2) allow the MBW to identify those references in
the model
> which are to be rewritten without
> * enforcing MBW-specific annotations in the
> data model.
> */
> Link b_link = JAXRS.lookupLink(a, a.b_ref.b_id); //
> effectively is ".../demo/b/1" now!
> // 'b_link' is written to stream instead of 'b_ref',
e. g. JAXB can
> be used with custom adapter!
> }
> }
> public class MyMBR implements MessageBodyReader<A> {
> @Override
> public A readFrom(Class<A> type, Type genericType,
> annotations,
> MediaType mediaType, MultivaluedMap<String,
> String> httpHeaders,
> InputStream entityStream) throws
> IOException, WebApplicationException {
> /*
> * When parsing document 'A' then URI '.../demo/b/1"
> has to be replaced by instance of B.
> *
> * The problems for MBR are the same as for MBW.
> *
> * Hence a JAX-RS API is needed which allows...
> * (1, 3) to forward URI to JAX-RS for resolution
without a
> complete network stack loopback roundtrip
> * (2) to identify those references in the data
model which are
> URIs and shall be replaced by Java object
> */
> return new A(JAXRS.lookupObject(b_link)); // returns
instance of
> 'B' produced by implicit invocation of 'get_b(1);'
> }
> }
> @GET @Path("a/{a_id}")
> public A get_a(@PathParam("a_id") int a_id) {
> // MyMBW replaces instance of B by URI '.../demo/b/1'
> return new A(a_id, new B(1));
> }
> @PUT @Path("a/{a_id}")
> public void put_a(@PathParam("a_id") int a_id) {
> // MyMBR replaces URI '.../demo/b/1' by instance of B.
> ...
> }
> @GET @Path("b/{b_id}")
> public B get_b(@PathParam("b_id") int b_id) {
> // Client's MBR will invoke 'conditional GET' when replacing
URI by
> instance of B.
> return new B(b_id);
> }
> @PUT @Path("b/{b_id}")
> public void put_b(@PathParam("b_id") int b_id) {
> // Client's MBW will invoke 'conditional PUT' when replacing

> instance of B by URI.
> ...
> }
> }
> ---snip---
> I think the comments expain pretty well how it works. Our particular
> MyMBW / MyMBR utilizes JAXB's XmlAdapter to exchange objects with URIs
> and vice versa, and it works on both, client and server side. But as I
said before:
> It is our particular data format, so it is _not_ a generic XML
> solution, as we must know how the syntax for links is like. Anyways,
> it pretty well depicts the demand on behalf of a structural links API.
> What the API cannot do is -unfortunately- simplify client programming:
> Unless JAX-RS makes WADL discovery mandatory, the client cannot know
> the URI patterns needed. So the proposal is a first step for server side
> I assume that Casey's solution works similar and would benefit from
> the proposed annotation and lookupLink / lookupObject methods in the same
> If there are questions, just ask. :-)
> Regards
> -Markus
> -----Original Message-----
> From: Santiago Pericas-Geertsen
> []
> Sent: Montag, 15. Dezember 2014 16:14
> To:
> Subject: Re: Hypermedia API
> Markus,
> I have a lot of questions about the proposal, but I feel most can be
> answered if you translate your ideas into a sample application.
> Assuming what you're proposing is available in JAX-RS, how would your
> application look like? Could you provide a sample app?
> -- Santiago
> On Dec 15, 2014, at 7:38 AM, Markus KARG <> wrote:
>> Sergey,
>> yes and exactly at that point we'd like to give the data model
>> designer an annotation at hand which marks that field as an injection
>> point for the actual URI at runtime. That's the sole idea of the
>> proposed API. :-)
>> Regards
>> -Markus
>> -----Original Message-----
>> From: Sergey Beryozkin []
>> Sent: Montag, 15. Dezember 2014 11:25
>> To:
>> Subject: Re: Hypermedia API
>> Hi Markus
>> What I meant is that data model designers may not necessarily need
>> the help of JAX-RS in order to design the data representations that
>> can accommodate links.
>> Example, a data designer wishing for a given piece of data have a
>> link would add a field such as href, etc... May it is oversimplifying
>> Cheers, Sergey
>> On 15/12/14 09:46, Markus KARG wrote:
>>> It is not as simple as you say. You're right that for XML and other
>>> generic syntax there cannot be a generic entity provider. Hence, a
>>> generic XML entity provider will not be able to fulfil the
>>> application author's wish, obviously. But in that case, the request
>>> is invalid, as it relies on the false assumption that there can be a
>>> generic solution with pure XML. XML cannot do magic tricks, hence
>>> JAX-RS
> cannot.
>>> Certainly the proposed API makes only sense for "valid wishes", i. e.
>>> the application assembler co-bundles entity providers (one or many)
>>> which are non-generic, i. e. are written according for particular
>>> XML schemas (hence not generically
>>> @Produces("application/xml") but partcularly
>>> @Produces("application/xml+foobar") for example, where "foobar" is a
>>> link-aware schema. I understand that for JAX-RS _implementation
>>> vendors_ this looks like a rather seldom case, but from the view of
>>> a JAX-RS _application vendor_ and _extension vendor_ this is my
>>> daily work,
>> actually.
>>> You're pretty right that this API is only good for the data model
>>> designers, absolutely. But I am representing these people in this
>>> expert group. JAX-RS is not only about SPI topics (which are
>>> essential for JAX-RS implementation
>>> vendors) but to a great extend is an API for application vendors.
>>> :-)
>>> -----Original Message-----
>>> From: Sergey Beryozkin []
>>> Sent: Sonntag, 14. Dezember 2014 21:30
>>> To:
>>> Subject: Re: Hypermedia API
>>> Hi Markus
>>> On 12/12/14 18:34, Markus KARG wrote:
>>>> This is correct, hence it is impossible to have a generic solution,
>>>> but need support by Entity Providers. As Entitiy Providers are
>>>> aware of the abilitiy how to merge structural links, they -and only
>>>> they- can decide about the sole correct way to add them at time of
>>>> coding and how to resolve them at time of decoding.
>>> The above is a conflicting statement. A solution involving the
>>> entity providers can not qualify as a generic solution because the
>>> providers have no idea about the schema constraints possibly applied
>>> to a representation to be produced from a given bean.
>>> This solution can work in some cases where no schemas are involved
>>> or a consumer does not care about the validation or when schemas are
>>> designed to allow the extra content. But it is not a generic solution.
>>> To be honest I do not expect such solutions to become mainstream.
>>> It is really about people designing the data model, the one meant
>>> for the external consumption, with the links in mind,
>>> auto-augmenting the existing data can be interesting but does not
>>> appear to be something
>>> 2.1 should be spending much time on
>>> Sergey
>>>> -----Original Message-----
>>>> From: Sergey Beryozkin []
>>>> Sent: Donnerstag, 11. Dezember 2014 22:24
>>>> To:
>>>> Subject: Re: Hypermedia API
>>>> The problem with auto-augmenting XML with links is that it can
>>>> produce non valid XML, schema - invalid. A corresponding schema
>>>> instance (and for most serious applications there will be a schema)
>>>> may not be open enough for a given XML instance to include extra
>>>> attributes or elements representing the links.
>>>> Sorry if I misunderstood
>>>> Sergey
>>>> On 11/12/14 21:02, Markus KARG wrote:
>>>>> I do not see how JSON-LD is any better than XML based links, as it
>>>>> doesn't solve the root problem: In the end it plays no role
>>>>> whether the document syntax is JSON or XML. The problem is the missing
>>>>> To make structural links work, there must be standard annotations
>>>>> in the entity POJOs, and the entity providers must process them,
>>>>> and the spec must unambiguously tell how. Yes this is tough, but I
>>>>> think that shouldn't be an excuse for not standardizing it. Rather
>>>>> we should concentrate on the question whether we _want_
>>>>> standardize structural links or not, and in case we do, who
>>>>> provides the RI for that, as possibly Casey has something which
>>>>> can be built upon, and implementing it won't be cheap, and it has
>>>>> to be done by _all_ JAX-RS
>>> vendors.
>>>>> So my question to the spec leads and vendors is: Shall we really
>>>>> go on with discussing structural links, or is it simply out of
>>>>> scope of JSR 370? Frankly, I would love to have structural links
>>>>> API, but I certainly respect it if none of the vendors wants to
>>>>> pay that. In the end, a standardization should standardize
>>>>> existing products, not enforce _all_ vendors to build something
>>>>> made up synthetically from
>>> scratch.
>>>>> *From:*Santiago Pericas-Geertsen
>>>>> []
>>>>> *Sent:* Donnerstag, 11. Dezember 2014 20:47
>>>>> *To:*
>>>>> *Subject:* Re: Hypermedia API
>>>>> Casey,
>>>>> Yes, structural links in entities is not something that JAX-RS
>>>>> provides any "special" support for (in some cases, people have
>>>>> included them in headers, but it is arguably less clean).
>>>>> The reason why JAX-RS hasn't done much (other than the JAXB Link
>>>>> serialization bit) is that JAX-RS has not been, and likely never
>>>>> will be, in the business of (structured) entity serialization; it
>>>>> delegates to specific JSON and XML libraries for that. Clearly
>>>>> this is an issue for link processing, but the architectural
>>>>> decision of not duplicating existing APIs is certainly sound.
>>>>> As you point out, JAX-RS would need some additional meta-data to
>>>>> "learn" about these links in representations. However, this needs
>>>>> to be done without introducing unnecessary coupling and in a
>>>>> standard manner --that is, not in a way that would require using a
>>>>> JAX-RS implementation for it to work. This is a difficult problem
>>>>> to
> solve.
>>>>> JSON-LD [1] is a step in the right direction, especially since
>>>>> becoming a W3C recommendation. Not having full control of the
>>>>> serialization is still an issue for us, but perhaps there's
>>>>> something we can do working with the new JSON-B EG.
>>>>> -- Santiago
>>>>> [1]
>>>>> On Dec 11, 2014, at 1:43 PM, Casey Lee <
>>>>> <>> wrote:
>>>>> I agree, Markus that the issue here is the technical
>>>>> infrastructure (or lack of) around HATEOAS has limited its
>>>>> adoption and understanding. Specifically, the limitation is with
>>>>> the fact that the links we currently have with JAX-RS 2.0 are only
>>>>> transitional links in the HTTP header, but no support for
>>>>> structural links in the
>>> Entity.
>>>>> I feel the issue is that the current API is all about RESOURCES,
>>>>> which causes server side developers to focus more on the URIs than
>>>>> on the REPRESENTATIONS. Additionally, this has leaked into the
>>>>> client API, causing the client side developer to also have an
>>>>> awareness of the resources, which limits the need to think about
>>>>> links or at best makes the links optional.
>>>>> Is there an opportunity to evolve the API to enable adding (server
>>>>> side) and retrieving (client side) Links from the Entity? One
>>>>> approach would be by annotating your Entity POJOs where Links
>>>>> would be added. This would allow some declaration of the
>>>>> structural (and possibly transitional) links for the representation.
>>>>> This would cause developers (client and server side) to begin to
>>>>> think about links and the structure/relationships of the
>> representations.
>>>>> At our organization, we've developed our own sets of annotations
>>>>> for declaring the structure of your representations and
>>>>> associating them to a media type. All of our documentation and
>>>>> the API that the client uses is based on the following:
>>>>> * Follow a link
>>>>> * Get back a representation
>>>>> * Find a link in the entity
>>>>> * Repeat
>>>>> This causes us to spend most of our effort describing the media
>>>>> types, and very little if any effort describing the URIs.
>>>>> -Casey
>>>>> On Wed, Dec 10, 2014 at 1:36 PM, Markus KARG
>>>>> < <>> wrote:
>>>>> Santiago,
>>>>> you asked for statements on the field of hypermedia and reactive.
>>>>> I will take the chance to start discussion hereby on the field of
>>>>> hypermedia and provide a starter for reactive in a separate thread.
>>>>> Some weeks back I gave a lecture on JAX-RS 2.0 big picture at JUG
>>>> Stuttgart,
>>>>> just as I did infrequently at other events before. I'd like to
>>>>> describe
>>>> the
>>>>> reactions as those were stereotypical, independent of audience,
>>>>> location
>>>> and
>>>>> date. People where convinced by the very clean separation of
>>>>> concerns (application made up from pure domain objects, technical
>>>>> aspects separated from domain model), and the mostly declarative
>>>>> programming style (simply adding annotations to declare needs,
>>>>> engine solves the needs "under the hood" using a sophisticated and
>>>>> extensible technical infrastructure). But when the presentation
>>>>> came to hypermedia support, they were some kind of shocked by the
>>>>> mostly algorithmic coding style needed to make it work, voiding
>>>>> the aforementioned separation of concerns and declarative code style.
>>>>> While the existing API clearly is a foundation to achieve at least
>>>>> "something", real HATEOAS becomes a hack with the existing low
>>>>> level
>>>> support
>>>>> only. Code gets cluttered with old-style techno-punk, which is
>>>>> hard to
>>>> read
>>>>> and understand. This is due to the lack of a declarative way to
>>>>> tell the infrastructure how to make up the links from application
>>>>> domain state, and how to provide the links to an entitiy provider
>>>>> so he can merge them into the wire-level representation. Certainly
>>>>> everbody would vote for a declarative kind of solution fitting
>>>>> into the existing infrastructure. On the other hand, nobody (yes,
>>>>> really
>>>>> zero) people wanted to agree that they have a REAL NEED for
>>>>> HATEOAS (hence, neither for an explicit HATEOAS API)
>>>> as
>>>>> 100% of all attendees admitted that their recent and current
>>>>> RESTful projects are on level 1 or 2 of the REST Maturity Model
>>>>> only, and that the largest obstacle to level 3 is not a techical
>>>>> issue (hence not a missing explicit HATEOAS API) but the fact that
>>>>> HATEOS as a paradigm simply is not well understood by most of them
>>>>> and / or they do not see the actual
>>>> benefit
>>>>> of HATEOAS in the real world: It wouldn't pay off, but it would be
>>>>> cool,
>>>> to
>>>>> sum it up.
>>>>> So the question is: Is HATEOAS commonly understood well enough
>>>>> that it
>>>> makes
>>>>> actual sense to provide an explicit API for it, or does it make
>>>>> sense to make an API even when it is not? And if we define an API,
>>>>> do we all agree that it should support the separation of concerns
>>>>> and declarative style
>>>> that
>>>>> is typical for JAX-RS?
>>>>> I think without an agreement on that general topics, it wouldn't
>>>>> be a good idea to discuss any kind of details of API proposals in
>>>>> the area of
>>>>> Bill and Sergey, what's your opinion on that?
>>>>> Regards
>>>>> -Markus
>>>>> -----Original Message-----
>>>>> From: Santiago Pericas-Geertsen
>>>> []
>>>>> Sent: Mittwoch, 10. Dezember 2014 20:03
>>>>> To:
>>>>> <>
>>>>> Cc: Marek Potociar
>>>>> Subject: Welcome to the JAX-RS 2.1 EG
>>>>> Hello Experts,
>>>>> Welcome to the JAX-RS 2.1 (JSR 370) expert group!
>>>>> This is the official mailing list for the JSR. Note that the old
>>>>> mailing list for JAX-RS 2.0 (JSR 339) is still available for 2.0
>> matters.
>>>>> Before we start any discussions, I would like everyone to take a
>>>>> couple of minutes and read the JSR description one more time to
>>>>> make sure we are all on the same page ;)
>>>>> ===
>>>>> 2.1 Please describe the proposed Specification:
>>>>> Server-Sent Events (SSE) is a new technology defined as part of
>>>>> the
>>>>> HTML5 set of recommendations for a client (e.g., a browser) to
>>>>> automatically get updates from a server via HTTP. It is commonly
>>>>> employed for one-way streaming data transmissions in which a
>>>>> server updates a client
>>>> periodically
>>>>> or every time an event takes place.
>>>>> JAX-RS 2.0 introduced the notion of asynchronous processing for
>>>>> both the client and the server APIs. However, asynchronous
>>>>> processing alone cannot deliver on all the promises of a modern
>>>>> architecture without the help of non-blocking I/O. If only
>>>>> blocking I/O is available, asynchronous
>>>> processing
>>>>> simply pushes the problem from one thread to the next --this is
>>>>> akin to borrowing from a person to pay another, the problem is not
>>>>> really solved, only deferred. Thus, support for non-blocking I/O
>>>>> is necessary to achieve high throughput and efficiently manage
>>>>> resources
>>> like threads.
>>>>> In summary, the following is a list of the tasks in scope for
>>>>> JAX-RS
>> 2.1:
>>>>> * Adding support for SSE.
>>>>> * Improving integration with CDI.
>>>>> * Exploring support for non-blocking I/O in providers (filters,
>>>>> interceptors, etc.).
>>>>> * Evaluating ways in which declarative security can be supported
>>>>> either directly in this JSR or by leveraging other EE-platform JSRs.
>>>>> * Making JAXB conditional on runtimes where it is available.
>>>>> * Providing integration with JSON-B.
>>>>> * Building upon the hypermedia API added in version 2.0.
>>>>> * Investigating the reactive programming paradigm as a way to
>>>>> improve the JAX-RS asynchronous client API.
>>>>> * Evaluating any requirements necessary to support the use of
>>>>> JAX-RS resource classes as controllers in the MVC 1.0 JSR.
>>>>> ===
>>>>> Some useful links:
>>>>> [JSR]
>>>>> [JAX-RS Spec] [JIRA for 2.1]
>>>>> [RI]
>>>>> [E-mail Archives]
>>>>> As before, all of our discussions will be conducted using the
>>>>> expert's alias and (automatically) CCed to the user's alias.
>>>>> Some of the 2.1 tasks above require coordination with other
>>>>> specifications (JSON-B, Security), so these tasks will tackled
>>>>> later on
>>> in the process.
>>>>> We have tentatively selected 2 topics to start our discussions,
>>>>> both of which require some investigation, these are: hypermedia
>>>>> improvements and reactive programming. If you have any
>>>>> suggestions/comments/concerns about these two topics, feel free to
>>>>> start a discussion about them. We will be sending some more info
>>>>> as well
>>> in the upcoming weeks.
>>>>> Looking forward to working with all of you!
>>>>> --
>>>>> Santiago Pericas-Geertsen
>>>>> Marek Potociar
>>>>> JSR 370 Spec Leads