Home > vSphere API > Why vSphere PropertyCollector Is Hard By Design?

Why vSphere PropertyCollector Is Hard By Design?

January 18th, 2012 Leave a comment Go to comments

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.

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure


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.

  1. Guru
    January 18th, 2012 at 07:31 | #1

    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. January 19th, 2012 at 16:08 | #2

    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
    January 21st, 2012 at 06:29 | #3
  4. January 21st, 2012 at 11:59 | #4

    Thanks Guru!

  5. Guy
    April 28th, 2012 at 05:41 | #5


    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. April 28th, 2012 at 22:35 | #6

    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
    April 29th, 2012 at 01:09 | #7

    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.

  1. No trackbacks yet.