________________________________
From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
To: Sastry Malladi <m_sastry_at_yahoo.com>
Cc: "jsr339-experts_at_jax-rs-spec.java.net" <jsr339-experts_at_jax-rs-spec.java.net>
Sent: Friday, December 9, 2011 6:54 AM
Subject: [jsr339-experts] Re: [jax-rs-spec users] New to the group - comments on the current draft
Hi Sastry,
* As I understand it, Handlers don't seem really generic handlers, but specifically "filters" for Entity Providers, if you will. But they are also providers. It is confusing.
>
The term "provider" is used for any type of framework extension (aspect) in JAX-RS. So you have entity providers, filter providers, etc. Filtering and entity processing are really separate aspects. Have a look at the attached diagram.
Sastry > Thanks for the diagram - I understand the difference, was commenting on the completeness as well as the naming. Please refer to my reply on the other thread.
* The scenario that is not covered is handlers for wrapping around resource method invocation - This is needed, for example, to measure the time taken by the resource method itself (monitoring/metrics).
>
You can use CDI (or EJB) interceptors for that.
Sastry > Please refer to my reply on the other thread - If I understand the CDI injections correctly, this doesn't satisfy the need. Please correct me if I'm missing something.
* Binding : The binding methods described are flexible, but in reality, only GlobalBinding is what is used in an operational environment.
I don't agree with that.
Sastry > I think it depends on the environment. Combination of GlobalBinding with specific overrides is a common pattern, I'd say.
However, specific resources may indicate that certain filters don't apply to them - For example a SecurityFilter is always globally configured in an environment and some resource may specifically say, they want to turn security off, since they are not secure resources.
Yes, I think this is a use case that isn't covered --at least not declaratively. If you want, file a JIRA to track this use case.
Sastry > I created an issue -
http://java.net/jira/browse/JAX_RS_SPEC-146
Have you considered declaring all such filters/handlers in a config file at the container level, but individual resources either add or override certain filters via a Config init parameter or such ? Usability and practicality is very important to consider here.
>
No, we haven't considered that yet. Note that running on servlet container (for example) is not a requirement in JAX-RS.
Sastry > I used the word "container" in a general sense, but the real point is the configurabilty of the filters/handlers via config file and overrides through other mechanisms -either annotations or init params or anything else.
* Binding : Why is it different on the client and server side ? Can we not use the same approach on both sides ?
Name binding is different because there's no place for the annotations on the client side. Also, as there's typically no class scanning on the client, providers need to be explicitly registered on either Client, Target or Invocation.Builder.
Hypermedia support
>This is an important topic dear to my heart and to me hypermedia support should include
>
That's good!
* Ability for the resource developers to specify which fields in their entities correspond to a resource (or sub resource), so that the container will automatically insert a link - whether for the self resource or some other resource.
We considered cases like that (see Jersey documentation for example), but it's hard to get agreement on how much poking around we want the framework to do. I think it's important to proceed gingerly here and add more behavior as we gain more experience. The current plan is to focus on a programmatic solution (i.e., give the tools to the app developer to do what he/she needs).
Sastry > I think it is ok to just give the programmatic interface (without the framework poking around the entities), however, it will be good to insert these links in the returned data, without the user having to explicitly declare the link fields in their entities. What do you think about that ?
* Ability for the resource developer to specify to optionally include any meta data for how to change the representations - For example, if you have a purchase order resource, and in order to update the purchase order one must supply certain parameters or can only update certain fields, but not the others etc. This is important in the REST world, since there is no schema for the resource interface.
>
No sure I follow this. Could you do it with custom validators?
Sastry > What I meant is that, similar to how we are talking about returning the "links" for either self or embedded resources/sub-resources, returning some "metadata" like POST templates or PUT templates, so that the caller, once he does a GET, he/she also knows how to update/create that resource, if they need to etc. The resource developer can specify this using an annotation, when desired. I think this will be very useful to the consumers.
* Ability for the resource developers to specify that the media representation be converted into HTML (so user friendly rendering can happen)
>
Via a template? That would be more MVC that hypermedia.
Sastry > Sure, it can be done via template - but more importantly, the spec needs to allow a mechanism to write a handler to get access to the stream of serialized bytes, and be able to write a HTML converted output. The more I think about, I think this can be achieved through the newly introduced Handlers.
* Now coming back to where the links should be : I think that they can both be in headers (Link header) as well as in the payload under a special reserved field called "links"
This would require the app's DTO to have the entry for the links and the framework to introspect it. As I said above, this goes beyond a simple programmatic API. Instead, I think for this version, we'll allow programmers to use Link in their DTOs and let them do that by hand, but help them with the link generation --thus, not forcing any particular type of DTO, etc.
Sastry > As I mentioned above, programmatic API is fine - The question is can we insert the links section, when the resource developers calls this programmatic API, without requiring a predefined links field. I hope I'm making sense.
-- Santiago