Friday, October 12, 2012

Latest WADL To Java enhancements in CXF

Dan has released CXF 2.7.0 which has some major enhancements including the addition of the asynchronous HTTP conduit and initial support for most parts of JAX-RS 2.0 (the topic of the next post on this blog).

What I'd like to mention in this post is the few enhancements to CXF wadl-to-java code generator, added thanks to the colleagues from Talend ESB team who have been stressing the generator to the limits :-).

One of the issues with processing complex WADL documents is that it is not obvious whether (URI) path parameters attached to one of the parent resource elements have to be inherited when generating the method signatures for descendant resources, for example:


<resource>
<param name="id" style="template"/>
<method name="GET">
</method>
<resource>
<resource>
<method name="POST">
</method>
</resource>
</resource>
</resource> 


Does the user want a generated method signature corresponding to "POST" contain an 'id' parameter or only have it added when a "GET" method available directly under the parent resource is processed ?  By default CXF does not add the current parameters to all the descendant methods. Note, WADL provides a mechanism to link to global parameter declarations from within individual methods but if restructuring a given document is not ideal then a new "inheritResourceParams" property will help.

Here is another issue one may face. Suppose you have an XML representation in the schema and the generated code will reference a JAXB-generated class name, say, "books.Book" class. What if you'd like a JAXP Source be used instead ? And what if you have a representation which has "multipart/form-data" payload, it is not 'fair' having no reference to whatever class may be able to handle this payload added to the generated code.

No problems, it is going to be easy with a new "repMap" (the representation map) property, for example, it may have pairs like "application/xml : javax.xml.transform.Source" and "multipart/form-data : org.apache.cxf.jaxrs.ext.multipart.MultipartBody". Note this property is effective when a given representation has no actual reference to a schema element, which is the case for all non-XML representations.

Now, suppose you have a jaxb binding document overriding the name of the class to be generated by JAXB and the generator missing on it,  or you have to 'override' an XML representation linking to the scheme element for the latter be handled by JAXP Source. This is where a new "tMap" parameter will become handy.

Please experiment with the above options, I know some users have already tried them and hope they will be of real help.

As far as WADL itself is concerned...As you know it has not been made a standard yet. However with the original wadl-to-java project at Oracle being under the active development and the CXF generator being regularly enhanced it is likely to become more and more useful tool for testers and for users of WADL-'aware' RESTful endpoints. Don't be concerned too much that WADL is not going to accepted at the universal mechanism for describing and working with RESTful services - it has its niche and hopefully it will make it into becoming a final recommendation one day.