Why vSphere PropertyCollector Is Hard By Design?

If you’ve had a chance to use vSphere Web Service SDK, you must know the PropertyCollector is very hard to use. It takes a newcomer quite some time to learn how to use it, and even more time to learn to use it effectively. Luckily, you no longer have to if you use the open source vSphere Java API (a.k.a. vijava) because it has encapsulated the PropertyCollector behind these newly added getter methods of the managed object types.

Still, a question has lingered in my mind for a while: “Why was the PropertyCollector designed to be hard?” If you have a similar question, this article is for you. Note that this is just my own thoughts. Hope it offers a good explanation, and more importantly you can learn from it for your future designs.

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.

Although vCenter and ESX/ESXi have implemented the same API interfaces, the vSphere API is mainly for vCenter and heavily influenced by vCenter. Functionality wise, vCenter supports almost all the APIs, while ESX/ESXi does part of them. It’s not strictly superset/subset relationship but pretty close.

As you know, the vCenter is built on top of relational databases, either Oracle or Microsoft SQL Server. With the vFabric Data Director and vPostgress, we can expect Postgress to be used. Why? According to Paul Maritz, you got to eat your own dog food.

So vCenter is a database centric application in server form. What does it really mean? At a high level, the managed object types are mapped to tables in the database; managed object instances to records; properties to fields. The ManagedObjectReference includes both type (table) and value (primary key). Secondly, different threads in vCenter share information via database.

With that in mind, the PropertyCollector is really an interface to the database retrieving different tables (managed object types) and their fields (properties). It’s very natural to design something like PropertyCollector, a single type that is responsible for getting all properties of all managed objects. Also with SOAP Web Services, it does not make much sense (check out the data transfer object design pattern) to provide numerous getters, each of which corresponds to a property.

While the single type making sense, the interface design can be improved however. The most common use case of PropertyCollector is to retrieve a property from a managed object. With the existing interfaces, you got to work with several data objects to specify what you want. It of course works but isn’t easy to use. Ideally it should have included a simple interface as follows:

Object getProperty(ManagedObjectReference obj, String propName)

This simple property retrieval is, however, not the most common usage of PropertyCollector in vSphere Client which has been the first and still the most important application built on top of vSphere API. This is yet another reason why the PropertyCollector is hard to use – its major application vSphere Client has different requirements that have been satisfied, therefore there hasn’t been enough incentives to improve the design.

Now, how to bridge the gap? I think the open source vSphere Java API has demonstrated a good approach. Should you be interested in how, you can check out the code. The architecture is designed so that other distributed system can leverage it as well. So you may still find it useful even if you are not using VMware vSphere.

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


  1. Guru
    Posted January 18, 2012 at 7:31 am | Permalink

    Though the property path can be passed to the searchManagedEntities to retrieve multiple properties of the interested object.The object contents retrieved cannot be not used at all.So,the end user of the API has to again call retrieveproperties function of the Propertycollectorutil function.Can we change the return value of Searchmanagedproperties to retrun a Map containing managed objects and hashtable(Containing teh object contents).

  2. Posted January 19, 2012 at 4:08 pm | Permalink

    Hi Guru, excellent point! I don’t recall why I did that way a while back. Please log either a bug or feature request in project home. Thanks!

  3. Guru
    Posted January 21, 2012 at 6:29 am | Permalink
  4. Posted January 21, 2012 at 11:59 am | Permalink

    Thanks Guru!

  5. Guy
    Posted April 28, 2012 at 5:41 am | Permalink


    I’m developing a vCenter plug-in in Python, but with using pyvisdk, which is another high-level API for vSphere Web SDK, that does all the PropertyCollector stuff.

    In my code, I need some properties of a host’s configuration (HostSystem.config), which are stored in data object HostConfigInfo (not managed).

    My problem is that fetching the entire HostConfigInfo takes time, and since I need only a small subset of it, I would like to fetch only what I need.

    So I started reading about this PropertyCollector, and from what I’m reading it works only on managed objects? That is, I can’t use this technique to have the vCenter travel inside HostConfigInfo and return only the properties that I’m interested in?

  6. Posted April 28, 2012 at 10:35 pm | Permalink

    Hi Guy,
    I am not familiar with the Python SDK you mentioned. But PropertyCollector itself does support what you look for. I have implemented this feature in VI Java API, check out the getPropertyByPath() method defined in the ManagedObject.java. To that method, you provide property path notation and get just what you need down the tree. Note that the path must not include any managedobjectreference type.
    BTW, you can use Jython for the Python language and high performance of vijava API.

  7. Guy
    Posted April 29, 2012 at 1:09 am | Permalink

    Hi Steve,

    Thanks for the info, I will check out the code.
    Also, I played with your proxy and saw that the vCenter client does this as well.
    Awesome tool, BTW.

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.