The fact that WADL is XML is both a bless and a curse. It is sort of convenient not having to worry about syntax, getting code completion in Emacs nxml-mode, and to have the ability to transform WADL into other things, using XSLT for instance. However, no matter what you try, there will always be some chunks model relationships that are available as first class citizens in the Infoset representation of WADL. So something that seemed really easy, often turns out much harder, and you find yourself having to pull in EXSLT to accomplish something simple.
So the question is, is the XML representation actually all that convenient at all? What about using Java instead?
A couple of months ago, I looked under the hood of the current collection of WADL tools, to find out there is not such a thing as a real convenient API layer to build to build your own processing tools. The classes in wadl-core currently postprocess a JAXB decoded representation of the WADL file, but you cannot access that postprocessed instance unless you modify or copy source code.
So I figured to see if I could create an API and get that injected eventually. You can find the results here. As you will notice, there is not a single line of real documentation, but I hope I will have some time to work on that soon.
Any way, what I tried to do is to marry a couple of conflicting concerns.
First of all, I want to be able to process a model using StringTemplate. As a consequence, you need to be able to traverse your entire model using bean property accessors. So I wanted to stick with the bean naming convention, and expose all of that in the most straight-forward way.
Second, I also wanted the different chunks of metadata found in a WADL file to be linked. So if I am referencing template parameters in my path attributes of a resource, I want to the path’s template parameter’s representation in Java to be linked to the metadata that is normally defined in the param sub elements of the resource.
Third, I wanted the API really to reflect the constraints WADL imposes. According to the schema, you can use plain style parameters everywhere. According to the spec, you can only use them inside of representation elements. I want to make sure the API reflects that.
And then I also wanted to be able to deal both with the expanded URI templates as well as the individual paths. The path normally does not contain query parameters. But the URI template should.
The trouble with APIs like these is that there are just different views and different ways to provide easy access to the different model elements. I’m trying to strike a balance here. Hopefully you will appreciate it.