org.libvirt
Class VirDomain

java.lang.Object
  extended by org.libvirt.VirDomain

public class VirDomain
extends java.lang.Object


Method Summary
 void attachDevice(java.lang.String xmlDesc)
          Creates a virtual device attachment to backend.
 VirDomainBlockStats blockStats(java.lang.String path)
          Returns block device (disk) stats for block devices attached to this domain.
 void coreDump(java.lang.String to, int flags)
          Dumps the core of this domain on a given file for analysis.
 void create()
          Launches this defined domain.
 void destroy()
          Destroys this domain object.
 void detachDevice(java.lang.String xmlDesc)
          Destroys a virtual device attachment to backend.
 void free()
          Frees this domain object.
 boolean getAutostart()
          Provides a boolean value indicating whether the network is configured to be automatically started when the host machine boots.
 VirConnect getConnect()
          Provides the connection object associated with a domain.
 int getID()
          Gets the hypervisor ID number for the domain
 VirDomainInfo getInfo()
          Extract information about a domain.
 long getMaxMemory()
          Retrieve the maximum amount of physical memory allocated to a domain.
 int getMaxVcpus()
          Provides the maximum number of virtual CPUs supported for the guest VM.
 java.lang.String getName()
          Gets the public name for this domain
 java.lang.String getOSType()
          Gets the type of domain operation system.
 VirSchedParameter[] getSchedulerParameters()
          Gets the scheduler parameters.
 java.lang.String[] getSchedulerType()
          Gets the scheduler type.
 int[] getUUID()
          Get the UUID for this domain.
 java.lang.String getUUIDString()
          Gets the UUID for this domain as string.
 int[] getVcpusCpuMaps()
          Returns the cpumaps for this domain Only the lower 8 bits of each int in the array contain information.
 VirVcpuInfo[] getVcpusInfo()
          Extracts information about virtual CPUs of this domain
 java.lang.String getXMLDesc(int flags)
          Provides an XML description of the domain.
 VirDomainInterfaceStats interfaceStats(java.lang.String path)
          Returns network interface stats for interfaces attached to this domain.
 VirDomain migrate(VirConnect dconn, long flags, java.lang.String dname, java.lang.String uri, long bandwidth)
          Migrate this domain object from its current host to the destination host given by dconn (a connection to the destination host).
 void pinVcpu(int vcpu, int[] cpumap)
          Dynamically changes the real CPUs which can be allocated to a virtual CPU.
 void reboot(int flags)
          Reboot this domain, the domain object is still usable there after but the domain OS is being stopped for a restart.
 void resume()
          Resume this suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain().
 void save(java.lang.String to)
          Suspends this domain and saves its memory contents to a file on disk.
 void setAutostart(boolean autostart)
          Configures the network to be automatically started when the host machine boots.
 void setMaxMemory(long memory)
          * Dynamically change the maximum amount of physical memory allocated to a domain.
 void setMemory(long memory)
          Dynamically changes the target amount of physical memory allocated to this domain.
 void setSchedulerParameters(VirSchedParameter[] params)
          Changes the scheduler parameters
 void setVcpus(int nvcpus)
          Dynamically changes the number of virtual CPUs used by this domain.
 void shutdown()
          Shuts down this domain, the domain object is still usable there after but the domain OS is being stopped.
 void suspend()
          Suspends this active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated.
 void undefine()
          undefines this domain but does not stop it if it is running
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getXMLDesc

public java.lang.String getXMLDesc(int flags)
                            throws LibvirtException
Provides an XML description of the domain. The description may be reused later to relaunch the domain with createLinux().

Parameters:
flags - not used
Returns:
the XML description String
Throws:
LibvirtException
See Also:
The XML Description format

getAutostart

public boolean getAutostart()
                     throws LibvirtException
Provides a boolean value indicating whether the network is configured to be automatically started when the host machine boots.

Returns:
the result
Throws:
LibvirtException

setAutostart

public void setAutostart(boolean autostart)
                  throws LibvirtException
Configures the network to be automatically started when the host machine boots.

Parameters:
autostart -
Throws:
LibvirtException

getConnect

public VirConnect getConnect()
Provides the connection object associated with a domain.

Returns:
the VirConnect object

getID

public int getID()
          throws LibvirtException
Gets the hypervisor ID number for the domain

Returns:
the hypervisor ID
Throws:
LibvirtException

getInfo

public VirDomainInfo getInfo()
                      throws LibvirtException
Extract information about a domain. Note that if the connection used to get the domain is limited only a partial set of the information can be extracted.

Returns:
a VirDomainInfo object describing this domain
Throws:
LibvirtException

getMaxMemory

public long getMaxMemory()
                  throws LibvirtException
Retrieve the maximum amount of physical memory allocated to a domain.

Returns:
the memory in kilobytes
Throws:
LibvirtException

setMaxMemory

public void setMaxMemory(long memory)
                  throws LibvirtException
* Dynamically change the maximum amount of physical memory allocated to a domain. This function requires priviledged access to the hypervisor.

Parameters:
memory - the amount memory in kilobytes
Throws:
LibvirtException

getMaxVcpus

public int getMaxVcpus()
                throws LibvirtException
Provides the maximum number of virtual CPUs supported for the guest VM. If the guest is inactive, this is basically the same as virConnectGetMaxVcpus. If the guest is running this will reflect the maximum number of virtual CPUs the guest was booted with.

Returns:
the number of VCPUs
Throws:
LibvirtException

getName

public java.lang.String getName()
                         throws LibvirtException
Gets the public name for this domain

Returns:
the name
Throws:
LibvirtException

getOSType

public java.lang.String getOSType()
                           throws LibvirtException
Gets the type of domain operation system.

Returns:
the type
Throws:
LibvirtException

getSchedulerParameters

public VirSchedParameter[] getSchedulerParameters()
                                           throws LibvirtException
Gets the scheduler parameters.

Returns:
an array of VirSchedParameter objects
Throws:
LibvirtException

setSchedulerParameters

public void setSchedulerParameters(VirSchedParameter[] params)
                            throws LibvirtException
Changes the scheduler parameters

Parameters:
params - an array of VirSchedParameter objects to be changed
Throws:
LibvirtException

getSchedulerType

public java.lang.String[] getSchedulerType()
                                    throws LibvirtException
Gets the scheduler type.

Returns:
the type of the scheduler
Throws:
LibvirtException

getUUID

public int[] getUUID()
              throws LibvirtException
Get the UUID for this domain.

Returns:
the UUID as an unpacked int array
Throws:
LibvirtException
See Also:

getUUIDString

public java.lang.String getUUIDString()
                               throws LibvirtException
Gets the UUID for this domain as string.

Returns:
the UUID in canonical String format
Throws:
LibvirtException
See Also:

getVcpusInfo

public VirVcpuInfo[] getVcpusInfo()
                           throws LibvirtException
Extracts information about virtual CPUs of this domain

Returns:
an array of VirVcpuInfo object describing the VCPUs
Throws:
LibvirtException

getVcpusCpuMaps

public int[] getVcpusCpuMaps()
                      throws LibvirtException
Returns the cpumaps for this domain Only the lower 8 bits of each int in the array contain information.

Returns:
a bitmap of real CPUs for all vcpus of this domain
Throws:
LibvirtException

pinVcpu

public void pinVcpu(int vcpu,
                    int[] cpumap)
             throws LibvirtException
Dynamically changes the real CPUs which can be allocated to a virtual CPU. This function requires priviledged access to the hypervisor.

Parameters:
vcpu - virtual cpu number
cpumap - bit map of real CPUs represented by the the lower 8 bits of each int in the array. Each bit set to 1 means that corresponding CPU is usable. Bytes are stored in little-endian order: CPU0-7, 8-15... In each byte, lowest CPU number is least significant bit.
Throws:
LibvirtException

setVcpus

public void setVcpus(int nvcpus)
              throws LibvirtException
Dynamically changes the number of virtual CPUs used by this domain. Note that this call may fail if the underlying virtualization hypervisor does not support it or if growing the number is arbitrary limited. This function requires priviledged access to the hypervisor.

Parameters:
nvcpus - the new number of virtual CPUs for this domain
Throws:
LibvirtException

attachDevice

public void attachDevice(java.lang.String xmlDesc)
                  throws LibvirtException
Creates a virtual device attachment to backend.

Parameters:
xmlDesc - XML description of one device
Throws:
LibvirtException

detachDevice

public void detachDevice(java.lang.String xmlDesc)
                  throws LibvirtException
Destroys a virtual device attachment to backend.

Parameters:
xmlDesc - XML description of one device
Throws:
LibvirtException

blockStats

public VirDomainBlockStats blockStats(java.lang.String path)
                               throws LibvirtException
Returns block device (disk) stats for block devices attached to this domain. The path parameter is the name of the block device. Get this by calling virDomainGetXMLDesc and finding the attribute within //domain/devices/disk. (For example, "xvda"). Domains may have more than one block device. To get stats for each you should make multiple calls to this function. Individual fields within the VirDomainBlockStats object may be returned as -1, which indicates that the hypervisor does not support that particular statistic.

Parameters:
path - path to the block device
Returns:
the statistics in a VirDomainBlockStats object
Throws:
LibvirtException

interfaceStats

public VirDomainInterfaceStats interfaceStats(java.lang.String path)
                                       throws LibvirtException
Returns network interface stats for interfaces attached to this domain. The path parameter is the name of the network interface. Domains may have more than network interface. To get stats for each you should make multiple calls to this function. Individual fields within the VirDomainInterfaceStats object may be returned as -1, which indicates that the hypervisor does not support that particular statistic.

Parameters:
path - path to the interface
Returns:
the statistics in a VirDomainInterfaceStats object
Throws:
LibvirtException

coreDump

public void coreDump(java.lang.String to,
                     int flags)
              throws LibvirtException
Dumps the core of this domain on a given file for analysis. Note that for remote Xen Daemon the file path will be interpreted in the remote host.

Parameters:
to - path for the core file
flags - extra flags, currently unused
Throws:
LibvirtException

create

public void create()
            throws LibvirtException
Launches this defined domain. If the call succeed the domain moves from the defined to the running domains pools.

Throws:
LibvirtException

destroy

public void destroy()
             throws LibvirtException
Destroys this domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor. The data structure is freed and should not be used thereafter if the call does not return an error. This function may requires priviledged access

Throws:
LibvirtException

free

public void free()
          throws LibvirtException
Frees this domain object. The running instance is kept alive. The data structure is freed and should not be used thereafter.

Throws:
LibvirtException

migrate

public VirDomain migrate(VirConnect dconn,
                         long flags,
                         java.lang.String dname,
                         java.lang.String uri,
                         long bandwidth)
                  throws LibvirtException
Migrate this domain object from its current host to the destination host given by dconn (a connection to the destination host). Flags may be one of more of the following: VirDomain.VIR_MIGRATE_LIVE Attempt a live migration. If a hypervisor supports renaming domains during migration, then you may set the dname parameter to the new name (otherwise it keeps the same name). If this is not supported by the hypervisor, dname must be NULL or else you will get an error. Since typically the two hypervisors connect directly to each other in order to perform the migration, you may need to specify a path from the source to the destination. This is the purpose of the uri parameter. If uri is NULL, then libvirt will try to find the best method. Uri may specify the hostname or IP address of the destination host as seen from the source. Or uri may be a URI giving transport, hostname, user, port, etc. in the usual form. Refer to driver documentation for the particular URIs supported. The maximum bandwidth (in Mbps) that will be used to do migration can be specified with the bandwidth parameter. If set to 0, libvirt will choose a suitable default. Some hypervisors do not support this feature and will return an error if bandwidth is not 0. To see which features are supported by the current hypervisor, see VirConnect.getCapabilities, /capabilities/host/migration_features. There are many limitations on migration imposed by the underlying technology - for example it may not be possible to migrate between different processors even with the same architecture, or between different types of hypervisor.

Parameters:
dconn - destination host (a VirConnect object)
flags - flags
dname - (optional) rename domain to this at destination
uri - (optional) dest hostname/URI as seen from the source host
bandwidth - optional) specify migration bandwidth limit in Mbps
Returns:
the new domain object if the migration was successful, or NULL in case of error. Note that the new domain object exists in the scope of the destination connection (dconn).
Throws:
LibvirtException

reboot

public void reboot(int flags)
            throws LibvirtException
Reboot this domain, the domain object is still usable there after but the domain OS is being stopped for a restart. Note that the guest OS may ignore the request.

Parameters:
flags - extra flags for the reboot operation, not used yet
Throws:
LibvirtException

suspend

public void suspend()
             throws LibvirtException
Suspends this active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated. Use VirDomain.resume() to reactivate the domain. This function requires priviledged access.

Throws:
LibvirtException

resume

public void resume()
            throws LibvirtException
Resume this suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain(). This function may requires privileged access

Throws:
LibvirtException

save

public void save(java.lang.String to)
          throws LibvirtException
Suspends this domain and saves its memory contents to a file on disk. After the call, if successful, the domain is not listed as running anymore (this may be a problem). Use VirConnect.virDomainRestore() to restore a domain after saving.

Parameters:
to - path for the output file
Throws:
LibvirtException

shutdown

public void shutdown()
              throws LibvirtException
Shuts down this domain, the domain object is still usable there after but the domain OS is being stopped. Note that the guest OS may ignore the request. TODO: should we add an option for reboot, knowing it may not be doable in the general case ?

Throws:
LibvirtException

undefine

public void undefine()
              throws LibvirtException
undefines this domain but does not stop it if it is running

Throws:
LibvirtException

setMemory

public void setMemory(long memory)
               throws LibvirtException
Dynamically changes the target amount of physical memory allocated to this domain. This function may requires priviledged access to the hypervisor.

Parameters:
memory - in kilobytes
Throws:
LibvirtException