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: dev_at_jsr311.dev.java.net
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 sun.com>
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.