On Apr 13, 2010, at 10:26 AM, Isak Jonsson wrote:
> Marc, I completely vote for annotations. I have already set up such a system for my project (@WadlDoc, @WadlIgnore, @WadlReturn, and some other home-brew annotations...) and do JAXBElement QName deduction. Works like a charm! The home-brew annotations (eg a wiki link) could probably be turned into something more general.
>
Great, are you able to share more details about your work - patches are always welcome...
Marc.
>> From: Marc Hadley <marc.hadley_at_oracle.com>
>> Content-Type: text/plain; charset=us-ascii
>> Date: Mon, 12 Apr 2010 11:56:23 -0400
>> Subject: Enhanced WADL Generation Thoughts
>>
>> The current extended WADL support is based on custom Javadoc tags:
>>
>> http://wikis.sun.com/display/Jersey/WADL
>>
>> Its very handy but it suffers from a couple of problems:
>>
>> (i) Its quite involved to set up
>> (ii) Its not very internationalization (I18N) friendly.
>>
>> The current support can be split into two functional areas:
>>
>> (a) Additional runtime information
>> (b) Documentation
>>
>> It seems to me that for (a) we could fix (i) by making the following
>> Javadoc tags (see
>> http://wikis.sun.com/display/Jersey/SupportedJavadocTagsForExtendedWADL
>> ) be annotations instead:
>>
>> @request.representation.qname
>> @request.representation.mediaType
>> @response.param
>> @response.representation.XXX.qname
>> @response.representation.XXX.mediaType
>>
>> E.g. to provide additional metadata about a set of possible responses
>> produced by a method you could add the following annotation:
>>
>> @WadlResponses({
>> @WadlResponse(status=200, mediaType="application/foo+xml",
>> entity=Foo.class),
>> @WadlResponse(status=400, mediaType="application/error+xml",
>> name="error", namespace="http//example.com/errors")
>> })
>>
>> As an aside it looks like one can determine the QName of a JAXB
>> annotated class at runtime so the first @WadlResponse should be
>> implementable.
>>
>> Using annotations for this would remove the need for addition steps in
>> the build and greatly simplify things IMO.
>>
>> For (b) I really like the re-use of Javadoc but looking at the I18N
>> tools out there it seems like most (if not all) are based on property
>> files in resource bundles. We could address (ii) by supporting property
>> files that hold the additional documentation. We could define some kind
>> of method->property name mapping so that alternate localizations can be
>> included with an app and selected at runtime using the value of the
>> HTTP Accept-Language header. I think this would also address (i) since
>> the property files can easily be included when building the code but it
>> would lose the connection to Javadoc unless we offered some doclet that
>> would generate the initial property files from existing javadoc.
>>
>> What do folks think ?
>>
>> Thanks,
>> Marc.
>>
>>
>>
>>
>