edu.ntnu.item.jt.VMware
Class GuestOS

java.lang.Object
  extended by edu.ntnu.item.jt.VMware.GuestOS

public class GuestOS
extends Object

Represents a Guest OS/Virtual Machine instance. Instances of GuestOS can only be gotten through a relevant VMwareServer, as a virtual machine always must be directly associated with a VMware server. The GuestOS is aware of its VMware server, but not vice versa. There is state associated with the virtual machine (GuestOS), but this is not reflected in the GuestOS class, as the underlying VIX API will return appropriate errors (which will be represented by exceptions here) if the state is wrong for a given call. Most functionality offered in this class utilizes in turn the VixInterface class and the C VIX API offered by VMWare.

Author:
Jøran Vagnby Lillesand

Field Summary
static String VIX_CONSOLE_USER_NAME
           
static int VIX_E_FILE_ALREADY_EXISTS
           
static long VIX_OK
           
static int VIX_PROPERTY_JOB_RESULT_HANDLE
           
static int VIX_PROPERTY_NONE
           
static int VIX_RUNPROGRAM_ACTIVATE_WINDOW
           
static int VIX_RUNPROGRAM_RETURN_IMMEDIATELY
           
static int VIX_SNAPSHOT_INCLUDE_MEMORY
           
static int VIX_VM_POWEROP_NORMAL
           
 
Constructor Summary
protected GuestOS(int[] vmHandle, String vmxPath, String username, String password, VMwareServer vmWareServer)
          Constructor for the GuestOS class.
 
Method Summary
 void copyFileFromGuest(String guestPathName, String hostPathName)
          Copy a file from the local machine (client) to the guest OS.
 void copyFileToGuest(String localPathName, String guestPathName)
          Copy a file to the guest OS.
protected  void finalize()
          Releases the vix handle of this guest OS, allowing vix to free up any resources locked by this VM.
 String getHost()
          Getter for the hostname of the VMware server running this guest OS.
 String getPassword()
          Getter for the password associated with this virtual machine.
 String getUsername()
          Getter for the username associated with this virtual machine.
 int getVMHandle()
          Not currently supported in VIX 1.0 and 1.1.
 String getvmxPath()
          Getter for the guest OS's VMX path.
 void loadSnapshot()
          Loads a previously stored snapshot.
 void login()
          Login to the guest OS.
 void logInGuiConsoleUser()
          Log in to the Guest OS with a GUI console user.
 void powerOff()
          Powers off the virtual machine.
 void powerOn(boolean waitForTools, int timeout)
          Powers on the virtual machine.
 void releaseJobHandle(int jobHandle)
          Releases the given job handle in the vix API.
 void revertToSnapshot(boolean waitForCompletion)
          Revert to the previous snapshot.
 void runProgramInGuest(String programPath, String commandLineArgs)
          Run a executable file in the guest OS.
 int runProgramInGuest(String programPath, String commandLineArgs, Callback callbackProc)
          Run a program in the guest OS using a callback procedure.
 void runProgramInGuestNonBlocking(String programPath, String commandLineArgs)
          Run a program in the guest OS without blocking call or any callback procedure.
 void takeSnapshot(String name, String description, boolean includeMemory)
          Take a snapshot of the current state in the virtual machine (guest OS).
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VIX_PROPERTY_NONE

public static final int VIX_PROPERTY_NONE
See Also:
Constant Field Values

VIX_OK

public static final long VIX_OK
See Also:
Constant Field Values

VIX_SNAPSHOT_INCLUDE_MEMORY

public static final int VIX_SNAPSHOT_INCLUDE_MEMORY
See Also:
Constant Field Values

VIX_PROPERTY_JOB_RESULT_HANDLE

public static final int VIX_PROPERTY_JOB_RESULT_HANDLE
See Also:
Constant Field Values

VIX_VM_POWEROP_NORMAL

public static final int VIX_VM_POWEROP_NORMAL
See Also:
Constant Field Values

VIX_E_FILE_ALREADY_EXISTS

public static final int VIX_E_FILE_ALREADY_EXISTS
See Also:
Constant Field Values

VIX_RUNPROGRAM_RETURN_IMMEDIATELY

public static final int VIX_RUNPROGRAM_RETURN_IMMEDIATELY
See Also:
Constant Field Values

VIX_RUNPROGRAM_ACTIVATE_WINDOW

public static final int VIX_RUNPROGRAM_ACTIVATE_WINDOW
See Also:
Constant Field Values

VIX_CONSOLE_USER_NAME

public static final String VIX_CONSOLE_USER_NAME
See Also:
Constant Field Values
Constructor Detail

GuestOS

protected GuestOS(int[] vmHandle,
                  String vmxPath,
                  String username,
                  String password,
                  VMwareServer vmWareServer)
Constructor for the GuestOS class. The constructor is protected, as guest OS's may only be returned via the appropriate VMwareServer object.

Parameters:
vmHandle - the Vix handle of this virtual machine.
vmxPath - the VMX config path of this virtual machine. The VMX path is valid on the VMware Server running this guest OS.
vmWareServer - reference to the VMware server running this guest OS instance.
username - username for logging in to the OS running at the virtual machine.
password - password for logging in to the OS running at the virtual machine. If no password is required, supply null.
Method Detail

powerOn

public void powerOn(boolean waitForTools,
                    int timeout)
             throws PowerUpFailureException
Powers on the virtual machine. If the virtual machine is already powered on, the function proceeds as normal (returns). The function can be instructed to wait for VMWare tools to respond in the guest OS. This can be done using a timeout which will be triggered if Tools does not respond within the given timeout.

Parameters:
waitForTools - specifies whether or not to wait for tools to run in the guest os.
timeout - specifies the timeout in seconds when waiting for tools. If waitForTools is false, this parameter is ignored.
Throws:
PowerUpFailureException - the only exception thrown. Contains a textual description of the error that occured.

powerOff

public void powerOff()
              throws PowerOffFailureException
Powers off the virtual machine.

Throws:
PowerOffFailureException - if an error occured while powering off the virtual machine.

login

public void login()
           throws LoginFailureException
Login to the guest OS. Note that it is required that the user account has an associated password (only verified for Win XP). If the virtual machine is not powered on, an exception will be thrown.

Throws:
LoginFailureException - indicates an error during logging in. Contains a textual description of the error.

copyFileToGuest

public void copyFileToGuest(String localPathName,
                            String guestPathName)
                     throws FileCopyException
Copy a file to the guest OS. Note that the file is copied from the client running the code (this code), not the VMWare host. The call blocks until file transfer is completed.

Parameters:
localPathName - full path of the local file.
guestPathName - full path of the destination file on the guest OS.
Throws:
FileCopyException - thrown if an error occurs during copying of the file. Includes a textual representation of the error.

copyFileFromGuest

public void copyFileFromGuest(String guestPathName,
                              String hostPathName)
                       throws FileCopyException
Copy a file from the local machine (client) to the guest OS. The call blocks until file transfer is completed.

Parameters:
guestPathName - file name of the file in the guest OS.
hostPathName - file name of destination file in the local machine.
Throws:
FileCopyException - thrown if an error occurs during copying of the file. Includes a textual representation of the error.

runProgramInGuest

public void runProgramInGuest(String programPath,
                              String commandLineArgs)
                       throws FileExecutionException
Run a executable file in the guest OS. In order to read from the program's stdout stream, pipe the output to a file using arguments and copy this file using the copyFileFromGuest function: guestOS.runProgramInGuest("/bin/ls", "/bin > /tmp/ls.out"); guestOs.copyFileFromGuest("/tmp/ls.out", "c:\\ls.out");

Parameters:
programPath - full path of the program to be executed.
commandLineArgs - command line arguments to be supplied to the executable.
Throws:
FileExecutionException - thrown if an error occured when executing the file.

logInGuiConsoleUser

public void logInGuiConsoleUser()
                         throws LoginFailureException
Log in to the Guest OS with a GUI console user. This causes running programs to be visible when the logging in to the VM using the console. The program is run within the context of the user stated in the previous log in operation.

Throws:
LoginFailureException - If the log in operation fails

runProgramInGuestNonBlocking

public void runProgramInGuestNonBlocking(String programPath,
                                         String commandLineArgs)
                                  throws FileExecutionException
Run a program in the guest OS without blocking call or any callback procedure. NB! When using this method, there is no way to evaluate the result status code of the call!

Parameters:
programPath - Path to the program to be executed
commandLineArgs - any command line arguments
Throws:
FileExecutionException

runProgramInGuest

public int runProgramInGuest(String programPath,
                             String commandLineArgs,
                             Callback callbackProc)
Run a program in the guest OS using a callback procedure. The callback procedure will be called upon finishing the operation. Note that to ensure that the program has finished executing the callback procedure class should be polled.

Parameters:
programPath - path to the program to be executed.
commandLineArgs - any command line arguments to be passed to the program.
callbackProc - class containing the callback procedure.
Returns:
job handle of the job (needed to free up the resources allocated by vix when executing the program).

takeSnapshot

public void takeSnapshot(String name,
                         String description,
                         boolean includeMemory)
                  throws CreateSnapshotException
Take a snapshot of the current state in the virtual machine (guest OS). May also include the current state of the memory in the guest. Note that this implementation is written for VMWare server, which only supports one snapshot at the time. This means that if a new snapshot is taken, any previously stored one will be overwritten.

Parameters:
name - a name describing the snapshot. Only used for description, so need not be unique.
description - a textual description of the snapshot.
includeMemory - indicates whether the memory state is to be part of the snapshot.
Throws:
CreateSnapshotException - an error occured while trying to create the snapshot. See the textual description and/or the exception error code for more information.

revertToSnapshot

public void revertToSnapshot(boolean waitForCompletion)
                      throws NoSnapshotLoadedException,
                             RevertToSnapshotFailedException,
                             NoSnapshotAvailableException
Revert to the previous snapshot. First attempts to load the snapshot, and the reverts to it.

Throws:
NoSnapshotLoadedException - indicates that no snapshot has been loaded prior to calling the function.
RevertToSnapshotFailedException - indicates that an error occured while attempting to revert to the loaded snapshot. For information about the error, see the exception's textual description or error code.
NoSnapshotAvailableException - no snapshot could be loaded, indicating that no snapshot is available.

loadSnapshot

public void loadSnapshot()
                  throws NoSnapshotLoadedException,
                         NoSnapshotAvailableException
Loads a previously stored snapshot. Does not perform any changes to the VM, but loads the handle of the snapshot

Throws:
NoSnapshotLoadedException
NoSnapshotAvailableException

releaseJobHandle

public void releaseJobHandle(int jobHandle)
Releases the given job handle in the vix API.

Parameters:
jobHandle - id of the job handle to be released.

getVMHandle

public int getVMHandle()
Not currently supported in VIX 1.0 and 1.1. public void createDirectory(String directory) throws DirectoryCreationException{ log(LOG_INFO, "Creating directory: "+directory); int jobHandle = vixLib.VixVM_CreateDirectoryInGuest(vmHandle[0], directory, VIX_PROPERTY_NONE, null, null); long result = vixLib.VixJob_Wait(jobHandle, VIX_PROPERTY_NONE, null, VIX_PROPERTY_NONE); if(result == VIX_E_FILE_ALREADY_EXISTS){ // Do nothing. Directory exist - no problem for this usage. log(LOG_INFO, "Directory already exists."); vixLib.Vix_ReleaseHandle(jobHandle); return; }else if(result != VIX_OK){ // Creating directory failed. vixLib.Vix_ReleaseHandle(jobHandle); log(LOG_WARNING, "Directory creation failed. Error code: "+result+". Error description: "+vixLib.Vix_GetErrorText(result, null)); throw new DirectoryCreationException(vixLib.Vix_GetErrorText(result, null), result); } }


getvmxPath

public String getvmxPath()
Getter for the guest OS's VMX path.

Returns:
vmx path of the guest OS.

getHost

public String getHost()
Getter for the hostname of the VMware server running this guest OS.

Returns:
hostname of the VMware server hosting the guest OS.

getUsername

public String getUsername()
Getter for the username associated with this virtual machine.

Returns:
username associated with the virtual machine OS.

getPassword

public String getPassword()
Getter for the password associated with this virtual machine.

Returns:
password associated with the virtual machine OS.

finalize

protected void finalize()
Releases the vix handle of this guest OS, allowing vix to free up any resources locked by this VM.

Overrides:
finalize in class Object