On 05/11/2009 15:10, Marc Hadley wrote:
> 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.
Yes, that was the idea. The idea was to support this in those cases
where you really want the bare input stream; but would still like to
declare the type in the schema. I would guess this wouldn't be used that
often.
>
>>> 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.
I would be interesting to understand better why it didn't work for you
if you have time. There must be something fundamental that I am missing
in the design. I do see why like many builder/fluent APIs you ended up
having to use a variant of Grafton's Gadget to encode generic types.
Having said that doesn't WADL generation use the static interface of the
class which does contain generic type information in most cases? It is
just inside the method that all the useful information evaporates.
>
>> Perhaps it might be better to declare the return type in the
>> annotation and then a generic mechanism could be utilized?
>>
> +1.
Not sure it would be required , if at all possible the Response/Builder
issue could be resolved in some way. Would have to create static
subtypes of GenericEntity to provide the static class literals you would
need for this:
static class GListString extends GenericEntity<List<String>> {
public GListString(List<String> list) {
super(list);
}
}
That could work I guess, you don't need an instance of this class to
work out what the generic parameters are.
>
>>
>>> 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.
I think I understand the generic interface; but as you say in some cases
the type information is going to be missing. So this would only apply to
readers such as the JAX-B one where the static information is available.
>
>>
>>> 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.
Not sure I like the annotation -> return type because of all the hoops
you need to jump through in order to create generic class literals. But
I think that the QName annotation could be generally applied.
Cheers
Gerard
>
>>
>>>
>>>
>>> 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
>>>
>>
>
>
> ---------------------------------------------------------------------
> 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