org.libvirt
Class Connect

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

public class Connect
extends java.lang.Object

The Connect object represents a connection to a local or remote hypervisor/driver.

Author:
stoty

Field Summary
protected  ConnectionPointer VCP
          the native virConnectPtr.
 
Constructor Summary
Connect(java.lang.String uri)
          Constructs a read-write Connect object from the supplied URI.
Connect(java.lang.String uri, boolean readOnly)
          Constructs a Connect object from the supplied URI.
Connect(java.lang.String uri, ConnectAuth auth, int flags)
          Constructs a Connect object from the supplied URI, using the supplied authentication callback
 
Method Summary
 void close()
          Closes the connection to the hypervisor/driver.
static int[] convertUUIDBytes(byte[] bytes)
          Helper function to convert bytes into ints for the UUID calls
static byte[] createUUIDBytes(int[] UUID)
          Helper function to convert UUIDs into a stirng for the UUID calls
 Domain domainCreateLinux(java.lang.String xmlDesc, int flags)
          Launches a new Linux guest domain.
 Domain domainCreateXML(java.lang.String xmlDesc, int flags)
          Launch a new guest domain, based on an XML description
 Domain domainDefineXML(java.lang.String xmlDesc)
          Defines a domain, but does not start it
 Domain domainLookupByID(int id)
          Finds a domain based on the hypervisor ID number.
 Domain domainLookupByName(java.lang.String name)
          Looks up a domain based on its name.
 Domain domainLookupByUUID(int[] UUID)
          Looks up a domain based on its UUID in array form.
 Domain domainLookupByUUID(java.util.UUID uuid)
          Fetch a domain based on its globally unique id
 Domain domainLookupByUUIDString(java.lang.String UUID)
          Looks up a domain based on its UUID in String form.
 void finalize()
           
 java.lang.String findStoragePoolSources(java.lang.String type, java.lang.String srcSpecs, int flags)
          Talks to a storage backend and attempts to auto-discover the set of available storage pool sources.
 java.lang.String getCapabilities()
          Provides capabilities of the hypervisor / driver.
 java.lang.String getHostName()
          Returns the system hostname on which the hypervisor is running.
 long getHypervisorVersion(java.lang.String type)
          Returns the version of the hypervisor against which the library was compiled.
 long getLibVirVersion()
          Gets the version of the native libvirt library that the JNI part is linked to.
 int getMaxVcpus(java.lang.String type)
          Provides the maximum number of virtual CPUs supported for a guest VM of a specific type.
 java.lang.String getType()
          Gets the name of the Hypervisor software used.
 java.lang.String getURI()
          Returns the URI (name) of the hypervisor connection.
 long getVersion()
          Gets the version level of the Hypervisor running.
 java.lang.String[] listDefinedDomains()
          Lists the names of the defined but inactive domains
 java.lang.String[] listDefinedNetworks()
          Lists the inactive networks
 java.lang.String[] listDefinedStoragePools()
          Provides the list of names of inactive storage pools.
 int[] listDomains()
          Lists the active domains.
 java.lang.String[] listNetworks()
          Lists the active networks.
 java.lang.String[] listStoragePools()
          Provides the list of names of active storage pools.
 Network networkCreateXML(java.lang.String xmlDesc)
          Creates and starts a new virtual network.
 Network networkDefineXML(java.lang.String xmlDesc)
          Defines a network, but does not create it.
 Network networkLookupByName(java.lang.String name)
          Looks up a network on the based on its name.
 Network networkLookupByUUID(int[] UUID)
          Deprecated. use the UUIDString or UUID API.
 Network networkLookupByUUID(java.util.UUID uuid)
          Fetch a network based on its globally unique id
 Network networkLookupByUUIDString(java.lang.String UUID)
          Looks up a network based on its UUID represented as a String.
 NodeInfo nodeInfo()
          Returns a NodeInfo object describing the hardware configuration of the node.
 int numOfDefinedDomains()
          Provides the number of inactive domains.
 int numOfDefinedNetworks()
          Provides the number of inactive networks.
 int numOfDefinedStoragePools()
          Provides the number of inactive storage pools
 int numOfDomains()
          Provides the number of active domains.
 int numOfNetworks()
          Provides the number of active networks.
 int numOfStoragePools()
          Provides the number of active storage pools
protected  void processError()
          call the error handling logic.
 void restore(java.lang.String from)
          Restores a domain saved to disk by Domain.save().
 void setDom0Memory(long memory)
          change the amount of memory reserved to Domain0.
 StoragePool storagePoolCreateXML(java.lang.String xmlDesc, int flags)
          Create a new storage based on its XML description.
 StoragePool storagePoolDefineXML(java.lang.String xml, int flags)
          Define a new inactive storage pool based on its XML description.
 StoragePool storagePoolLookupByName(java.lang.String name)
          Fetch a storage pool based on its unique name
 StoragePool storagePoolLookupByUUID(int[] UUID)
          Deprecated. Use the UUIDString or UUID APIs.
 StoragePool storagePoolLookupByUUID(java.util.UUID uuid)
          Fetch a storage pool based on its globally unique id
 StoragePool storagePoolLookupByUUIDString(java.lang.String UUID)
          Fetch a storage pool based on its globally unique id
 StorageVol storageVolLookupByKey(java.lang.String key)
          Fetch a a storage volume based on its globally unique key
 StorageVol storageVolLookupByPath(java.lang.String path)
          Fetch a storage volume based on its locally (host) unique path
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VCP

protected ConnectionPointer VCP
the native virConnectPtr.

Constructor Detail

Connect

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

Parameters:
uri - The connection URI
Throws:
LibvirtException
See Also:
The URI documentation

Connect

public Connect(java.lang.String uri,
               boolean readOnly)
        throws LibvirtException
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(java.lang.String uri,
               ConnectAuth auth,
               int flags)
        throws LibvirtException
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
Method Detail

convertUUIDBytes

public static int[] convertUUIDBytes(byte[] bytes)
Helper function to convert bytes into ints for the UUID calls


createUUIDBytes

public static byte[] createUUIDBytes(int[] UUID)
Helper function to convert UUIDs into a stirng for the UUID calls


close

public void close()
           throws LibvirtException
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(java.lang.String xmlDesc,
                                int flags)
                         throws LibvirtException
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

domainCreateXML

public Domain domainCreateXML(java.lang.String xmlDesc,
                              int flags)
                       throws LibvirtException
Launch a new guest domain, based on an XML description

Parameters:
xmlDesc -
Returns:
the Domain object
Throws:
LibvirtException
See Also:
The XML format description

domainDefineXML

public Domain domainDefineXML(java.lang.String xmlDesc)
                       throws LibvirtException
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)
                        throws LibvirtException
Finds a domain based on the hypervisor ID number.

Parameters:
id - the hypervisor id
Returns:
the Domain object
Throws:
LibvirtException

domainLookupByName

public Domain domainLookupByName(java.lang.String name)
                          throws LibvirtException
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)
                          throws LibvirtException
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

domainLookupByUUID

public Domain domainLookupByUUID(java.util.UUID uuid)
                          throws LibvirtException
Fetch a domain based on its globally unique id

Parameters:
UUID - a java UUID
Returns:
a new domain object
Throws:
LibvirtException

domainLookupByUUIDString

public Domain domainLookupByUUIDString(java.lang.String UUID)
                                throws LibvirtException
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()
              throws LibvirtException
Overrides:
finalize in class java.lang.Object
Throws:
LibvirtException

findStoragePoolSources

public java.lang.String findStoragePoolSources(java.lang.String type,
                                               java.lang.String srcSpecs,
                                               int flags)
                                        throws LibvirtException
Talks to a storage backend and attempts to auto-discover the set of available storage pool sources. e.g. For iSCSI this would be a set of iSCSI targets. For NFS this would be a list of exported paths. The srcSpec (optional for some storage pool types, e.g. local ones) is an instance of the storage pool's source element specifying where to look for the pools. srcSpec is not required for some types (e.g., those querying local storage resources only)

Parameters:
type - type of storage pool to discover
srcSpecs - XML document specifying discovery sourc
flags - unused
Returns:
an xml document consisting of a SourceList element containing a source document appropriate to the given pool type for each discovered source.
Throws:
LibvirtException

getCapabilities

public java.lang.String getCapabilities()
                                 throws LibvirtException
Provides capabilities of the hypervisor / driver.

Returns:
an XML String describing the capabilities.
Throws:
LibvirtException
See Also:
The XML format description

getHostName

public java.lang.String getHostName()
                             throws LibvirtException
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

getHypervisorVersion

public long getHypervisorVersion(java.lang.String type)
                          throws LibvirtException
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

getLibVirVersion

public long getLibVirVersion()
                      throws LibvirtException
Gets the version of the native libvirt library that the JNI part is linked to.

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

getMaxVcpus

public int getMaxVcpus(java.lang.String type)
                throws LibvirtException
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 java.lang.String getType()
                         throws LibvirtException
Gets the name of the Hypervisor software used.

Returns:
the name
Throws:
LibvirtException

getURI

public java.lang.String getURI()
                        throws LibvirtException
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()
                throws LibvirtException
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

listDefinedDomains

public java.lang.String[] listDefinedDomains()
                                      throws LibvirtException
Lists the names of the defined but inactive domains

Returns:
an Array of Strings that contains the names of the defined domains currently inactive
Throws:
LibvirtException

listDefinedNetworks

public java.lang.String[] listDefinedNetworks()
                                       throws LibvirtException
Lists the inactive networks

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

listDefinedStoragePools

public java.lang.String[] listDefinedStoragePools()
                                           throws LibvirtException
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()
                  throws LibvirtException
Lists the active domains.

Returns:
and array of the IDs of the active domains
Throws:
LibvirtException

listNetworks

public java.lang.String[] listNetworks()
                                throws LibvirtException
Lists the active networks.

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

listStoragePools

public java.lang.String[] listStoragePools()
                                    throws LibvirtException
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(java.lang.String xmlDesc)
                         throws LibvirtException
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(java.lang.String xmlDesc)
                         throws LibvirtException
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(java.lang.String name)
                            throws LibvirtException
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)
                            throws LibvirtException
Deprecated. use the UUIDString or UUID API.

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

networkLookupByUUID

public Network networkLookupByUUID(java.util.UUID uuid)
                            throws LibvirtException
Fetch a network based on its globally unique id

Parameters:
UUID - a java UUID
Returns:
a new network object
Throws:
LibvirtException

networkLookupByUUIDString

public Network networkLookupByUUIDString(java.lang.String UUID)
                                  throws LibvirtException
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()
                  throws LibvirtException
Returns a NodeInfo object describing the hardware configuration of the node.

Returns:
a NodeInfo object
Throws:
LibvirtException

numOfDefinedDomains

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

Returns:
the number of inactive domains
Throws:
LibvirtException

numOfDefinedNetworks

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

Returns:
the number of inactive networks
Throws:
LibvirtException

numOfDefinedStoragePools

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

Returns:
the number of pools found
Throws:
LibvirtException

numOfDomains

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

Returns:
the number of active domains
Throws:
LibvirtException

numOfNetworks

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

Returns:
the number of active networks
Throws:
LibvirtException

numOfStoragePools

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

Returns:
the number of pools found
Throws:
LibvirtException

processError

protected void processError()
                     throws LibvirtException
call the error handling logic. Should be called after every libvirt call

Throws:
LibvirtException

restore

public void restore(java.lang.String from)
             throws LibvirtException
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)
                   throws LibvirtException
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(java.lang.String xmlDesc,
                                        int flags)
                                 throws LibvirtException
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(java.lang.String xml,
                                        int flags)
                                 throws LibvirtException
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(java.lang.String name)
                                    throws LibvirtException
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)
                                    throws LibvirtException
Deprecated. Use the UUIDString or UUID APIs.

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

storagePoolLookupByUUID

public StoragePool storagePoolLookupByUUID(java.util.UUID uuid)
                                    throws LibvirtException
Fetch a storage pool based on its globally unique id

Parameters:
UUID - a java UUID
Returns:
a new network object
Throws:
LibvirtException

storagePoolLookupByUUIDString

public StoragePool storagePoolLookupByUUIDString(java.lang.String UUID)
                                          throws LibvirtException
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(java.lang.String key)
                                 throws LibvirtException
Fetch a a storage volume based on its globally unique key

Parameters:
key - globally unique key
Returns:
a storage volume
Throws:
LibvirtException

storageVolLookupByPath

public StorageVol storageVolLookupByPath(java.lang.String path)
                                  throws LibvirtException
Fetch a storage volume based on its locally (host) unique path

Parameters:
path - locally unique path
Returns:
a storage volume
Throws:
LibvirtException