Clarify that @Produces/@Consumes can specify only a single MIME-TYPE

I’ve already raised that it’s not specified which of @Produces and @Consumes is used as a MIME-TYPE for request body in #109.

Both JAX-RS annotations allow multiple MIME-TYPEs in the value as an array. But on client side, one of them, which should specify the request body MIME-TYPE, should allow only one MIME-TYPE as a value and it should be specified what happens if there are multiple values.

• On the server, the incoming (consumed) MIME-TYPE is defined by request body content type and the produced MIME-TYPE can be defined by the Accept HTTP header. Therefore it makes sense to define multiple values (separated by a comma) for both @Consumes and @Produces and the container will select which MIME is used
• On the client side (in MP REST Client API), the incoming MIME-TYPE is derived from the response. But there’s no way how to specify the outgoing MIME-TYPE in the request if there are more possible MIME-TYPEs so the behavior is unspecified if multiple MIME-TYPEs are specified.

For example, Jersey’s client proxy chooses only the first MIME-TYPE specified and ignores others: https://github.com/jersey/jersey/blob/master/ext/proxy-client/src/main/java/org/glassfish/jersey/client/proxy/WebResourceFactory.java#L317

Possible solution is to specify that if multiple MIME-TYPEs are specified for request body, the first one in the list is used.

[OndroMih]

Additionally, we can allow that a method has an argument that specifies the outgoing MIME-TYPE dynamically, such as:

@Produces(MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON)
public Something postSomething(Something something, @Context MediaType requestBodyMimeType)

When called with service.postSomething(something, MediaType.APPLICATION_JSON), the request body will be mapped to JSON.

However, this is probably an edge usecase and should already be supported by passing Entity as an argument to the request method, such as postSomething(Entity.entity(something, MediaType.APPLICATION_JSON)), although we should cover it by the TCK (and probably also by the spec doc) if it isn’t already.

[derekm]

I have server & client interfaces that look like this:

/**
 * Accepts answers to questions that map to Standard Data Set attributes.
 *
 * @author Derek Moore <a href="mailto:[e-mail]">[e-mail]</a>
 */
public interface AnswersResource {

    @GET
    @Consumes({
            MediaType.APPLICATION_JSON,
            MediaType.APPLICATION_XML,
            })
    @Produces({
            MediaType.APPLICATION_JSON,
            MediaType.APPLICATION_XML,
            })
    public List<QuestionAnswer> get(@QueryParam("flowId") UUID flowId);

    /**
     * Post an answer to a Standard Data Set question.
     * @param answer an answer to a Standard Data Set question
     * @return the answer as saved
     */
    @POST
    @Consumes({
            MediaType.APPLICATION_JSON,
            MediaType.APPLICATION_XML,
            })
    @Produces({
            MediaType.APPLICATION_JSON,
            MediaType.APPLICATION_XML,
            })
    public QuestionAnswer post(QuestionAnswer answer);

    /**
     * Form post an answer to a Standard Data Set question.
     * @param flowId the flow the question is in
     * @param orgId the id for the org that the question belongs to
     * @param customerId the customer answering the question
     * @param attributeKey the attribute the question answers
     * @param value the chosen value of the attribute
     * @param values the chosen values of the attribute
     * @return the answer as saved
     */
    @POST
    @Consumes({
            MediaType.APPLICATION_FORM_URLENCODED,
            })
    @Produces({
            MediaType.APPLICATION_JSON,
            MediaType.APPLICATION_XML,
            MediaType.TEXT_HTML,
            })
    public QuestionAnswer post(@NotNull @FormParam("flowId") UUID flowId,
                               @NotNull @FormParam("orgId") UUID orgId,
                               @NotNull @FormParam("customerId") UUID customerId,
                               @NotNull @FormParam("attributeKey") String attributeKey,
                               @FormParam("value") String value,
                               @FormParam("values") List<String> values);

}

Notice how I could unify the two @POSTs iff type QuestionAnswer could be a dual-use JAXB & BeanParam object!

Jersey used to allow this, but now it rejects the type at runtime if it has both annotations.

MP Rest Client should explicitly support dual-use JAXB/JSON-{P,B} & BeanParam objects, then I could get rid of the second @POST!