Why Some vSphere Java API Methods don’t Work with Old Servers? A Story of Compatibility

Many of you already know there are some changes in the vSphere API from 2.5 to 4.0. The changes include 20+ new managed object types, additional properties (including sub-properties that embedded inside the first level properties), and several inheritance structure changes.

Several managed objects like Datastore became the subtype of ManagedEntity in vSphere 4, which is different from the hierarchy in 2.5 where it’s a subtype of ExtensibleManagedObject. The changes came for good reasons – we want permission control over these managed objects.

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.

The good news is that VMware only added new things and haven’t remove things, therefore vSphere API can still handle the compatibilities. In vSphere Java API, I just used the latest WSDL as reference.

It’s a little bit tricky when it comes to the hierarchical changes. All of sudden, you have many methods inherited from ManagedEntity in vSphere4, but not in 2.5 as before.

Because Web Services is a wire protocol, it doesn’t care whatever hierarchical structure in the client side as long as the final Web Services requests are the same. So the new hierarchical relationship in vSphere 4 still works while talking to older versions of target as long as you don’t use the newly inherited methods, some of which are getter methods for newly added properties.

Here the confusion starts. When you use IDEs like Eclipse, the intelli-sense feature prompts you the inherited methods even you target your applications to an older version of server.  For example, you can easily write the following code:

String dsName = ds.getName();

When you run this code with vSphere 4, there is no problem. But if with 2.5, you get InvalidProperty exception with no clue. That is why a bug was filed (Bug ID: 2969170) last week.

Ideally, vSphere Java API should have done a better job in checking the versioning. I decided not to for various reasons.

First of all is the simplicity. To add something like “java.lang.UnsupportedOperationException,” much checking code needs to be added in different places.

If you want to talk to older version of servers, you want to pay attentions on these details by yourself. The vSphere API Reference is actually pretty handy here.

To avoid some of these incompatibility issues, you should try to use “old” ways to get things done. For example, if you want to get the name of a data store, you should try this:

DatastoreInfo dsInfo = ds.getInfo();
String dsName = dsInfo.getName();

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

One Comment

  1. Posted August 30, 2014 at 4:44 am | Permalink

    I am truly pleased to glance at tuis website posts which
    contains lots of helpful facts, thanks for providing such information.

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.