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 <markus_at_headcrashing.eu> 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 [mailto:sberyozkin_at_talend.com]
> Sent: Montag, 15. Dezember 2014 11:25
> To: jsr370-experts_at_jax-rs-spec.java.net
> 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 it...
> 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 [mailto:sberyozkin_at_talend.com]
>> Sent: Sonntag, 14. Dezember 2014 21:30
>> To: jsr370-experts_at_jax-rs-spec.java.net
>> 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 [mailto:sberyozkin_at_talend.com]
>>> Sent: Donnerstag, 11. Dezember 2014 22:24
>>> To: jsr370-experts_at_jax-rs-spec.java.net
>>> 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 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. 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
>>>> [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/
>>>>
>>>> On Dec 11, 2014, at 1:43 PM, Casey Lee <cplee_at_nektos.com
>>>> <mailto: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 <markus_at_headcrashing.eu
>>>> <mailto: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]
>>>>
>>>> Sent: Mittwoch, 10. Dezember 2014 20:03
>>>> To: jsr370-experts_at_jax-rs-spec.java.net
>>>> <mailto: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
>>>> [JAX-RS Spec] https://jax-rs-spec.java.net/ [JIRA for 2.1]
>>>> https://java.net/jira/browse/JAX_RS_SPEC/fixforversion/16402/
>>>> [RI] https://jersey.java.net/
>>>> [E-mail Archives] 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
>>>>
>>>>
>>>
>>>
>>
>>
>
>