dev@jsr311.java.net

Determining the media type of responses

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 29 Nov 2007 14:25:50 -0500

Resource methods can return void, Response or an arbitrary type. For
void return types there's no response entity body so we'll ignore that
case. If the method is annotated with a single-valued non-wildcard
@ProduceMime then the response media type can be statically
determined. If a returned Response has the Content-Type set in the
metadata then the response return media type can be determined
dynamically. For all other cases we need an algorithm to determine the
response media type. Here's a proposal for that algorithm:

1. If the method is annotated with a multivalued @ProduceMime (e.g.
@ProduceMime({"text/plain", "text/html"})) or a wildcard ProduceMime
the runtime will intersect that with the request Accept header to
obtain an ordered list of suitable media types. The runtime will then
iterate through that list looking for a MessageBodyWriter that
supports the media type and class of the returned entity. The first
suitable MessageBodyWriter will be used, if none is found an error is
signaled via a 406 Not Acceptable.

2. If the method is not annotated with @ProduceMime then the runtime
will gather the list of MessageBodyWriter that support the class of
the returned entity, create a list of media types that can be
produced, and then intersect this with the request Accept header to
produce an ordered list of suitable types. If the list is not empty,
the runtime will pick the first type in the list to become the
response media type and use the appropriate MessageBodyWriter. If the
list is empty an error is signaled via a 406 Not Acceptable.

A final question is what to do when the list of suitable media types
in 1 or 2 above only contains wildcards, e.g. client sends Accept: */
*, the MessageBodyWriter has ProduceMime("*/*"). A couple of things we
might do:

(a) define a default media type (e.g. application/octet-stream) that
will be used in lieu of a concrete media type.
(b) require MessageBodyWriter providers to be annotated with
@ProduceMime with at least one concrete type specified and use that.
(c) make it an error condition

Either way I think we should add a strong caution to the specification
and Javadoc that MessageBodyWriter providers should only use wildcard
@ProduceMime when they *really* mean it.

Thoughts, opinions ?

Thanks,
Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.