Introduction

Agaetis VMWare API is just a wrapper of the VIX API (which is a C++ API) in Java. The VIX API of VMWare allows you to control a VMWare Virtual Machine. That means to run, revert, stop, snapshot a VMWare virtual machine. The only problem was that the VIX API is written in C++ and consequently is not directly usable by a Java program. To solve this little gap there is a Java library called JNA . This latter allows to use shared library from your java code. It does the same thing as JNI but it's easier to use.

Install the VIX API

First, you need to install the vix api on the computer where you want to use the Agaetis VMWare API. To download it please go to http://www.vmware.com/support/developer/vix-api/.

Without this api installed on the computer, the Agaetis VMWare API won't work because it relies heavily on it. If you don't have a vmware account you will need to create one in order to download the VIX API. If you already use VMWare Server 1.x or 2.x or even Workstation, then you know what I'm speaking about. Otherwise, you should know that it's free and really quick to subscribe.

Use the Agaetis VMWare API

To be able to use all functionalities from the API, you need to download the jar file and to put it in the classpath of your application. Here are the link to download it (you can download it directly from our nexus repository) :

- from Agaetis Nexus Repo : click here .
- from Sourceforge.net : click here .
NB : don't forget to put it in the CLASSPATH of your application !!!

Basics

Everything is ready, let's try to see how it works. The API needs to know where is the VIX shared library. So before any calls to the Agaetis API, we need to provide VIX library location to JNA. This location is easy to find if you remember where you installed the VIX library in the second point of this documentation. By default it's located in "/usr/lib/vmware-vix/lib/ for Linux system and in " C:\Program Files\VMWare\VMWare VIX\" for Windows. If in those folders you can find a file called libvixAllProducts.so (Linux) or vix.dll (Windows), then it's the folder you were looking for and that will tell to JNA where the shared libraries are located. It behaves a bit like a classpath for JNA.

You can notice that there are different folders where you can find Vix libraries. All are specific to a VMWare product. If you use a VMWare Server 2 to run the virtual machine you want to connect to, all necessary libraries are in the "VMWARE VIX FOLDER/VIServer-2.0.0/32bit" folder. If you use a VMWare Server 1.0 then they should be in "VMWARE VIX FOLDER/server-1/32bit".

So, to avoid problems of dependency you need to declare the folder in the library path of your system. For instance if you installed the VIX API in "C:\Program Files\VMWare\VMWare Vix\" in a Windows platform, and you want to connect to vm's hosted by VMWare Server 2, then you need to add to the PATH environment variable "C:\Program Files\VMWare\VMWare Vix\VIServer-2.0.0\32bit". If you are under Linux then you should set the LD_LIBRARY_PATH the same way. If this is not done then you can expect some Unsatisfied Link Exception at runtime. If you are under linux you can always create symbolic link if you have such exception.

So before any calls to the Agaetis VMWare API you should set this location by using the static mehod VixLibrary.setLibraryPath() . here is an example : 

VixLibrary.setLibraryPath("/usr/lib/vmware-vix/lib/");
JNA is ready to call shared library functions. Now we need to define a host where to connect. This host must run a VMWare Server with at least one virtual machine. This is the java code to define a host (VixHost) : 
VixHost vhost = new VixHost();
vhost.setPort(0);
vhost.setHost("https://localhost:8333/sdk");
vhost.setUsername("username");
vhost.setPassword("password");
vhost.setServiceProvider(Vix.ServiceProvider.VMWARE_VI_SERVER);
In this code we instantiate a VixHost object which represents the host. It needs the port used, the address where VMWare Server is running, the username for the virtual machine you want to connect to and the password for this username. The last line tells what kind of VMWare Server you are connecting to. Actually, this last parameter is really important. If you know that you'll connect to a VMWare Server 1.x then the port, the host and the service provider parameter must be different. It happens because VMWare Server 1.x doesn't have use the same protocol to communicate. So here is a sample when you want to connect to a VMWare Server 1.x : 
VixHost vhost = new VixHost();
vhost.setPort(902);
vhost.setHost("192.168.0.23");
vhost.setUsername("username");
vhost.setPassword("password");
vhost.setServiceProvider(Vix.ServiceProvider.VMWARE_SERVER);
In this code we must define the port 902, which is the default port of VMWare Server 1.x. We must set as host address an IP address. The username and the password definition is the same. The last difference is in the service provider type. As the server you want to connect in this sample is a version 1.x, you must set the server provider type to VMWARE_SERVER.

If you connect to a VMWare Server 2.x then you can use the first example. You can notice that the host in this sample is a bit weird. VMWare Server 2.x use the http protocol for remote control of virtual machines. Because of that you don't have to specify a specific port with the VixHost.setPort() method. Just use the value 0 like written above. URL used as argument for the VixHost.setHost method must have this form "protocol://hostname:port/sdk". First the protocol used can be either http or https. The hostname may be an IP address or a hostname known by the dns server or mentioned in the host file. The port is by default 8333 but could be different according to how the VMWare Server was installed. The last part "sdk" must be present (Don't ask me why ....).

Last thing : the service provider can be also Vix.ServerProvider.WORKSTATION if the remote virtual machine is hosted by VMWare Workstation.

Now the host is defined correctly according to the remote version of VMWare Server, we can connect ! (you must say "at last !"). In order to do that we must use the VixHost.connect() method. This method take no argument and just perform a connection. If everything goes fine, you'll go to the next instruction otherwise you may have an exception thrown.

The next step is to open a virtual machine on this server. To open it does not mean to run it. It just allows to instantiate a VixVM object that will encapsulate all the commands for the virtual machine. Here is an example : 
 VixVM myVM = vhost.open("[standard] Virtual Machine/Virtual Machine.vmx");
The string in parameter for this method can also change according to the version of the server you are connecting to. In this example it takes the datastore path format. The first part of the string is the datastore name (by default it's standard). This value is surrounded by square brackets. The second part is the relative path to the datastore of the virtual machine configuration file. You must know it if you want to use any virtual machine on a VMWare Server 2.x or Workstation.

If you the server you will connect to is a VMWare Server version 1.x then this path is quietly different. For this version it only needs the absolute path of the configuration file (vmx file) of the virtual machine you want to take control of. So if you use vhost.setServiceProvider(Vix.ServiceProvider.VMWARE_SERVER); to initialize your host then here is an example to open a virtual machine. 
VixVM myVM = vhost.open("/home/me/vmware/Virtual Machine/Virtual Machine.vmx");
Now with this object you can perform different operations. for instance you can check if the virtual machine is already on : 
if (myVM.isOn()) { ... }
Or you can run the vm by running : 
myVM.powerOn();
There is also a myVM.powerOff() method to switch off the virtual machine.

Conclusion

So it was a little explanation of the Agaetis VMWare API. Feel free to read the javadoc. You should find other methods to play with for virtual machines. Enjoy !!