Archive for March, 2013

Generating xml schema documentation elements from JAXB annotated classes

Wednesday, March 27th, 2013
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 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!

Tell me how you build your buildings and I’ll tell you who you are

Saturday, March 9th, 2013
I have to admit that I succumbed to the temptation of starting SimSity Social several months ago. As a game that intrigued me even when I was a kid and a genuine fan of God/simulation games I just couldn’t resist. All in all, I can say that even though the mechanics are not quite what a stand-alone simulation game usually brings to the table, the whole package is on the whole pleasing and engaging.
This however is not the subject of this post, this post is about some strange cities that my neighbors have built.

 This one is really special, very good distribution of population-boosting buildings and zones approach for businesses and factories. Can you say anal?

 Also very interesting vertically aligned buildings in columns shuffled between businesses, not obvious way to get high population but to be honest, I don’t think he cares that much. Especially with all the police/hospital/firefighting facilities. Can you say square?

 This one is one of my favorites… What’s with all the same buildings and businesses? Also, look at the nice flower plantation around the mayor’s office 🙂  Can you say particular?

This stuck me when I saw it, the owner, once expanded nicely on the main map, is slowly expanding over the island creating first the road grid, only to put the buildings at a later moment. Impressive! Organized and patient!