On Apr 14, 2010, at 11:04 AM, gerard davison wrote:
>
> Just to check, newer than the w3c draft version that was put in
> place for Jersey 1.2?
>
It was, but then we reverted it back, because it would have broken
backwards compatibility.
This then prompted an "all cards on the table" re-think about WADL
integration.
Paul.
> 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
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>