DoubleCloud.org

One of the most common confusions that a newcomer has while learning vSphere API is the ManagedObjectReference, a.k.a MOR. If you read the API Reference, you will find a lot of them. Recently there was a question poping in the open source VIJava API forum. So I think it is worth explaining it here.

There are two major types in the vSphere API: managed object types are for these objects on the server side only; and data object types for properties, parameters, and results, which can be send back and forth between client and server. The MOR is a data object type, but used to represent managed objects living on server side. If you are familiar with C/C++ programming, you can think of it as pointer in some sense. Even better, think of it as a combination of table and primary key in relational database. I will explain it more soon.

The MOR has two properties: type and val, both are strings. The reason for it having type is that there are close to 100 managed object types but only one MOR for all of them. To distinguish them, type is therefore used and its value is limited to available types which are 93 in vSphere 4.1.

The val is the unique identifier for a managed object within a target server. For the same managed object, say a virtual machine, the val can be different when you get it from an ESX/ESXi or the vCenter that manages the ESX/ESXi. Now, let’s get back to the relational database analog just mentioned, the type is the “table” and val is the “primary key.”

Too abstract? Let’s take a look at a sample. A MOR representing a virtual machine may look like this:

type: VirtualMachine
val: vm-820

Once we are clear with MOR, let’s take a look at the ManagedObject. To your surprise, there isn’t a managed object type called ManagedObject in vSphere API reference. As a side story, I told one of my colleagues about this in a meeting and his response was, “I can’t believe it! I got to look it up and show you.” He never gets back to me afterwards.

If you use VI Java API, you do see a type/class ManagedObject which packs quite some code. It’s super class for every managed object types like HostSystem, VirtualMachine, etc. The main reason I added it to the VI Java API is for logical completeness of the object model. When logical, a nice object model comes naturally. From the implementation perspective, it does pull up much code for re-use across different subclasses.

With ManagedObject and its subtypes in VI Java API, you will have objects to work with and write much less code. Even nicer, you have all the typing in place. Before you can have a MOR object pointing to a virtual machine or a host, you mix them up and the compiler won’t catch the mistake. In VI Java API, there are VirtualMachine and HostSystem objects and you simply cannot confuse them or the compiler won’t let you go.

I am sure you all want the benefits of using VI Java API, but still wonder if there is a big performance difference between using MOR and ManagedObject (mainly its subtypes). In theory, there is a difference; in practice, you won’t notice any difference caused by this because the ManagedObject is a VERY thin layer. In fact, you will see 10 times performance boost using VI Java 2.0 because of the new Web Service engine I wrote from scratch.

Well, by this far I hope you understand well the MOR and ManagedObject. When using VI Java API, however, please avoid MOR as much as possible. Instead, use ManagedObject and its subtypes.