Easy VMware Development with VI Java API and Groovy


Have you ever wanted to write a script or an application that automates your VMware VI3.x / vSphere environment, but lack the development skills to do so?  Or, maybe you have development skills, but you’re looking for ways to simplify your code and improve your productivity?  In either case, I’ve stumbled across something you’ll definitely want to check out.

Before we start, I should probably clarify something.  If you have zero development experience, then the title of this post could be a little misleading.  An absolute beginner probably wouldn’t consider this “easy.”  There are certainly easier ways to develop VMware scripts which are targeted at VMware Administrators, such as the vSphere PowerCLI.  And if you want to do some VMware scripting without learning a programming language and/or acquiring some development skills, then you should stop reading now and go check out the vSphere PowerCLI.  However, if you’re a little adventurous and want a “fast track” for creating VMware applications, then by all means, read on.

OK, with that out of the way, let’s start by talking about the first of two technologies we’re going to be working with, that is the VI (vSphere) Java API. This API isn’t actually an official VMware API available for download.  Rather, it’s a VMware sponsored open source project created by Steve Jin, a VMware engineer and author of VMware VI and vSphere SDK.  Now, if you look at the download page, you’ll see VMware already has the VMware vSphere Java SDK.  So this immediately begs the question, why would we want to bother with Steve’s open source VI Java API when VMware already provides a way for Java developers to create applications for vSphere?  Well, I’ll let Steve answer this question.  From his FAQ …

If you are using Java to develop applications talking to VMware Infrastructure (vSphere), this API is for you. Using this API instead of the VI SDK web services interfaces results in significantly less lines of code, much faster, and much more readable code.

That sounds pretty good to me.  I don’t like writing a lot of unnecessary code.  So I started tinkering around with Steve’s VI Java API a few weeks ago and I have to say, I’m very impressed (and if you look at the long list of testimonials, you’ll see I’m certainly not the only one either).   But while Steve is true to his word — this API really is fast and absolutely reduces the overall code required from a VI perspective — the Java language itself is fairly chatty.  Let’s face it, for many reasons Java has never been accused of being an easy language to master.  And I think one big reason is that it often requires many lines of code for even the most basic of tasks.  So it wasn’t long after I began working with the VI Java API that I looked to see if I could instead use my new favorite programming language, Groovy.

Despite its fairly young age, Groovy is gaining significant traction because it is a programming language that is agile, dynamic and was created for the powerful Java Virtual Machine (JVM).  If you’re a Java developer, a very cool thing about the language is that it is very Java friendly.  Meaning, more often than not, valid Java code is also valid Groovy code.  So you can start using Groovy right away wile keeping the learning curve gradual.  But you’ll quickly find that Java code rewritten as pure Groovy code is much more concise and readable because Groovy reduces various aspects of Java’s complexity and “noise.”  Let me show you an example of this.  The following example comes from Dr. Paul King’s (co-author of Groovy in Action) fantastic Groovy tutorial

This is both valid Java and valid Groovy code.

This is Groovy code which is functionally equivalent.


See what I mean?  Call me crazy, but I’ll take the latter.

OK great.  But can we combine the power of the VI Java API with the power of Groovy?  As it turns out, not only is it possible, but it’s actually quick and easy to setup.  All you have to do is take the two .jar files that make up the VI Java API and place them in the ~/.groovy/lib directory (or any other directory you’ve told Groovy looks for .jar files).

Now let’s take a look at another example.  This time let’s look at code that was explicitly written to show off the VI Java API.  The following graphic is a screenshot of HelloVM.java which is one of many sample code files that are available for you to check out.  It’s just a simple little Java app that will query vCenter (or an ESX host) and display the VMs, their OS and whether or not multiple snapshots are supported.



Like I said earlier, most Java code is valid Groovy code and this HelloVM.java is no exception.  It will run properly when executed as Java code and when executed as Groovy code.  But I’ve rewritten the code as pure Groovy code (intentionally leaving out all the legal mumbojumo at the top) …

import java.net.URL
import com.vmware.vim25.*
import com.vmware.vim25.mo.*
def start = System.currentTimeMillis()
def si = new ServiceInstance(new URL("https://<ip address of vCenter or ESX>/sdk"), "administrator",
     "password", true)
def end = System.currentTimeMillis()
println "time taken: " + (end-start)
def rootFolder = si.getRootFolder()
def name = rootFolder.getName()
println "root: " + name
def mes = new InventoryNavigator(rootFolder).searchManagedEntities("VirtualMachine")
mes.each {
    println "\nHello " + it.getName()
    println "GustOS: " + it.getConfig().getGuestFullName()
    println "Multiple snapshots supported?: " + it.getCapability().isMultipleSnapshotsSupported()

Taking the code above, changing the IP address and password, saving it as HelloVM.groovy and then running groovy HelloVM.groovy from the command line yields the following on my system …

time taken:  2774
root:  Datacenters

Hello VMware Capacity IQ
GustOS:  Red Hat Enterprise Linux 5 (32-bit)
Multiple snapshots supported?: true

Hello vSphere Management Assistant
GustOS:  Red Hat Enterprise Linux 5 (64-bit)
Multiple snapshots supported?: true

Hello cincylab-vc2
GustOS:  Microsoft Windows Server 2003, Standard Edition (32-bit)
Multiple snapshots supported?: true


Pretty cool eh?  So, how do you get started?  Here is what you’ll need to get up and running quickly …

  1. Download and setup Java properly for your system
  2. Download and setup Groovy for your system
  3. Download the VI Java API
  4. Unzip the VI Java API package and place the two .jar files in you ~/.groovy/lib directory
  5. Take a look at Dr. Paul King’s Groovy tutorial (or just do a Google search and find one that suits you)
  6. Read Steve Jin’s VI Java API Tutorial
  7. Have fun 🙂

Now, if you already know a thing or two about Groovy, then you’re probably already thinking that you could use Grails to quickly stand up vSphere web apps … and you’d be right 🙂   I’ll write about that next.  Hopefully it won’t take me another two months to do it!

Good luck and please feel free to let me know your thoughts / questions /concerns about the VI Java API and Groovy.


  1. org.codehaus.groovy.runtime.typehandling.GroovyCastException: Cannot cast object '…' with class 'java.lang.String' to class 'java.net.URL'

    1. def si = new ServiceInstance(“https://ipAddress/sdk”.toURL(), “administrator”, “password”, true)


      def si = new ServiceInstance(new URL(“https://ipAddress/sdk”), “administrator”, “password”, true)

  2. I have one datacenter(DC), 2 ESX servers(ESX-1 and ESX-2), and 4 VM instances(vm1, vm2, vm3, vm4).
    vm1 and vm2 are in ESX-1 and vm3 and vm4 are in ESX-2, Both ESX-1 and ESX-2 are in DC.

    Usning the following VIJava API cmd we can get all VM instance information in a DataCenter.
    “ManagedEntity[] vms = new InventoryNavigator(rootFolder).searchManagedEntities(new String[][] { {“VirtualMachine”, “name” }, }, true);”

    Usning the following VIJava API cmd we can get all Hosts information in a DataCenter.
    “ManagedEntity[] hosts = new InventoryNavigator(rootFolder).searchManagedEntities(new String[][] { {“HostSystem”, “name” }, }, true);”

    My question is I have vm1 VirualMachine obj, how can i get this vm HostIP(I mean ESX-1 IP)??

Comments are closed.