Re: JSR311: Issue 1 - Proposal for new conneg APIs

From: Ryan McDonough <>
Date: Thu, 11 Oct 2007 20:43:01 -0400


The example you've provided seems a bit isolated and I'm having a bit of
difficulty understanding how it would work in practice. Assuming the
following code:

class PersonResource {

   public Person getPersonAsXmlEn(@UriParam("id) String id) {...}

   public Person getPersonAsXmlFr(@UriParam("id) String id) {...}

   public Person getPersonAsJsonEn(@UriParam("id) String id) {...}

   public Person getPersonAsJsonFr(@UriParam("id) String id) {...}

Here, we could possibly get a representation in either XML or JSON and in
either English or French. The methods are not annotated for the purpose of
seeing how the RequestHelper would execute the proper method.

On additional item: we should be able to specify the Q value of the media
type and also also sort the the media types by this value. If the client is
sending an accept header with a q value, we should be including that in the
selection process.


On 10/11/07, Marc Hadley <> wrote:
> Issue 1[1] asks about additional support for content negotiation.
> I've uploaded a sketch of some new APIs to aid with content
> negotiation beyond the media type support we currently have:
> RepresentationVariant represents an available combination of media
> type, language, charset and encoding. Its ListBuilder static inner
> class is a builder that makes creation of a list of variants
> straightforward.
> RequestHelper would replace the existing PreconditionEvaluator and
> adds support for conneg to the existing precondition methods. I also
> added a notAcceptable method to Response.Builder and an extra
> representation method to directly support RepresentationVariant.
> The idea is that you use RepresentationVariant.ListBuilder to create
> a list of variants that describe all of the possible representations
> that can be produced. You then use RequestHelper.narrowChoices to
> select a variant that matches the preferences in the request. Once
> you've narrowed the choices you can then proceed to evaluate
> preconditions for the chosen variant.
> Here's an example of how it could be used.
> @HttpContext RequestHelper req;
> @HttpMethod
> public Response getFoo() {
> RepresentationVariant.ListBuilder b =
> RepresentationVariant.ListBuilder.newInstance();
> b.mediaTypes("application.xml", "application.json");
> b.languages("en", "fr");
> List<RepresentationVariant> variants = b.add().build();
> // check we have a representation that is acceptable
> RepresentationVariant v = req.narrowChoices(variants);
> if (r==null)
> return Response.Builder.notAcceptable(variants);
> // check preconditions
> Response r = req.evaluatePreconditions(getTag(v), v);
> if (r!=null)
> return r;
> // have a representation and preconditions were met
> return Response.Builder.representation(getEntity(v), v);
> }
> I can see the above pattern being repeated over and over and I'm
> wondering if there's some way we can automate it to make it more
> convenient - perhaps via a callback interface or something. Either
> way I suspect we need the lower level approach above for maximum
> flexibility.
> BTW, RepresentationVariant is somewhat similar to the Variant class
> in the RESTlet API. The main difference is that a variant in RESTlet
> includes all the representation metadata whereas
> RepresentationVariant only includes metadata used for conneg.
> Let me know what you think.
> Marc.
> [1]
> [2]
> ---
> Marc Hadley <marc.hadley at>
> CTO Office, Sun Microsystems.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

Ryan J. McDonough