Whoops forgot the link:
http://docs.jboss.org/resteasy/docs/3.0.9.Final/userguide/html/LinkHeader.html#d4e397
On 12/17/2014 8:52 AM, Bill Burke wrote:
> Are you automatically expanding URI links into data when reading (MBR)?
> And automatically linking when writing (MBW)? BTW, this
> resolving/building of links could be done in a
> Writer/ReaderInterceptor.What I don't understand is how is the container
> supposed to resolve/build links. There's not enough metadata in your
> example and the container would have to guess which methods to use to
> expand/build the link.
>
> I think some facility to automatically create links when marshalling
> might be useful. We had a contributor build something for us, but I was
> never completely satisfied with it. [1]. Honestly though I found that
> I'd rather just build the links by hand. We've had this feature for
> years and I've rarely gotten a question on it. Also, as I've said
> before, Hypermedia/linking is pretty much ignored by app developers.
> Some of the REST talks I've been to over the years suggest that it is
> not a very popular "feature" of REST.
>
> As far as automatically expanding links? I'm really not convinced it
> would be useful and is a real edge case.
>
> This does make me think it might be interesting to include the opposite
> of a UriBuilder...a UriParser in the specification.
>
> On 12/16/2014 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
>> are.
>> *
>> * 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); //
>> link 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,
>> Annotation[] 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 only.
>>
>> I assume that Casey's solution works similar and would benefit from the
>> proposed annotation and lookupLink / lookupObject methods in the same
>> way.
>>
>> If there are questions, just ask. :-)
>>
>> Regards
>> -Markus
>>
>>
>> -----Original Message-----
>> From: Santiago Pericas-Geertsen
>> [mailto:Santiago.PericasGeertsen_at_oracle.com]
>>
>> Sent: Montag, 15. Dezember 2014 16:14
>> To: jsr370-experts_at_jax-rs-spec.java.net
>> 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 <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
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com