Marc,
> The same applies to use of Entity<T>, Representation<T> and
> Response.
> You only use them when you need them, the rest of the time you can
> work with POJOs. However when you do need them they bring together
> everything in one place and IMO are much more convenient and
> intuitive than sprinkling a set of annotated properties representing
> aspects of the request and response through the method signature and
> class.
I understand your motivation. Still, the problem I have with Response (and
Representation to a lesser extent) is that it makes the user focus shift
from POJO resources to lower-level request/response flows.
If you give him access to a Response object, why not also give access to a
Request object and then why not let him directly handle the Request/Response
call? Then you have defined another Servlet-like API that follows two
opposite goals: exposing higher-level domain objects as Web resources AND
providing a complete, flexible and optimized request/response handling API
(similar to the Servlet API or Restlet API but not as complete and useful).
I strongly disagree to go down this road as this will lead to confusion and
suboptimal design. I have the feeling that you do want to cover 100% of the
HTTP use cases with this JSR instead of truly attempting to make the 80%
simpler cases truly easy to implement while keeping the JSR small, focused
and easy to learn.
As soon as I try to propose a simplification for the benefit of reducing the
API conceptual weight you object because it isn't flexible enough and can't
handle the rare cases where you don't have control on the source code and
want to do advanced things (like tweaking the HTTP headers, fine tuning the
cache control, etc.). I still don't see the point of asking this JSR to
handle cases where you can't annotate a resource POJO class because you
don't control the source code. For the representation classes this is less
an issue as we talked about (the wrapper thing).
If we really want to handle 100% of the cases, then we are guaranteed to
produce a mix of lower-level API and higher-level API that will
significantly overlap existing APIs, produce confusion and comprise its
adoption.
> Understood, Paul and I have been working on the API for many months
> now and have already explored some of the paths being suggested. It
> takes a while to work through the implications of each design choice.
I fully value your experience and contribution to this EG process. I also
think that it would make our collaboration easier to not impose your initial
API as the de facto basis of our work, where we can only add/remove a couple
of features, at the margin. I'm pushing a bit strong here as you are
obviously open for discussion, but I sometimes feel that this initial API is
more a burden than a facilitator.
Why not say: here we have our initial proposition. Feel free to propose
alternative ones (like I will try to do). It is the fruit of our hard work
and significant experience with these ideas. Let's start with a blank page
and attempt define the EG's API based on our discussions and on the
consensus. While the discussion moves forward we can enrich it as required.
> BTW, in the above suggestion, how would the post method set
> the value
> of {var} ?
As we need an annotation to inject context info into POJO, we also need a
mechanism to let POJOs update some context info. I am open about having an
optional Context class that would serve as a gateway between the annotated
POJOs and their environment. I would limit this gateway to this sole class
with no Request or Response classes, even though useful information could be
available (like the IP address of the client). This could be a good
abstraction of the lower-level HTTP request/response cycle into a
higher-level concept.
> > Agreed. @Resource("someUriTemplate") would be even simpler, with
> > the option
> > to specify @Resource(id="someUriTemplate", otherParam="xxx") if
> > necessary.
> >
> Except, syntactically, if you have "otherParam" you *always* have to
> write @Resource(id="someuri"), you can't use the shortcut @Resource
> ("someUriTemplate") even if otherParam has a default value.
> Its not a big deal but worth bearing in mind.
Thanks for pointing that out, I missed this annotation subtilety.
Best regards,
Jerome