Generating xml schema documentation elements from JAXB annotated classes

When you're in the business of creating Java Web Services today, be it JAX-WS or JAX-RS, one of the difficult things to get right is actually documenting the entities from a API developer point of view, especially in the scenario where your model is the code.
The main problem comes to the fact that a JAXB annotated model doesn't map anything to the generated schema contracts (be it  WSDL or WADL+XSD) and classes. This is understandable as Javadocs don't exist at runtime and there is no specific JAXB annotation that maps to the xs:annotation, xs:documentation and xs:appinfo schema elements. Various tools like enunciate and all provide some support to to compile time generation but from my point of view the generated wadl + schema (my main scenario) is not the same quality as is the runtime generated ones.
Can this be improved?
Some guys at the The Distributed Systems Group (DSG) of the Information Systems Institute at the Technical University of Vienna certainly thought so and they forked the JAXB API project to add the Java annotations for xs:annotation, appinfo and documentation, modified the JAXB implementation library schema generator to enhance the produced xsd by mapping the annotations to schema elements and also (which seems was their primary objective) added support for schema facets thus allowing you to express with annotations things like pattern facets, min/max etc.).
The project is hosted here but there's a fork which is a bit easier to test because they went around a bit the troublesome java endorsed directory classloading mechanism (needed because JAXB implementation classes are on a protected package within the JDK) (this might change in time).
All in all, it looks very promising as it works with JAX-RS and Jersey so, if they can unify the facets with the JSR-303 and JSR-349 annotations and also have it supported by the xjc binding compiler it would go a really long way in providing a much nicer API documentation (yes, yes, that's soooo 90'ies blah blah) and schemas but also declarative validation of service interfaces.
If you agree, point your browsers to the java.net JIRA and vote here.
All in all a nice renaissance for services considering Jersey 2.0 is coming up and all the hypermedia API standards that are emerging.
On a tangent, I believe a fair chunk of JAXB schema generation code was written by Kohsuke (of Hudson/Jenkins fame). If you dig in and read the code, your mind will warp, you have been warned.
Now, do your company a favor, make them buy OxygenXML and generate some nice docos!

Comments

Post a Comment

Popular posts from this blog

Relaxing SSL validation for JaxWS

I've recently had the need to access a web service developed in .Net and signed with a self signed certificate. I've decided to use the JaxWS and the Metro stack to develop the client and run it on Java6. As a plus, the service was protected with username and password. The service was exposed on an IP address and I repetedly had problems in establishing a connection. In the end, thanks to this article, it was obvious that the certificate was not created with the alternative name attribute but it was not an option to change the certificate as the web service was already used by other consumers (.net clients don't suffer by this issue). So, on my quest to relax the validation, I've found out this article and code snippet, which did not compile at first (I guess package names were changed in JDK6) so I've did some trivial refactoring and now, after invoking the static methods in the client code, the SSL connection gets validated with no problems. Hope it helps and th...
Read more

Kaspersky Anti Virus 6 and Subversion problems

I've spent a good part of my day today in trying to understand why I can't checkout our subversion repository. I was getting this: svn: REPORT of '/svn/repos/!svn/vcc/default': 400 Bad Request google searches would make you think it's a proxy issue but I don't use or need one so after a lot of trial and errors I've found out that if you use Kaspersky Anti-Virus 6 it seems that if you use the Web Anti-Virus options with the recommended settings and you have the "Scan HTTP traffic" option on you end up with the problem above. It seems Kaspersky doesn't like the HTTP packets subversion uses so they get blocked. I really like Kaspersky and I recommend it to all but I hope they will address this issue as soon as possible as subversion is becoming the main open source VCS system. Any tips on this issue are welcome.
Read more

Search and Replace in ODT using AODL

Recently I needed to create a way to search and replace a word in a OpenOffice OpenDocument ODT. It would seem the project itself already has a library AODL (take care, at least two other project pages but with older code) that exposes the format model but I didn't find any utility methods like search and replace functionality. I've created two versions of the method, one a old-style, imperative approach, and the other, a LINQ version. As I'm still new to LINQ it would seem that the classical approach produces a more efficient code. Anyone care to chip in and make a faster algorithm? In this particular version I'm just going for simple string equality, I didn't want to go with other StringComparison methods (just look at the Equals overload method). public static void SearchAndReplaceString(TextDocument document, string searchText, string replaceText) { var content = document.Content; foreach (var item in content) ...
Read more