Re: Issue 1: Adding additional conneg metadata to _at_Produce/ConsumeXXX

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Mon, 21 May 2007 11:18:19 -0400

I've added an issue so we don't forget about this:

I think we should only define constants for annotation properties or
API method arguments so I'd prefer to defer discussion of the exact
set of constants until we are closer to final API design - otherwise
we'd risk defining constants for things we don't directly cover in
the API.


On May 18, 2007, at 2:52 PM, Larry Cable wrote:

> On a slightly related matter, I would encourage us to codify a set
> of useful constant values such as "fr" or
> "application/xml" as constants, it's a minor and (very) subjective
> matter of style but the fewer
> "freehand" strings a developer has to type the fewer (stupid) typo
> errors occur ... just an idea
> i.e
> @ProduceXXX(value=APPLICATION_XML, language=EN)
> these constants could use static inclusion to improve readability
> :)
> - Larry
> ________________________________
> From: Marc Hadley [mailto:Marc.Hadley_at_Sun.COM]
> Sent: Fri 5/18/2007 11:47 AM
> To:
> Subject: Issue 1: Adding additional conneg metadata to @Produce/
> ConsumeXXX
> 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 ?
> (i) Language
> This would allow a developer to declare what languages are acceptable
> for input and what languages can be produced for output. Adding this
> facility would allow a developer to use different classes or methods
> for different languages, e.g.:
> @UriTemplate("/someuri")
> public class SomeClass {
> @ProduceXXX(value="application/xml" language="en")
> @HttpMethod
> public Source getEnglish() {...}
> @ProduceXXX(value="application/xml" language="fr")
> @HttpMethod
> public Source getEnglish() {...}
> ... // other languages
> }
> 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.
> (ii) Charset
> The java.nio.charset.Charset class describes a set of standard
> encodings that must be supported by any Java implementation and
> includes methods to list the supported encodings for a particular
> installation. The CharsetProvider class defines a standard way to add
> support for additional charsets. On my Mac I have support for the
> following charsets:
> Big5, Big5-HKSCS, EUC-JP, EUC-KR, GB18030, GB2312, GBK, IBM-Thai,
> IBM00858, IBM01140, IBM01141, IBM01142, IBM01143, IBM01144, IBM01145,
> IBM01146, IBM01147, IBM01148, IBM01149, IBM037, IBM1026, IBM1047,
> IBM273, IBM277, IBM278, IBM280, IBM284, IBM285, IBM297, IBM420,
> IBM424, IBM437, IBM500, IBM775, IBM850, IBM852, IBM855, IBM857,
> IBM860, IBM861, IBM862, IBM863, IBM864, IBM865, IBM866, IBM868,
> IBM869, IBM870, IBM871, IBM918, ISO-2022-CN, ISO-2022-JP, ISO-2022-
> KR, ISO-8859-1, ISO-8859-13, ISO-8859-15, ISO-8859-2, ISO-8859-3,
> ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
> ISO-8859-9, JIS_X0201, JIS_X0212-1990, KOI8-R, MacRoman, Shift_JIS,
> TIS-620, US-ASCII, UTF-16, UTF-16BE, UTF-16LE, UTF-8, windows-1250,
> windows-1251, windows-1252, windows-1253, windows-1254, windows-1255,
> windows-1256, windows-1257, windows-1258, windows-31j, x-Big5-
> Solaris, x-euc-jp-linux, x-EUC-TW, x-eucJP-Open, x-IBM1006, x-
> IBM1025, x-IBM1046, x-IBM1097, x-IBM1098, x-IBM1112, x-IBM1122, x-
> IBM1123, x-IBM1124, x-IBM1381, x-IBM1383, x-IBM33722, x-IBM737, x-
> IBM856, x-IBM874, x-IBM875, x-IBM921, x-IBM922, x-IBM930, x-IBM933, x-
> IBM935, x-IBM937, x-IBM939, x-IBM942, x-IBM942C, x-IBM943, x-IBM943C,
> x-IBM948, x-IBM949, x-IBM949C, x-IBM950, x-IBM964, x-IBM970, x-
> ISCII91, x-ISO-2022-CN-CNS, x-ISO-2022-CN-GB, x-iso-8859-11, x-
> JIS0208, x-JISAutoDetect, x-Johab, x-MacArabic, x-MacCentralEurope, x-
> MacCroatian, x-MacCyrillic, x-MacDingbat, x-MacGreek, x-MacHebrew, x-
> MacIceland, x-MacRomania, x-MacSymbol, x-MacThai, x-MacTurkish, x-
> MacUkraine, x-MS950-HKSCS, x-mswin-936, x-PCK, x-windows-50220, x-
> windows-50221, x-windows-874, x-windows-949, x-windows-950, x-windows-
> iso2022jp
> 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.
> (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 ? 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.
> Marc.
> ---
> Marc Hadley <marc.hadley at>
> CTO Office, Sun Microsystems.
> Notice: This email message, together with any attachments, may
> contain information of BEA Systems, Inc., its subsidiaries
> and affiliated entities, that may be confidential, proprietary,
> copyrighted and/or legally privileged, and is intended solely for
> the use of the individual or entity named in this message. If you
> are not the intended recipient, and have received this message in
> error, please immediately return this by email and then delete it.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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