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();