nova-api team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Okay,

I looked over the issue in detail.

There are a number of things going on:

1)  WADL2Java expects XSD 1.0 but we're using XSD 1.1.  That's actually not that big of a deal, because you can convert between the two by running the WADL trough our normalizer. See https://github.com/rackspace/wadl-tools

2)  WADL2Java  puts resource_types and entity types in the same java package.  We have a resource type called metadata that captures all of the properties of metadata that are shared between images and servers and that translates that into a java interface called Metadata.  We also have an entity type called Metadata and that gets translated into a class called Metadata.  The interface and the class are both in the same package so things blow up.  Personally, I think this is an issue with WADL2Java trying to put everything in the same place.  Media-type bindings should go in a different package in my opinion.

I hand crafted a normalized WADL that resolves the problem by renaming the offending resource types and put it here:

https://github.com/RackerWilliams/compute-api/tree/norm/openstack-compute-api-1.1/src/normalized/wadl2java

You should be able to run that via wadl2java and have it generate code.  I also put a story in the wadl-tool backlog that will add options to the normalizer so that kind of normalization can be done automatically so moving forward we shouldn't have to maintain n versions of the WADL -- that's the idea behind the normalizer anyway.

Now about WADL in general.  I agree with Waldon that we should have a parseable description of the contract. There are a lot of advantages to doing that especially in terms of QA and documentation.  Personally, I'm a fan of WADL because it opens up a lot of doors in both of those departments.  That said, I also agree with Mark that the language bindings that get created directly from a description like WADL tend to be very brittle (they also tend to be low level least common denominator bindings).  You can see the kind of brittleness that issue 2 above can lead to.  Say you file a bug with the WADL2Java guys asking for resource types to be put in another java package.  Once the bug get's fixed there's no way that the change won't break existing code!

You can certainly use some code generation to help humans build a language binding, but you shouldn't bind directly to auto-generated code if you can avoid it because that code can change from under your feet.  There should be a level of abstraction there so that bindings keep working even if the underlying generated code changes. At the end of the day, a language binding is a an API in the traditional sense and you can't have it change willy-nilly.   

-jOrGe W.

On Dec 9, 2011, at 2:45 AM, Pedro Navarro Pérez wrote:

> Thanks ! I didn't know there are different versions. I'll try again
> with the right version
> 
> Pedro
> 
> On Thu, Dec 8, 2011 at 4:54 PM, Brian Waldon <brian.waldon@xxxxxxxxxxxxx> wrote:
>> I'm with Lorin here. The aim of a WADL is to provide a parseable description of a contract.
>> 
>> Pedro: Make sure your tool is using the same WADL version (I think there's 2006 and 2009) as the spec itself. Maybe one of those doesn't allow assert tags? I have personally built the WADL on my own machine, so I know it is possible...
>> 
>> Waldon
>> 
>> 
>> On Dec 6, 2011, at 10:02 PM, Lorin Hochstein wrote:
>> 
>>> 
>>> 
>>> On Dec 6, 2011, at 9:56 PM, Mark Nottingham wrote:
>>> 
>>>> My understanding is that this isn't supporrted; WADL is used in OpenStack for generating documentation and QA. Generating static bindings from a description like this leads to brittleness.
>>>> 
>>> 
>>> I thought  one of the aims of having the WADL was this specific use case: to support automatic generation of bindings for various (non-Python) languages. This came up during one of the sessions at the Essex design summit.
>>> 
>>> Lorin
>>> --
>>> Lorin Hochstein, Computer Scientist
>>> USC Information Sciences Institute
>>> 703.812.3710
>>> http://www.east.isi.edu/~lorin
>>> 
>>> 
>>> --
>>> Mailing list: https://launchpad.net/~nova-api
>>> Post to     : nova-api@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~nova-api
>>> More help   : https://help.launchpad.net/ListHelp
>> 
> 
> -- 
> Mailing list: https://launchpad.net/~nova-api
> Post to     : nova-api@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~nova-api
> More help   : https://help.launchpad.net/ListHelp