Thursday, August 23rd, 2007

A bit about WADL (Revised)

In today’s high-tech world there is a growing need to create a simpler way to describe web-based applications. In the past one would use a WSDL to describe such application. One competing project put forth from Sun is Web Application Description Language [WADL] (http://research.sun.com/techrep/2006/abstract-153.html).

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.