On Nov 5, 2009, at 8:47 AM, Paul Sandoz wrote:
>>
>> Before I do this lets check that I am thinking along the right
>> lines. We have a few cases here and I want to make sure I raise a
>> sensible issue, I am guessing that we want to get away from javadoc
>> comments as that makes the assumption the source is available.
>>
>> 1. Bean parameters / return values
>>
>> This is the trivial case, we can derived the xml type from the JAX-
>> B element
>>
>> @Produces("application/xml")
>> @Consumes("application/xml")
>> public Bean echo(Bean value)
>> {
>> ...
>> }
>>
>
> Yes.
>
>
>> 2. Generic types
>>
>> These could be annotated with the standard JAX-B annotations; but
>> unfortunately @XmlElement can only be attached to types and
>> methods. Instead we would have to invent a new annotation type.
>>
>> @Consumes("application/xml")
>> public void process(@RSQName(name="root", namespace="http://www.example.com
>> ") Reader value)
>> {
>> }
>>
>
> One issue is there could be a mismatch for the qname declared in the
> annotation compared to the actual qname for the Reader type. And is
> it not redundant information? So perhaps such an annotation only has
> value when a qname cannot be derived from the type?
>
Sounds right to me.
>> 3. Response type
>>
>> This would be a strong argument for adding a generic parameter to
>> the Response/ResponseBuilder interfaces;
>
> Marc and I tried and failed miserably. We could not get things to
> work with type safety using the response building pattern.
>
Yes, I forget the exact problem no but we couldn't get it to work
satisfactorily. We settled on the GenericEntity class to capture the
generic type for use with Response or non-committal return types like
Object. Unfortunately this only works at runtime and isn't any use for
WADL generation.
> Perhaps it might be better to declare the return type in the
> annotation and then a generic mechanism could be utilized?
>
+1.
>
>> but that would only work for simple bean types unless we allow the
>> @RSQName annotation on the response object (Actually it would be on
>> the method; but this is a common idiom for annotating the return
>> type)
>>
>> public Response<BeanType> echo(....)
>> {
>> Response.ResponseBuilder ok = Response.ok();
>>
>> Response.ResponseBuilder<BeanType> typed = ok.type(BeanType.class);
>> return type.entity(bean).build();
>>
>> or
>>
>> return type.entity(BeanType.class, bean).build();
>> }
>>
>> I guess it is far to late to make this change for -RS 1.1. It would
>> help me a lot with the client stuff I have been working on.
>>
>>
>>
>> 4. MessgaeBodyReader / MessageBodyWriter
>>
>> So I guess this is a less common use case if the type cannot be
>> derived from the bean class. The problem here though I guess is
>> that a reader / writer might produce different content depending on
>> the context.
>>
>> @Produces
>> @RSQNames(
>> {
>> @RSQName("cars", "http://www.example.com")
>> @RSQName("houses", "http://www.example.com")
>> }
>> public GenericReader implenents MessageBodyReader
>> {
>> ...
>> }
>>
>
> I was more thinking of a generic interface that is implemented to
> derive the qname from the JAXB bean or any XML related artifact,
> rather than explicitly declaring Qnames on readers/writers. As we
> don't want developers to have to write their own message body
> writers for common functionality. Thus the qname for 1) is can be
> obtained via the generic functionality on the JAXB readers/writers.
>
Is the reason for tying this to readers/writer that you could re-use
the existing isReadable/isWritable method to locate the correct
provider to query ? This only works when the entity type is statically
available though, for Response return types or types like Object you'd
still need an annotation to supply the necessary QName.
>
>> 5. XmlBeans
>>
>> I guess you are talking about http://xmlbeans.apache.org/, in
>> theory the annotation method should work just fine for this.
>
> Yes, but like 4 i think we can do something more generic rather than
> application specific.
>
Agree, the annotation approach (like the existing javadoc tag) could
apply to any type.
Marc.
>
>>
>>
>> Does that seem a reasonable summary?
>>
>> Gerard
>>
>>
>>
>> On 05/11/2009 11:02, Paul Sandoz wrote:
>>> On Nov 5, 2009, at 11:55 AM, gerard davison wrote:
>>>
>>>>
>>>>
>>>> Paul,
>>>>
>>>> Is there an issue for this?
>>>
>>> No, would you like to log an enhancement?
>>>
>>>
>>>> Presumably it should be possible to work out the bean types
>>>> automatically without having to use the javadoc tags.
>>>>
>>>
>>> Yes that should be possible, i recall now we had a quick
>>> discussion on this. Ideally we should have something that can work
>>> with say XmlBeans too. Which makes me think the right place to
>>> define this would be for a message body reader/writer to implement
>>> a known interface.
>>>
>>> There is one issue with responses, the return type may be of the
>>> type Response. So it might be necessary in some cases to declare
>>> something using an annotation instead.
>>>
>>>
>>>> (This is work I am interested in doing at some point)
>>>>
>>>
>>> OK!
>>>
>>> Paul.
>>>
>>>> Gerard
>>>>
>>>>
>>>> On 05/11/2009 08:55, Paul Sandoz wrote:
>>>>> On Nov 4, 2009, at 7:28 PM, Suchitha Koneru (sukoneru) wrote:
>>>>>
>>>>>> Thanks Paul for the response.
>>>>>> I haven't included javadoc tags as we do not have much java
>>>>>> documentation added to the methods. Is java doc necessary for
>>>>>> generating
>>>>>> xsd references in the wadl's requests and responses ?
>>>>>
>>>>> Yes. That is currently the only way to associate xsd references
>>>>> with entities of resource methods.
>>>>>
>>>>>
>>>>>> Is there any
>>>>>> tutorial which gives instructions on adding jersey specific
>>>>>> java doc ?
>>>>>
>>>>> See the previous link i sent and also look at the JavaDoc of the
>>>>> extended-wadl sample and the pom file.
>>>>>
>>>>> Paul.
>>>>>
>>>>>>
>>>>>> -----Original Message-----
>>>>>> From: Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
>>>>>> Sent: Wednesday, November 04, 2009 1:21 AM
>>>>>> To: users_at_jersey.dev.java.net
>>>>>> Subject: Re: [Jersey] FW: xml schema in request and response
>>>>>> (wadl)
>>>>>>
>>>>>> Hi Suchitha,
>>>>>>
>>>>>> Did you include javadoc tags such as:
>>>>>>
>>>>>> * @response.representation.200.qname {http://
>>>>>> www.example.com}item
>>>>>>
>>>>>> * @request.representation.qname {http://www.example.com}item
>>>>>>
>>>>>> on the resource methods?
>>>>>>
>>>>>> http://wikis.sun.com/display/Jersey/SupportedJavadocTagsForExtendedWADL
>>>>>>
>>>>>> Paul.
>>>>>>
>>>>>> On Nov 4, 2009, at 8:02 AM, Suchitha Koneru (sukoneru) wrote:
>>>>>>
>>>>>>>
>>>>>>> Xml schemas are attached for reference.
>>>>>>> From: Suchitha Koneru (sukoneru)
>>>>>>> Sent: Tuesday, November 03, 2009 9:55 PM
>>>>>>> To: users_at_jersey.dev.java.net
>>>>>>> Subject: xml schema in request and response (wadl)
>>>>>>>
>>>>>>> Hello Jersey Users ,
>>>>>>> I have looked into extended-wadl sample
>>>>>>> application. I
>>>>>>> was able to generate the extended-wadl which has a href to the
>>>>>>> xml
>>>>>>> schema. However, In the restful service methods , the xsd
>>>>>>> for the
>>>>>>> request and response is not specified. It looks like specifying
>>>>>>> mediaType alone will not suffice, we would also need the
>>>>>>> related xsd.
>>>>>>>
>>>>>>> For instance consider a snippet of the extended wadl
>>>>>>> generated(also attached ). The consumer of the wadl will not be
>>>>>>> aware of xml payload structure in requests/responses.
>>>>>>>
>>>>>>>
>>>>>>> <resource path="Users">
>>>>>>> <method name="GET" id="getAllUsers">
>>>>>>> <response>
>>>>>>> <representation mediaType="application/xml"/>
>>>>>>> <representation mediaType="application/json"/>
>>>>>>> </response>
>>>>>>> </method>
>>>>>>> <method name="PUT" id="updateUser">
>>>>>>> <request>
>>>>>>> <representation mediaType="application/xml"/>
>>>>>>> </request>
>>>>>>> <response>
>>>>>>> <representation mediaType="*/*"/>
>>>>>>> </response>
>>>>>>> </method>
>>>>>>> <method name="POST" id="createUser">
>>>>>>> <request>
>>>>>>> <representation mediaType="application/xml"/>
>>>>>>> </request>
>>>>>>> <response>
>>>>>>> <representation mediaType="*/*"/>
>>>>>>> </response>
>>>>>>> </method>
>>>>>>> <resource path="del/{userID}">
>>>>>>> <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
>>>>>>> type="xs:string" style="template" name="userID"/>
>>>>>>> <method name="DELETE" id="deleteUser"/>
>>>>>>> </resource>
>>>>>>> <resource path="{userID}/">
>>>>>>> <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
>>>>>>> type="xs:string" style="template" name="userID"/>
>>>>>>> <method name="GET" id="getUser">
>>>>>>> <response>
>>>>>>> <representation mediaType="application/
>>>>>>> xml"/>
>>>>>>> </response>
>>>>>>> </method>
>>>>>>> </resource>
>>>>>>>
>>>>>>> The src code for customized wadl generator is
>>>>>>>
>>>>>>> public class SampleWadlConfigurator extends
>>>>>>> WadlGeneratorConfig {
>>>>>>>
>>>>>>> @Override
>>>>>>> public List<WadlGeneratorDescription> configure() {
>>>>>>> return generator( WadlGeneratorApplicationDoc.class )
>>>>>>> .prop( "applicationDocsStream", "application-doc.xml" )
>>>>>>> .generator( WadlGeneratorGrammarsSupport.class )
>>>>>>> .prop( "grammarsStream", "application-grammars.xml" )
>>>>>>> .descriptions();
>>>>>>> }
>>>>>>>
>>>>>>>
>>>>>>> Could you please let me know, if we can include xsd
>>>>>>> references in
>>>>>>> request and response elements of the wadl(similar to a wsdl) .
>>>>>>>
>>>>>>> Thank you,
>>>>>>> Suchitha.
>>>>>>>
>>>>>>> <application.wadl><schema1.xsd><schema2.xsd>
>>>>>>> ---------------------------------------------------------------------
>>>>>>> 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
>>>>>>
>>>>>>
>>>>>> ---------------------------------------------------------------------
>>>>>> 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 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
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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 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
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>
>