Re: JSR311: don't understand ResponseBuilder.variants()

From: Stephan Koops <>
Date: Mon, 17 Mar 2008 17:38:37 +0100

Hi Bill,

the usecase is:

public Response get(@Context Request request)
    List<Variant> variants = new ArrayList<Variant>();
    // VariantListBuilder could be used
    variants.add(new Variant(MediaType.parse("text/html"), "en", null));
    variants.add(new Variant(MediaType.parse("text/plain"), "en", null));
    variants.add(new Variant(MediaType.parse("text/html"), "de", null));
    variants.add(new Variant(MediaType.parse("text/plain"), "de", null));
    Variant variant = request.selectVariant(variants);
    if(variant == null)
        return Response.notAcceptable(variants).build(); // requested
variant not available.
    String entity;
        if(variant.getMediaType().equals("text/html") // pseudo code
            entity = ENGLISH_HTML;
            entity = ENGLISH_PLAIN;
        if(variant.getMediaType().equals("text/html") // pseudo code
            entity = GERMAN_HTML;
            entity = GERMAN_PLAIN;
    return Response.ok(entity).variant(variant).build();

As you said, the created Vary-Header is:
Vary: Accept, Accept-Language

You are right, that these information without an additional message body
is not very useful for the client.
But the client should add a body with further information

Does this answer your question?
>>> I don't understand why this method exists:
>>> ResponseBuilder.variants(List<Variant> variants);
>>> The Response has to choose what its Variant is doesn't it? I mean,
>>> the response MUST have a chosen content-type (for example).
>>> I thought variants were really for request processing, not the
>>> response.
>> That method is used by the implementation of Response.notAcceptable.
>> IIRC it is used to set the contents of the Vary header from the
>> supplied list.
Yes, right.
> I'm still confused on what ResponseBuilder.variants() is supposed to
> do. I looked into the Vary header and its return value. The value of
> the header should be what accept headers should be used to qualify a
> representational type.
> i.e.
> Vary: Accept, Accept-Language
> I can't find any reference to actual types, languages that are
> available in the response. From what I've read on Vary, it is really
> used for caching semantics and nothing really to do with 300 or 406
> response codes.
> For response codes 300 (Multiple Choices) and 406 ("Not acceptable"),
> W3C says that the entity body returned *may* be a link to various
> representations, but the entity body is not specified by the
> specification.
> Can we remove ResponseBuilder.variants and
> notAcceptable(List<Variant>) or define exactly what the HTTP Response
> message should look like please?
> or point me to someplace that defines what this method is supposed to do.