Home > vSphere API > Lightweight Caching Framework in vSphere Java API 2.0

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.

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


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:

package com.vmware.vim25.mo.samples;
import static com.vmware.vim.cf.NullObject.NULL;

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

import com.vmware.vim.cf.CacheInstance;
import com.vmware.vim25.VirtualMachineSummary;
import com.vmware.vim25.mo.Folder;
import com.vmware.vim25.mo.InventoryNavigator;
import com.vmware.vim25.mo.ManagedEntity;
import com.vmware.vim25.mo.ServiceInstance;

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);
    vicf.watch(vms, new String[] {"name", "runtime.powerState", "summary"});
    vicf.watch(hosts, 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.

Categories: vSphere API Tags: ,
  1. jcai
    April 29th, 2011 at 16:46 | #1

    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. April 29th, 2011 at 17:08 | #2

    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
    May 10th, 2012 at 09:38 | #3

    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. May 10th, 2012 at 10:45 | #4

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


  5. BS
    December 13th, 2016 at 15:05 | #5

    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?

  1. No trackbacks yet.