On Apr 13, 2010, at 11:26 PM, Suchitha Koneru (sukoneru) wrote:
> Hello Paul,
>
> Is the issue specified below, which was raised in the past being taken
> into account while Enhancing WADL generation ?
>
> https://jersey.dev.java.net/issues/show_bug.cgi?id=416
>
Yes, all WADL related issues will be taken into account.
>
> Can we add support for inferring method return types, from the method
> declarations instead of adding this information through Java DOC
>
I think so as per what Marc stated: "As an aside it looks like one can
determine the QName of a JAXB annotated class at runtime".
Paul.
> Could you please let me know,
>
> Thanks,
> Suchitha
>
> -----Original Message-----
> From: Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
> Sent: Tuesday, April 13, 2010 7:37 AM
> To: users_at_jersey.dev.java.net
> Subject: Re: [Jersey] Enhanced WADL Generation Thoughts
>
>
> 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
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>