Among many well know improvements like huge performance boost, VI Java API 2.0 has a big feature that we don’t talk much. It’s the full compatibility: one library for all the existing version from 2.0, 2.0 to 4.0.
Some people know the pain of using Apache AXIS in an environment with multiple versions of servers. You have to generate at least two sets of libraries and use them at the same time. It’s very inconvenient when you have a type like ManagedObjectReference, which could be com.vmware.vim.ManagedObjectReference or com.vmware.vim25.ManagedObjectReference. If you have to work with both in the same piece of code, you have to include the full type name with package name. In fact, these two type has exactly the same definition except that they are in two different packages. This is OK even though you have to type a bit more and your code looks a bit longer than it should.
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 really confusing part comes when you have to convert the data objects. Here is the scenario. You first connect to a server using a low version of library, and then you find out that you can actually get the new properties in the newer version. Then you have to switch to the new library. The related ManagedObjectReference is also “cloned” to a new object with newer type. In the Web Service SDK 2.5, there is a sample code on this and got many people lost there including me initially.
With VI Java API 2.0, you don’t have this pain. One set of library kills all. There are however other things you need to watch out.
First, although you can specify the version of the target server when you new a ServiceInstance, you must know the version before you call it, or to play safe you just use the lowest version 2.0. When you use lower version, you won’t be able to get newer properties and call newer methods. To get accurate version, I have provided a utility code detecting the target version. The idea behind it is very simple, you just get the content of a well know URL, and parse out the version number.
Secondly, the API makes accessible all the properties and methods of the latest vSphere API in your application even your application is intended for an older version of servers. You, as the developer, have to check the availability of a property of a method against a particular version. The code still compiles no matter what but may get you problems in run time.
While I was presenting the API to our professional service team, I got a very good question which I should clarify here. Some of you may have known, the vSphere 4 not only adds more types, properties, and methods, but also changes the type inheritance hierarchy. The Network and Datastore, for example, becomes a subtype of ManagedEntity in vSphere 4. The VI Java 2.o reflects this change, but you should NOT call any methods or accessors of ManagedEntity while working with a Network or Datastore object on an older version of target server.