One WSDL API instead of two

The Woden API provides two 'views' of WSDL via the Component API and the Element API. Questions have been asked about the value of this split and whether a single WSDL model would be better.

The initial goal of the Woden project was to provide a faithful implementation of the W3C WSDL2 spec to identify any problems with the spec and help the WSDL2 working group complete it. The WSDL2 spec is focussed mainly on the component model rather than its underlying XML infoset representation. The component model is intended to be more useful to WSDL2 consumers because they can obtain service information without worrying about XML specifics like traversing composite documents. However, knowledge of the XML infoset and document structure is required by WSDL2 editing and authoring applications that need to manipulate the XML.

To address these two types of usage, the Woden API defines two views of the WSDL (effectively, two WSDL APIs):

The Component API is read-only and is aimed at WSDL consumers. The Element API is read/write, aimed at WSDL authors or editors. The Woden implementation provides only one underlying WSDL object model for these two APIs. The APIs are just different views of the same objects. So it’s simple to move between the views depending on your needs (i.e. consuming service information only versus manipulating the XML infoset). The Component interfaces provide a toElement() method to change to the XML infoset view of a WSDL object and the DescriptionElement interface provides the toComponent() method to show the component model derived from a <wsdl:description>.

As the Woden API has evolved we have seen more overlap between the Component and Element APIs that was envisaged when this initial split was conceived. The Element API was not sufficient in its original form as a pure infoset view. For example, if a WSDL element contained a QName attribute referring to another element, then an accessor method that returned the QName value was sometimes not as useful as a method that returned the object identified by that QName. As we started adding more of the latter type of method to the Element API, it started to look more like the Component API.

One proposal is to combine both APIs into a single WSDL API that serves both purposes; a logical component model and an infoset syntax model. Through Woden’s adopters so far, we have already seen value in the Component model. With our focus on the W3C WSDL2 spec effort to June 2007, we have not yet considered in any depth if/how the Element API might be used and we don’t yet know of any Woden adopters doing WSDL2 authoring or editing. So we can’t yet claim any demonstrated value in having the Element API (at least, not in having a separate infoset API).

We need to consider this issue now that the spec is published, but while the Woden API is not yet finalized. The API will be not be deemed 'stable' until the Woden 1.0 release. There is no point in continuing with 2 separate WSDL APIs unless we have users that want them separate or there are fundamental problems that prevent us combining them.

Some potential problems to consider are:

The difference between Description component and <wsdl:description> element.

This difference is reflected in the Woden API between Description and DescriptionElement. In the component model, there is a single Description component as the top-level container for the other WSDL components that make up a service description. There is no notion of composition via import or include, so there are no nested Description components – just a ‘flattened’ view of the WSDL contained within a single Description component. By comparison, the WSDL XML infoset supports document composition via <wsdl:import> and <wsdl:include> elements, so a complete service description may contain multiple <wsdl:description> elements (e.g. the service WSDL imports the binding WSDL which imports the interface WSDL). In the Woden Element API this means multiple DescriptionElements linked from a root DescriptionElement via ImportElement or IncludeElement.

So, Description and DescriptionElement are not the same thing. Description contains all of the interfaces, bindings and services declared within a top-level or root <wsdl:description> AND within any imported or included descriptions. DescriptionElement represents a single <wsdl:description> element and its directly declared child elements. If the child elements include <wsdl:import> or <wsdl:include>, the corresponding ImportElement or IncludeElement interfaces can be used to navigate to any nested DescriptionElements.

It would be easy enough to combine say Binding and BindingElement into a single interface because they represent the same entity (a single binding) and contain fundamentally the same content (the same binding faults and operations). Combining Description and DescriptionElement requires more thought. Perhaps we could define different sets of methods for get_local_only and get_local_and_nested, with the behaviour of the latter being similar to flattened properties in the existing Description component.

Some of the WSDL infoset not represented in the Component model.

The WSDL elements <documentation>, <import>, <include> and <types> do not have corresponding WSDL components defined – they are infoset only. Likewise, some WSDL attributes are not represented directly as Component properties. For example, description’s targetNamespace is not a Description component property and the messageLabel attribute of binding fault reference is not a BindingFaultReference property (it is only used to determine the corresponding interface fault reference).

If we combine the two APIs, the WSDL component model will be mixed with infoset-specific content and Woden will no longer provide a 'clean' component model view. This new API might be more complicated or at least less obvious for API users wanting to work with the WSDL component model. This only really matters if Woden users care about having a clean component model view versus a component/infoset hybrid.

FrontPage/Woden/APIReview/OneWsdlApi (last edited 2009-09-20 22:47:26 by localhost)