Wire Compatibility of Web Services

As a software professional, you may have heard about the source compatibility and binary compatibility. With the Web Services, a new type of compatibility came up. This is what I call wire compatibility. It’s not related to the programming but the XML messages passed on the wire. Since we don’t use XML directly but programming APIs, the wire compatibility surfaces and affects the source and binary compatibility.

Too abstract? You bet. Let’s pick up an example here. Because VMware vSphere API is defined in WSDL, I will use it in the following discussion.

Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.

In vSphere 4.1, the method PowerOnMultiVM_Task() gets an additional parameter called option typed as OptionValue array. The following are related parts in the WSDL:

<operation name="PowerOnMultiVM_Task">
  <input message="vim25:PowerOnMultiVM_TaskRequestMsg" />
  <output message="vim25:PowerOnMultiVM_TaskResponseMsg" />
  <fault name="RuntimeFault" message="vim25:RuntimeFaultFaultMsg"/>
<complexType name="PowerOnMultiVMRequestType">
    <element name="_this" type="vim25:ManagedObjectReference" />
    <element name="vm" type="vim25:ManagedObjectReference" maxOccurs="unbounded" />
    <element name="option" type="vim25:OptionValue" minOccurs="0" maxOccurs="unbounded" />

As you can see, the minOccurs of the option element is zero, meaning it’s optional. If you have an application built with 4.0 (no option parameter by then), the SOAP request still works. So it’s compatible on the wire.

As said, most people don’t program with XML but stubs. The generated stubs in 4.0 and 4.1 are different. The following is the code from vijava API 2.1.

/** old signature for back compatibility with 2.5 and 4.0 */
public Task powerOnMultiVM_Task(VirtualMachine[] vms) throws RuntimeFault, RemoteException 88
  return powerOnMultiVM_Task(vms, null);
/** @since SDK4.1 */
public Task powerOnMultiVM_Task(VirtualMachine[] vms, OptionValue[] option) throws RuntimeFault, RemoteException
    throw new IllegalArgumentException("vms must not be null.");
  ManagedObjectReference[] mors = MorUtil.createMORs(vms);
  ManagedObjectReference tmor = getVimService().powerOnMultiVM_Task(getMOR(), mors, option);
  return new Task(getServerConnection(), tmor);

As you can see, the new stub changes its signature and breaks the existing application built on top of the method. In other words, if your application uses the method with 4.0 API, it won’t compile against 4.0 API stub. This is a typical case where compatible on wire but not on source code.

To mitigate the issue, vijava includes a shorthand method with previous method signature for source compatibility (see the comment in the code). It simply calls the new method with null in place of the additional parameter. This is an additional value provided by vijava besides the other benefits like object model and performance.

BTW, vSphere API compatibility is more than wire compatibility. Check out this blog for more.

This entry was posted in Software Development, vSphere API and tagged , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.