VirtualBox’s Java SDK overview

VirtualBox is an excellent product, it helps you to create virtual machines on top of another machine using a hypervisor, it  gives you the ability to run multiple operating systems on the same machine, but yet not many people know about its SDK

VirtualBox has an SDK that can be used to interact with it as well as its virtual machines, DHCP etc.

it is pretty sad that such a great product has a very poor documentation with very few examples all over the internet, when you are trying to do something with it you will bump into with many non-trivial deductible considerations, below you will find a brief summary of what I learned when I was playing around with it as well as how I learned to decipher its cryptic documentation.

VirtualBox SDK basics

To download the SDK you will need to go here

ok, once you have it unzip it and you will find something like this

first nasty surprise, the SDK is packaged in a very odd fashion, anyway, what you should know about it is that there are two ways to communicate with the VirtualBox binaries XPCOM and web service, the only difference between those is the connection method, once the connection is established the same functions can be used, it is worth to mention that there are many clients available for the SDK like C, Java, Python, PHP etc, I only tried with Java but for the others the mechanism should be pretty much the same

Documentation

The SDK comes with 2 important pieces of documentation one is under

sdk/docs/SDKRef.pdf
sdk/bindings/webservice/java/jax-ws/vboxjws-doc.jar

the first option is the general documentation which has the description of every method and class in a more generic fashion, on the other hand, vboxjws-doc.jar contains the java documentation, you only need to decompress it

in case that you are interested, the source code of the Java driver is in

sdk/bindings/webservice/java/jax-ws/vboxjws-src.jar

it just need to be decompressed too

Establishing VirtualBox first connection

XPCOM 

it is a mechanism to allow inter-platform communication, this allows the client to talk to the VirtualBox binaries if you want to understand it deeper go here in this way, the communications happen locally, your code should be located on the same machine where VirtualBox is installed.

So far the XPCOM communication only worked for me on Linux OS because Windows does not have support for that, you need to add extra libraries which I don’t know where to get them from, so, I will suppose that you also are using  Linux too.

the XPCOM libraries are located within the unzipped file here:

sdk/bindings/xpcom/java/vboxjxpcom.jar

you just need to add it to your classpath and that’s it, to create the connection you should do something like

package ninja.donhk.vbox;

import org.virtualbox_5_2.*;

public class VBoxManager {

    static {
        System.setProperty("java.library.path", "libs/vboxjxpcom.jar");
        System.setProperty("vbox.home", "/usr/lib/virtualbox");
    }

    private final VirtualBoxManager boxManager;
    private final IVirtualBox vbox;

    public VBoxManager() {
        boxManager = VirtualBoxManager.createInstance(null);
        vbox = boxManager.getVBox();
    }

    public String getVBoxVersion() {
        return vbox.getVersion();
    }
}

notice

System.setProperty("java.library.path", "libs/vboxjxpcom.jar");
System.setProperty("vbox.home", "/usr/lib/virtualbox");

that is needed to let the JVM know from which place get the libraries and where are the VirtualBox binaries installed, another way to do so is using something like

java -Djava.library.path=libs/vboxjxpcom.jar -Dvbox.home=/usr/lib/virtualbox -jar myJar.jar

but I think the first way is cleaner and less error-prone, on the other hand, we have this

boxManager = VirtualBoxManager.createInstance(null);
vbox = boxManager.getVBox();

this is how we establish the connection, now if you call getVBoxVersion and it returns the version, congratulations you just did your hello world with this SDK

Web service

in this way, VirtualBox will have a listener with which we will interact sending the instructions from a client that can be in a remote location, the client can be on the same machine but it doesn’t make sense to use web services if you are on the same machine, in such case it would be better to stick with xpcom

before proceeding with the first connection, we need to start up the listener on the server side, do do, it is needed to execute

vboxwebsrv -H 0.0.0.0 -A null

-H sets the host to bind, the default is localhost and thus, if we don’t specify it, the service only will accept local connections

-A specifies the authentication method to be used, with null, we disable it

Note: if you don’t know where is vboxwebsrv, it will be in the bin directory of your VirtualBox installation, if you on Linux, after you installed VirtualBox it should already on your PATH, just execute vboxwebsrv -h to check it out

the expected output would be

once the server is already listening, we have to prepare the client, first, add the following libs to your classpath

sdk/bindings/webservice/java/jax-ws/vboxjws.jar

and the client will looks like

package ninja.donhk;

import org.virtualbox_5_2.*;

public class VBoxManager {

    private final VirtualBoxManager boxManager;
    private final IVirtualBox vbox;

    public VBoxManager() {
        boxManager = VirtualBoxManager.createInstance(null);
        boxManager.connect("http://192.168.15.11:18083", null, null);
        vbox = boxManager.getVBox();
    }

    public String getVBoxVersion() {
        return vbox.getVersion();
    }
}

In either way, after compile, you should expect something like this

VirtualBox programming concepts

Machine states

VirtualBox is a powerful tool but it is a complex beast, it is an environment where all the components are fighting for the resources at the same time, the first element to consider are the states that a VirtualMachine can have, they are described below

when you are manipulating the vm, you often need to lock it to prevent another process from changing it and leaving it in an inconsistent state

VirtualBoxManager

It is only allowed to have one instance of VirtualBoxManager at a time

Sample Java class to manage virtual machines

the code is really straightforward, I won’t go over each method to explain how it works, just those that are particularly interesting

Whenever a change is going to be done over a vm, it might require a lock and the lock depends on the type of operation that is being done, there are three types of locks, check out the documentation for more details

The launch method has a small hack 😉 which makes the code wait until the machines started up since there is no way to know when a machine finishing booting I added a code that waits until the machine gets an IP (which means that it can be accessed from the outside)

Live example

below is a sample of a project that I’m working (and of which I will create a post later) that uses this code as part of the backend

Before running this code make sure that you configured correctly the classpath, depending on the approach that you are taking will need to add the xpcom or the web service binding under the libs folder as mentioned above

full source code

.