users@jersey.java.net

Re: [Jersey] Enhanced WADL Generation Thoughts

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Wed, 14 Apr 2010 10:12:25 +0200

Also forgot to mention that Jersey currently supports an old version
of WADL and we would like to move to the newer version but somehow
without breaking backwards compatibility for existing clients.

Paul.

On Apr 13, 2010, at 4:36 PM, Paul Sandoz wrote:

>
> On Apr 12, 2010, at 5:56 PM, Marc Hadley wrote:
>
>> 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.
>>
>
> Agreed on both points. It works and it can work well once set up but
> i think it is a good time to review and improve it.
>
> It is also specific to JavaDoc so we would require something
> separate say to work with ScalaDoc.
>
>
>> 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.
>>
>
> A minor suggestion: should we make the annotations, by name,
> independent of WADL?
>
>
>> 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 ?
>>
>
> Looks like a good proposal to me.
>
> Paul.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>