Hi Marc,
> Aside from the question of naming I'd like to explore the issue of
> what additional metadata we'd want to add to the produce/consume
> annotations. I think the three candidates are: Language, Charset and
> Content Encoding - did I miss any ?
With the current Media Type, that's it for me too.
> (i) Language
[...]
> However, I wonder how useful this would be in practice. In
> particular, I don't think it would be great application
> design if you
> had to edit the code to support an additional language for your
> content.
>
> Instead I'd expect the data to be somehow indexed by
> language so you could support additional languages just by
> adding the
> necessary data. In this case I think its more likely that a
> developer
> would want to get the language as a parameter and use it as
> some kind
> of key to find the corresponding data, e.g.:
>
> @UriTemplate("/someuri")
> public class SomeClass {
> @ProduceXXX(value="application/xml")
> @HttpMethod
> public Response get(@HeaderParam("Accept-Language") String langs) {
> String lang = getSupportedLanguage(langs);
> if (lang==null)
> return Response.Builder.notAcceptable().build();
> ...
> }
> }
>
> I think the same reasoning applies to the input side of things and
> I'm therefore not yet convinced that adding a declarative language
> capability is that useful in practice. I think the above does
> illustrate a need for a "QValuedCommaSeparatedList" type to aid in
> parsing of the Accept-XXX headers though.
Like you, I'm not sure yet about the practicality of declaring those
metadata as annotations. However, I think that we should protect the
resource code from client preferences considerations like parsing/analyzing
the Accept* headers!
This is exactly here that we can provide higher-level value to the
developer, by really doing the content negotation work for him:
- he (somehow) declares and provides the available representations of his
resources
- the container analyzes the client preferences and selects the best
representation transparently
> (ii) Charset
[...]
> Unless I'm missing something there doesn't appear to be much use in
> allowing a developer to declare support for a particular subset of
> the platform supported charsets provided the 311 runtime uses the
> platform facilities correctly when reading and writing data.
This can be important to be able to declare the character set of a byte
stream dynamically generated or read from a file.
> (iii) Content Encoding
>
> I don't really know enough about content encoding to judge
> how useful
> it would be to be able to statically declare support for one or more
> of them. Can somebody give some concrete use cases that would
> illustrate its benefits in our API ?
You want to return a representation from a zipped file directly without
unzipping it, while still allowing the client to know what's inside the
representation to auto-unzip it.
> BTW, I'm assuming that transfer
> encodings would be supported under-the-covers in a way
> transparent to
> the application and that we don't need to say anything about that in
> the specification.
Agreed.
Best regards,
Jerome