From Sun:

WADL is designed to provide a machine processable protocol description format for use with such HTTP-based Web applications, especially those using XML.

A WADL file is an XML based language specification used to describe WEB-based applications. These files define resources, methods, requests and responses. The WADL project (https://wadl.dev.java.net/) houses the language specification as well as a wealth of other information including source code, examples and documentation.

wadl2java Utility

The WADL project also provides a Java utility called wadl2java. Wadl2java produces Java stubs from WADL files. The utility can be called directly from the command-line or as an Apache Ant task. At first I was a little baffled over how this utility worked. So, I decided to email the creator, Marc Hadley, with some questions. I was pleasantly surprised that he answered my questions. My concern was that wadl2java requires separate tasks and output directories for every WADL file. I’m use to having all generated classes contained within the same directory. Marc pointed out that even if he changed wadl2java to allow for this, the possibility still existed that a conflict could arise when two separate WADL files specified an XML element or attribute with the same name. Whichever WADL file was processed last would generate a class that overwrote the preceding. Wow, the light bulb went off, now I understood why it works the way it does. This was a conscience design decision to avoid class-naming conflicts, thus the utility must place these files in separate directories. In other words, if you were creating an application that consumes the services of two separate applications described by their own WADL files, two separate ant tasks would be required to produce the class stubs. Three applications would require three ant tasks, and so on. The generated stubs must be placed in independent output directories or the results from the second WADL would overwrite at least the end-point of the first WADL, as well as any other like-named classes. To avoid this, wadl2java has some built-in dependency checking that can be specified within the ant task.

Areas for Improvement?

Since the WADL project provides documentation I won’t go into details about the specification. However, I would like to point out a few areas that I found a bit confusing. When creating a WADL to describe an application, the ‘method’ reference has an ‘href’ attribute whose value must be prefixed with a pound ‘#’ sign. I see no practical reason for this requirement and would suspect that the WADL utilities can be programmed in such a manor to eliminate it. Additionally, the ‘href’ attribute actually is associated with the ‘id’ attribute of the ‘method’ definition such that the value of the ‘href’ attribute in the ‘method’ reference minus the pound ‘#’ sign refers to the value of the ‘id’ attribute in the ‘method’ definition. This is confusing because the labels used for these attributes are not consistent. Here I would suggest that both attributes be labeled the same. If it makes sense to use ‘href’ then both should be ‘href’. Otherwise, both should be ‘id’.
Another confusing area is the ‘method’ definition’s ‘name’ attribute. A ‘name’ attribute is usually an attribute used to identify something and is similar in function to how the ‘id’ attribute is being used. However, is this case, the value of this attribute really refers to the HTTP method type used to access the application. I would suggest that the attribute be labeled as ‘type’ or something similar.

Finally, the use of a ‘description’ attribute within the wadl2java’s ant task concerns me. This task uses the ‘description’ attribute to indicate the name of the WADL file one wishes to process. This is a little puzzling. Most Ant tasks I’ve seen make use of a ‘description’ attribute to provide a means for adding comments or further information regarding the particular task being performed. Maybe a better label for such an attribute would be ‘file’.

Overall…

Generally the WADL specification and its related tools excite me. I would recommend its use to anyone seeking a simple yet powerful means to describe any WEB-based application.
For more information about WADL please check out their site at https://wadl.dev.java.net/.

Originally published May 23, 2007.

createTank Attends…

After much thought, I attended the LZA Boot Camp in Baltimore last month (April 23-25) for what boiled down to two hard, tangible reasons:

1. To widen my horizons (and createTank’s) by concentrating on a broader and more business oriented slant toward SOA (createTank has historically focused on research around the implementation questions of a SOA, or software architecture in general).
2. To attain an architectural (and specifically a SOA) credential to differentiate createTank from those that are “architects in name only” (see Vitruvius’ Education of an Architect to be discussed here at a later date). The fact that this credential would come from such an independent and objective organization as ZapThink was quite a convincing point.

I did in fact get what I came for … I saw a review of SOA from a different perspective, and I am now a Senior Licensed ZapThink Architect (Senior LZA). However, I did get more than I expected. Specifically, I found in my notes and “take-backs,” a refinement in some of our positions at createTank. I also met quite a few good Architects and Technologists from across the country and around the world that should hopefully prove to be good friends with which to bounce and share architectural ideas. I’d been looking for a community such as this for a long time now.

Since Then…

I’ve finally found the time to review the notes and complete my internal reports. They really did pack a lot into the three days. The time betwixt has allowed me a good deal of dialogue with other Architects, including our own Larry Liberto, which has further refined the positions and ideas of interest. I should be posting many of our findings and related interesting points here over the next few weeks.

Concerning the refined positions, most are agreed upon by createTank and ZapThink, but createTank seems to have a slightly different take in areas which may prove interesting. This is likely due to our technical and implementation specific background. It might be an over simplification, but we tend to ground our architectural advice from below in our implementation experience, whilst ZapThink tends to support their architectural advice from above with business experience. Of course both methods are legitimate and useful, but they are different. There is a great deal of overlap, as there should be in architecture, but by researching the differences, we may refine our positions and learn more from each other. I’m somewhat amazed at how we’ve come to so many of the same conclusions about SOA and Architecture in general while approaching the problem from such different perspectives. I’d speculate that the common factors are [1] experience and [2] the ability to be honest about that experience. It seems that many groups (especially vendors) let marketing get in the way of that which is best left in its simplest state.

We at createTank have been big fans of ZapThink for a while now as one of only a few organizations out there that were not trying to sell SOA as a set of products, but rather trying to reveal the truth behind its power. I would definitely recommend the LZA Boot Camp to any genuine or aspiring Architect out there with an interest in seeing SOA framed in an objective manner. I’d also recommend it to organizations looking to implement SOA internally, as a vaccine to the seemingly endless vendor sales pitches in store for them.

ZapThink: http://www.zapthink.com/

ZapThink LZA: http://www.zapthink.com/lza.html

ZapThink Architect Resource Center [ARC]: http://www.zapthink.com/ARC-view.html

Next Scheduled LZA Event: Sydney, Australia May 28-30, 2007
Register: http://www.zapthink.com/eventreg.html