Just to check, newer than the w3c draft version that was put in place
for Jersey 1.2?
Gerard
On 14/04/2010 09:12, Paul Sandoz wrote:
> 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
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>
--
Gerard Davison | Senior Principal Software Engineer | +44 118 924 5095
Oracle JDeveloper Web Service, Spring, Weblogic SCA Tooling Development
Oracle Corporation UK Ltd is a company incorporated in England& Wales.
Company Reg. No. 1782505.
Reg. office: Oracle Parkway, Thames Valley Park, Reading RG6 1RA.
Blog http://kingsfleet.blogspot.com Twitter kingsfleet