Lightweight Caching Framework in vSphere Java API 2.0

In vSphere Java API 2.0, I wrote a lightweight caching framework. It’s still experimental but has a great potential to greatly simplify your development work. Commercial companies already use it in their products.

The motivation behind this framework is simple – instead of keep polling the changes from the server side, you keep a local cache that is made as fresh as possible. The View in the vSphere Perl toolkit is one way to do. It caches all properties of a managed object despite the fact that you don’t need that many at all.

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 caching framework in vSphere Java API takes another approach. You tells it what managed objects and what properties you want to be cached. After that, the caching framework does its best to read the properties and keep them as fresh as possible.

Architecturally the caching framework is totally separated from the core of the API. You can take it away without any impact on the rest of the API. This is quite different from other toolkit.

Have enough introduction? Let’s take a look at sample code:

import static;

import java.text.SimpleDateFormat;
import java.util.Date;

import com.vmware.vim25.VirtualMachineSummary;

public class CacheFrameworkSample
  public static void main(String[] args) throws Exception
    ServiceInstance si = new ServiceInstance(new URL(""), "root", "password", true);
    Folder rootFolder = si.getRootFolder();
    ManagedEntity[] vms = new InventoryNavigator(rootFolder).searchManagedEntities("VirtualMachine");
    ManagedEntity[] hosts = new InventoryNavigator(rootFolder).searchManagedEntities("HostSystem");

    CacheInstance vicf = new CacheInstance(si);, new String[] {"name", "runtime.powerState", "summary"});, new String[] {"name", "summary"});

    //check if the caching is ready to use; otherwise wait

    Thread[] vrs = new VimReader[2];

    for(int i=0; i<1; i++)
        String name = (String) vicf.get(vms[i], "name");
        SimpleDateFormat sdf = new SimpleDateFormat();
        Object power = vicf.get(vms[i], "runtime.powerState");
        //show how to test the null value
        if(power==NULL) // or == NullObject.NULL
        	System.out.println("power is null");
        VirtualMachineSummary summary = (VirtualMachineSummary )vicf.get(vms[i], "summary");
        System.out.println(this.getName() + " reading vm: " + name + " = " + power + " @ " + sdf.format(new Date(System.currentTimeMillis())));//+ summary.getRuntime().getMaxMemoryUsage());

      for(int i=0; i<1; i++)
        String name = (String) vicf.get(hosts[i], "name");
        Object summary = vicf.get(hosts[i], "summary");
        System.out.println(this.getName() + " reading host: " + name + " = " + summary);

      } catch(Exception e)

As you see from the sample, it’s pretty easy. You first create a CacheInstance from a ServiceInstance, then you specify what managed objects and what properties to cache. You can add as many watch points as you want. In the end, you just call start() to let the caching framework take care of the rest.

When you application wants data, you just retrieve it as from a HashMap. The HashMap has two levels. The first level’s key is the managed object and value is another HashMap. The lower level HashMap has key as property name and value as the value of a property.

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


  1. jcai
    Posted April 29, 2011 at 4:46 pm | Permalink

    If I use this caching mechanism to watch property “childEntity” of manged object “Folder”, I’d assume the property value (an array) will change if a VM is added or deleted, right? But is it possible to know which VM is added or deleted?

  2. Posted April 29, 2011 at 5:08 pm | Permalink

    Hi Jay,
    Great question! The cached values are just snapshots of different properties. They don’t log down the history or delta. There is a chance to do so if you change the code to have a new subscriber to the change. The mechanism is not open at the moment, but may be so in the future.

  3. angelo
    Posted May 10, 2012 at 9:38 am | Permalink

    I would like to know if VMs, Hosts or Datastores are added or deleted. What would be the simplest and most efficient way of doing this? Is the cacheing mechanism the appropriate way of doing this?

  4. Posted May 10, 2012 at 10:45 am | Permalink

    Caching framework is not intended for this. To get what you want, I think it’s best to use events.


  5. BS
    Posted December 13, 2016 at 3:05 pm | Permalink

    I am currently using CacheInstnace framework to cache few config properties for all Virtual Machine Objects. But cache is not getting updated or providing all cached properties for newly added Virtual Machine objects.
    Is there a way to update the cache with newly created objects?

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__

    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.