Santiago,
actually I am convinced that support for structural links indeed _are_ just
a JAX-RS issue, because there already _are_ media types supporting that, and
there _are_ solutions (like those mentioned by Casey which is provider
based, and my own JAXB based), and our charter solely is to define JAX-RS.
There are media types supporting structural links (like XML, JSON-B, PDF,
HTML, etc.) and there are types that inherently do not (like PNG, etc.).
The fact XML, JSON-B etc. do support it, does not imply that the is a
generic solution to inject the links into them, like Casey correctly said,
as for example XML could have schemas preventing this. But the fact that
there are unable types, and the fact that there are able but possibly
"currently disabled" types (like schema-bound XML) is not an excuse to not
support structural links generally. Instead, it would be a good idea for
improved hypermedia support to provide building blocks to those programmers
who are about to write an entity provider for a data type that is either
always support such links (like JSON-B, HTML and PDF), or "currently
enabled" (like XML without schema or with a schema supporting links and
known to the entity provider).
Thanks to the client-driven type negotiation ("Accept: PDF, PNG") this would
allow that a JAX-RS application containing a PDF entity provider installed
may response with a PDF containing links to other PDFs, while a JAX-RS
application having no PDF entity provider on board may response with a PNG
containing the complete content as one big foto. I am using unusual mime
types on purpose to get the discussion away from JSON-B and XML to shift
focus on entity providers which are less generic than XML and JSON-B but
know a bit more about the schema of the represented information, which XML
and JSON-B inherently cannot (schema-aware vs schema-unaware entity
providers).
What I propose is an API which enables programmers to code schema-aware
entity providers which merge structural links in the represention / resolve
links found in representations. Certainly this is possible only if the media
type and current entity instance do allow such.
That API must allow to "bind" declaratively JAX-RS resources methods (link
targets) to injection points in the domain POJOs (entity classes). An entity
provider must have an API to request the "left hand" (URI of JAX-RS resource
method) when it parses the entity instance and finds a "right hand"
(injection point) annotation. Using this simple mechanism, entity providers
can dissemble POJO nets into standalone entities representations pointing to
each other using URIs, and (lazily) synthesize that POJO net by following
the links when parsing the representation.
Anyways, I do not force anybody to support it. I just wanted to point out
that the need is there, even if not urgent, and that solutions would be
technically possible. I shop stop at this point to not make Marek complain
again about lengthy postings. ;-)
Regards
-Markus
From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Freitag, 12. Dezember 2014 17:37
To: jsr370-experts_at_jax-rs-spec.java.net
Subject: Re: [jax-rs-spec users] Hypermedia API
On Dec 11, 2014, at 4:02 PM, Markus KARG <markus_at_headcrashing.eu> 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 API. 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.
It's not a matter of better or worse, it is just that JSON-B is yet to be
defined and thus there may be an opportunity (for them) to do something,
especially given that JSON-LD is a W3C rec.
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.
I'm confused, you make it sound like this would be a JAX-RS only solution.
If this requires, say, a special media type, then it is not _just_ a JAX-RS
issue.
-- Santiago
From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Donnerstag, 11. Dezember 2014 20:47
To: jsr370-experts_at_jax-rs-spec.java.net
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] <
http://www.w3.org/TR/json-ld/>
http://www.w3.org/TR/json-ld/
On Dec 11, 2014, at 1:43 PM, Casey Lee < <mailto:cplee_at_nektos.com>
cplee_at_nektos.com> 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 <
<mailto:markus_at_headcrashing.eu> markus_at_headcrashing.eu> 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 HATEOAS.
Bill and Sergey, what's your opinion on that?
Regards
-Markus
-----Original Message-----
From: Santiago Pericas-Geertsen [
<mailto:Santiago.PericasGeertsen_at_oracle.com>
mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Mittwoch, 10. Dezember 2014 20:03
To: <mailto:jsr370-experts_at_jax-rs-spec.java.net>
jsr370-experts_at_jax-rs-spec.java.net
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] <
https://www.jcp.org/en/jsr/detail?id=370>
https://www.jcp.org/en/jsr/detail?id=370
[JAX-RS Spec] <
https://jax-rs-spec.java.net/>
https://jax-rs-spec.java.net/
[JIRA for 2.1]
<
https://java.net/jira/browse/JAX_RS_SPEC/fixforversion/16402/>
https://java.net/jira/browse/JAX_RS_SPEC/fixforversion/16402/
[RI] <
https://jersey.java.net/>
https://jersey.java.net/
[E-mail Archives] <
https://java.net/projects/jax-rs-spec/lists>
https://java.net/projects/jax-rs-spec/lists
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