org.libvirt

Class Connect

public class Connect extends Object

The Connect object represents a connection to a local or remote hypervisor/driver.
Constructor Summary
Connect(String uri, boolean readOnly)
Constructs a Connect object from the supplied URI.
Connect(String uri, ConnectAuth auth, int flags)
Constructs a Connect object from the supplied URI, using the supplied authentication callback
Connect(String uri)
Constructs a read-write Connect object from the supplied URI.
Method Summary
voidclose()
Closes the connection to the hypervisor/driver.
DomaindomainCreateLinux(String xmlDesc, int flags)
Launches a new Linux guest domain.
DomaindomainDefineXML(String xmlDesc)
Defines a domain, but does not start it
DomaindomainLookupByID(int id)
Finds a domain based on the hypervisor ID number.
DomaindomainLookupByName(String name)
Looks up a domain based on its name.
DomaindomainLookupByUUID(int[] UUID)
Looks up a domain based on its UUID in array form.
DomaindomainLookupByUUIDString(String UUID)
Looks up a domain based on its UUID in String form.
voidfinalize()
StringgetCapabilities()
Provides capabilities of the hypervisor / driver.
StringgetHostName()
Returns the system hostname on which the hypervisor is running. (the result of the gethostname(2) system call) If we are connected to a remote system, then this returns the hostname of the remote system.
longgetLibVirVersion()
Gets the version of the native libvirt library that the JNI part is linked to.
intgetMaxVcpus(String type)
Provides the maximum number of virtual CPUs supported for a guest VM of a specific type.
StringgetType()
Gets the name of the Hypervisor software used.
StringgetURI()
Returns the URI (name) of the hypervisor connection.
longgetVersion()
Gets the version level of the Hypervisor running.
longGetHypervisorVersion(String type)
Returns the version of the hypervisor against which the library was compiled.
String[]listDefinedDomains()
Lists the names of the defined domains
String[]listDefinedNetworks()
Lists the inactive networks
String[]listDefinedStoragePools()
Provides the list of names of inactive storage pools.
int[]listDomains()
Lists the active domains.
String[]listNetworks()
Lists the active networks.
String[]listStoragePools()
Provides the list of names of active storage pools.
NetworknetworkCreateXML(String xmlDesc)
Creates and starts a new virtual network.
NetworknetworkDefineXML(String xmlDesc)
Defines a network, but does not create it.
NetworknetworkLookupByName(String name)
Looks up a network on the based on its name.
NetworknetworkLookupByUUID(int[] UUID)
Looks up a network based on its UUID represented as an int array.
NetworknetworkLookupByUUIDString(String UUID)
Looks up a network based on its UUID represented as a String.
NodeInfonodeInfo()
Returns a NodeInfo object describing the hardware configuration of the node.
intnumOfDefinedDomains()
Provides the number of inactive domains.
intnumOfDefinedNetworks()
Provides the number of inactive networks.
intnumOfDefinedStoragePools()
Provides the number of inactive storage pools
intnumOfDomains()
Provides the number of active domains.
intnumOfNetworks()
Provides the number of active networks.
intnumOfStoragePools()
Provides the number of active storage pools
voidrestore(String from)
Restores a domain saved to disk by Domain.save().
voidsetDom0Memory(long memory)
change the amount of memory reserved to Domain0.
StoragePoolstoragePoolCreateXML(String xmlDesc, int flags)
Create a new storage based on its XML description.
StoragePoolstoragePoolDefineXML(String xml, int flags)
Define a new inactive storage pool based on its XML description.
StoragePoolstoragePoolLookupByName(String name)
Fetch a storage pool based on its unique name
StoragePoolstoragePoolLookupByUUID(int[] UUID)
Fetch a storage pool based on its globally unique id
StoragePoolstoragePoolLookupByUUIDString(String UUID)
Fetch a storage pool based on its globally unique id
StorageVolstorageVolLookupByKey(String key)
Fetch a a storage volume based on its globally unique key
StorageVolstorageVolLookupByPath(String path)
Fetch a storage volume based on its locally (host) unique path

Constructor Detail

Connect

public Connect(String uri, boolean readOnly)
Constructs a Connect object from the supplied URI.

Parameters: uri The connection URI readOnly Whether the connection is read-only

Throws: LibvirtException

See Also: The URI documentation

Connect

public Connect(String uri, ConnectAuth auth, int flags)
Constructs a Connect object from the supplied URI, using the supplied authentication callback

Parameters: uri The connection URI auth a ConnectAuth object flags

Throws: LibvirtException

See Also: The URI documentation

Connect

public Connect(String uri)
Constructs a read-write Connect object from the supplied URI.

Parameters: uri The connection URI

Throws: LibvirtException

See Also: The URI documentation

Method Detail

close

public void close()
Closes the connection to the hypervisor/driver. Calling any methods on the object after close() will result in an exception.

Throws: LibvirtException

domainCreateLinux

public Domain domainCreateLinux(String xmlDesc, int flags)
Launches a new Linux guest domain. The domain is based on an XML description similar to the one returned by virDomainGetXMLDesc(). This function may require priviledged access to the hypervisor.

Parameters: xmlDesc the Domain description in XML flags an optional set of flags (unused)

Returns: the Domain object

Throws: LibvirtException

See Also: The XML format description

domainDefineXML

public Domain domainDefineXML(String xmlDesc)
Defines a domain, but does not start it

Parameters: xmlDesc

Returns: the Domain object

Throws: LibvirtException

See Also: The XML format description

domainLookupByID

public Domain domainLookupByID(int id)
Finds a domain based on the hypervisor ID number.

Parameters: id the hypervisor id

Returns: the Domain object

Throws: LibvirtException

domainLookupByName

public Domain domainLookupByName(String name)
Looks up a domain based on its name.

Parameters: name the name of the domain

Returns: the Domain object

Throws: LibvirtException

domainLookupByUUID

public Domain domainLookupByUUID(int[] UUID)
Looks up a domain based on its UUID in array form. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.

Parameters: UUID the UUID as an unpacked int array

Returns: the Domain object

Throws: LibvirtException

domainLookupByUUIDString

public Domain domainLookupByUUIDString(String UUID)
Looks up a domain based on its UUID in String form.

Parameters: UUID the UUID in canonical String representation

Returns: the Domain object

Throws: LibvirtException

finalize

public void finalize()

getCapabilities

public String getCapabilities()
Provides capabilities of the hypervisor / driver.

Returns: an XML String describing the capabilities.

Throws: LibvirtException

See Also: The XML format description

getHostName

public String getHostName()
Returns the system hostname on which the hypervisor is running. (the result of the gethostname(2) system call) If we are connected to a remote system, then this returns the hostname of the remote system.

Returns: the hostname

Throws: LibvirtException

getLibVirVersion

public long getLibVirVersion()
Gets the version of the native libvirt library that the JNI part is linked to. // * @return major * 1,000,000 + minor * 1,000 + release

Throws: LibvirtException

getMaxVcpus

public int getMaxVcpus(String type)
Provides the maximum number of virtual CPUs supported for a guest VM of a specific type. The 'type' parameter here corresponds to the 'type' attribute in the element of the XML.

Parameters: type

Returns: the number of CPUs

Throws: LibvirtException

getType

public String getType()
Gets the name of the Hypervisor software used.

Returns: the name

Throws: LibvirtException

getURI

public String getURI()
Returns the URI (name) of the hypervisor connection. Normally this is the same as or similar to the string passed to the virConnectOpen/virConnectOpenReadOnly call, but the driver may make the URI canonical.

Returns: the URI

Throws: LibvirtException

getVersion

public long getVersion()
Gets the version level of the Hypervisor running. This may work only with hypervisor call, i.e. with priviledged access to the hypervisor, not with a Read-Only connection. If the version can't be extracted by lack of capacities returns 0.

Returns: major * 1,000,000 + minor * 1,000 + release

Throws: LibvirtException

GetHypervisorVersion

public long GetHypervisorVersion(String type)
Returns the version of the hypervisor against which the library was compiled. The type parameter specified which hypervisor's version is returned

Parameters: type

Returns: major * 1,000,000 + minor * 1,000 + release

Throws: LibvirtException

listDefinedDomains

public String[] listDefinedDomains()
Lists the names of the defined domains

Returns: an Array of Strings that contains the names of the defined domains

Throws: LibvirtException

listDefinedNetworks

public String[] listDefinedNetworks()
Lists the inactive networks

Returns: an Array of Strings that contains the names of the inactive networks

Throws: LibvirtException

listDefinedStoragePools

public String[] listDefinedStoragePools()
Provides the list of names of inactive storage pools.

Returns: an Array of Strings that contains the names of the defined storage pools

Throws: LibvirtException

listDomains

public int[] listDomains()
Lists the active domains.

Returns: and array of the IDs of the active domains

Throws: LibvirtException

listNetworks

public String[] listNetworks()
Lists the active networks.

Returns: an Array of Strings that contains the names of the active networks

Throws: LibvirtException

listStoragePools

public String[] listStoragePools()
Provides the list of names of active storage pools.

Returns: an Array of Strings that contains the names of the defined storage pools

Throws: LibvirtException

networkCreateXML

public Network networkCreateXML(String xmlDesc)
Creates and starts a new virtual network. The properties of the network are based on an XML description similar to the one returned by virNetworkGetXMLDesc()

Parameters: xmlDesc the Network Description

Returns: the Network object representing the created network

Throws: LibvirtException

See Also: The XML format description

networkDefineXML

public Network networkDefineXML(String xmlDesc)
Defines a network, but does not create it. The properties of the network are based on an XML description similar to the one returned by virNetworkGetXMLDesc()

Parameters: xmlDesc

Returns: the resulting Network object

Throws: LibvirtException

See Also: The XML format description

networkLookupByName

public Network networkLookupByName(String name)
Looks up a network on the based on its name.

Parameters: name name of the network

Returns: The Network object found

Throws: LibvirtException

networkLookupByUUID

public Network networkLookupByUUID(int[] UUID)
Looks up a network based on its UUID represented as an int array. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.

Parameters: UUID the UUID as an unpacked int array

Returns: The Network object found

Throws: LibvirtException

networkLookupByUUIDString

public Network networkLookupByUUIDString(String UUID)
Looks up a network based on its UUID represented as a String.

Parameters: UUID the UUID in canonical String representation

Returns: The Network object found

Throws: LibvirtException

nodeInfo

public NodeInfo nodeInfo()
Returns a NodeInfo object describing the hardware configuration of the node.

Returns: a NodeInfo object

Throws: LibvirtException

numOfDefinedDomains

public int numOfDefinedDomains()
Provides the number of inactive domains.

Returns: the number of inactive domains

Throws: LibvirtException

numOfDefinedNetworks

public int numOfDefinedNetworks()
Provides the number of inactive networks.

Returns: the number of inactive networks

Throws: LibvirtException

numOfDefinedStoragePools

public int numOfDefinedStoragePools()
Provides the number of inactive storage pools

Returns: the number of pools found

Throws: LibvirtException

numOfDomains

public int numOfDomains()
Provides the number of active domains.

Returns: the number of active domains

Throws: LibvirtException

numOfNetworks

public int numOfNetworks()
Provides the number of active networks.

Returns: the number of active networks

Throws: LibvirtException

numOfStoragePools

public int numOfStoragePools()
Provides the number of active storage pools

Returns: the number of pools found

Throws: LibvirtException

restore

public void restore(String from)
Restores a domain saved to disk by Domain.save().

Parameters: from the path of the saved file on the remote host

Throws: LibvirtException

setDom0Memory

public void setDom0Memory(long memory)
change the amount of memory reserved to Domain0. Domain0 is the domain where the application runs. This function may requires priviledged access to the hypervisor.

Parameters: memory in kilobytes

Throws: LibvirtException

storagePoolCreateXML

public StoragePool storagePoolCreateXML(String xmlDesc, int flags)
Create a new storage based on its XML description. The pool is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted

Parameters: xmlDesc XML description for new pool flags future flags, use 0 for now

Returns: StoragePool object

Throws: LibvirtException

storagePoolDefineXML

public StoragePool storagePoolDefineXML(String xml, int flags)
Define a new inactive storage pool based on its XML description. The pool is persistent, until explicitly undefined.

Parameters: xml XML description for new pool flags flags future flags, use 0 for now

Returns: StoragePool object

Throws: LibvirtException

storagePoolLookupByName

public StoragePool storagePoolLookupByName(String name)
Fetch a storage pool based on its unique name

Parameters: name name of pool to fetch

Returns: StoragePool object

Throws: LibvirtException

storagePoolLookupByUUID

public StoragePool storagePoolLookupByUUID(int[] UUID)
Fetch a storage pool based on its globally unique id

Parameters: UUID globally unique id of pool to fetch

Returns: a new network object

Throws: LibvirtException

storagePoolLookupByUUIDString

public StoragePool storagePoolLookupByUUIDString(String UUID)
Fetch a storage pool based on its globally unique id

Parameters: UUID globally unique id of pool to fetch

Returns: VirStoragePool object

Throws: LibvirtException

storageVolLookupByKey

public StorageVol storageVolLookupByKey(String key)
Fetch a a storage volume based on its globally unique key

Parameters: key globally unique key

Returns: a storage volume

storageVolLookupByPath

public StorageVol storageVolLookupByPath(String path)
Fetch a storage volume based on its locally (host) unique path

Parameters: path locally unique path

Returns: a storage volume