Home > Software Development, vSphere API > Wire Compatibility of Web Services

Wire Compatibility of Web Services

November 23rd, 2010 Leave a comment Go to comments

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.

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

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"/>
</operation>
<complexType name="PowerOnMultiVMRequestType">
  <sequence>
    <element name="_this" type="vim25:ManagedObjectReference" />
    <element name="vm" type="vim25:ManagedObjectReference" maxOccurs="unbounded" />
    <element name="option" type="vim25:OptionValue" minOccurs="0" maxOccurs="unbounded" />
  </sequence>
</complexType>

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
{
  if(vms==null)
  {
    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.

  1. No comments yet.
  1. No trackbacks yet.