org.libvirt

Class Connect

java.lang.Object

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Connect.OpenFlags

Field Summary

Fields

Modifier and Type	Field and Description
protected ConnectionPointer	vcp The native virConnectPtr.

Constructor Summary

Constructors

Constructor and Description
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
Connect(java.net.URI uri, Connect.OpenFlags... flags) Constructs a read-write Connect object from the supplied URI.
Connect(java.net.URI uri, ConnectAuth auth) Constructs a Connect object from the supplied URI, using the supplied authentication callback
Connect(java.net.URI uri, ConnectAuth auth, Connect.OpenFlags... flags) Constructs a Connect object from the supplied URI, using the supplied authentication callback

Method Summary

Modifier and Type	Method and Description
void	addIOErrorListener(IOErrorListener l) Adds the specified I/O error listener to receive I/O error events for domains of this connection.
void	addLifecycleListener(LifecycleListener l) Adds the specified listener to receive lifecycle events for domains of this connection.
void	addPMSuspendListener(PMSuspendListener l) Adds the specified listener to receive PMSuspend events for domains of this connection.
void	addPMWakeupListener(PMWakeupListener l) Adds the specified listener to receive PMWakeup events for domains of this connection.
void	addRebootListener(RebootListener l) Adds the specified reboot listener to receive reboot events for domains of this connection.
java.lang.String	baselineCPU(java.lang.String[] xmlCPUs) Computes the most feature-rich CPU which is compatible with all given host CPUs.
int	close() Closes the connection to the hypervisor/driver.
CPUCompareResult	compareCPU(java.lang.String xmlDesc) Compares the given CPU description with the host CPU
static long	connectionVersion(Connect conn) Deprecated. Use getLibVersion() instead.
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
Device	deviceCreateXML(java.lang.String xmlDesc) Create a new device on the VM host machine, for example, virtual HBAs created using vport_create.
Device	deviceLookupByName(java.lang.String name) Fetch a device based on its unique name
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.
java.lang.String	domainXMLFromNative(java.lang.String nativeFormat, java.lang.String nativeConfig, int flags) Reads a native XML configuration document, and generates generates a domain configuration file describing the domain.
java.lang.String	domainXMLToNative(java.lang.String nativeFormat, java.lang.String domainXML, int flags) Reads a domain XML configuration document, and generates generates a native configuration file describing the domain.
boolean	equals(java.lang.Object obj)
protected 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.
long	getCellsFreeMemory(int startCells, int maxCells) NUMA Support
long	getFreeMemory() Returns the free memory for the connection
java.lang.String	getHostName() Returns the system hostname on which the hypervisor is running.
long	getHypervisorVersion(java.lang.String type) Deprecated. To get the version of the running hypervisor use getVersion() instead.
long	getLibVersion() Get the libvirt library version of this connection.
long	getLibVirVersion() Deprecated. use Library.getVersion() instead
int	getMaxVcpus(java.lang.String type) Provides the maximum number of virtual CPUs supported for a guest VM of a specific type.
SecurityModel	getSecurityModel() Returns the security model of the connected node.
java.lang.String	getSysinfo() Returns the XML description of the sysinfo details for the host on which the hypervisor is running.
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.
int	hashCode()
Interface	interfaceDefineXML(java.lang.String xmlDesc) Define an interface (or modify existing interface configuration)
Interface	interfaceLookupByMACString(java.lang.String mac) Try to lookup an interface on the given hypervisor based on its MAC.
Interface	interfaceLookupByName(java.lang.String name) Try to lookup an interface on the given hypervisor based on its name.
boolean	isAlive() Determine if the connection to the hypervisor is still alive.
boolean	isConnected() Verify the connect is active.
int	isEncrypted() Determine if the connection is encrypted
int	isSecure() Determine if the connection is secure
java.lang.String[]	listDefinedDomains() Lists the names of the defined but inactive domains
java.lang.String[]	listDefinedInterfaces() Provides the list of names of defined interfaces on this host
java.lang.String[]	listDefinedNetworks() Lists the inactive networks
java.lang.String[]	listDefinedStoragePools() Provides the list of names of inactive storage pools.
java.lang.String[]	listDevices(java.lang.String capabilityName) List the names of the devices on this node
int[]	listDomains() Lists the active domains.
java.lang.String[]	listInterfaces() Provides the list of names of interfaces on this host
java.lang.String[]	listNetworkFilters() Lists the names of the network filters
java.lang.String[]	listNetworks() Lists the active networks.
java.lang.String[]	listSecrets() Retrieve the List UUIDs of defined secrets
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.
NetworkFilter	networkFilterDefineXML(java.lang.String xmlDesc) Defines a networkFilter
NetworkFilter	networkFilterLookupByName(java.lang.String name) Fetch a network filter based on its unique name
NetworkFilter	networkFilterLookupByUUID(int[] uuid) Looks up a network filter based on its UUID in array form.
NetworkFilter	networkFilterLookupByUUID(java.util.UUID uuid) Fetch a network filter based on its globally unique id
NetworkFilter	networkFilterLookupByUUIDString(java.lang.String uuid) Looks up a network filter based on its uuid in String form.
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	numOfDefinedInterfaces() Provides the number of defined interfaces.
int	numOfDefinedNetworks() Provides the number of inactive networks.
int	numOfDefinedStoragePools() Provides the number of inactive storage pools
int	numOfDevices(java.lang.String capabilityName) Provides the number of node devices.
int	numOfDomains() Provides the number of active domains.
int	numOfInterfaces() Provides the number of interfaces.
int	numOfNetworkFilters() Provides the number of network filters
int	numOfNetworks() Provides the number of active networks.
int	numOfSecrets() Fetch number of currently defined secrets.
int	numOfStoragePools() Provides the number of active storage pools
void	registerCloseListener(ConnectionCloseListener l) Register the specified connection close listener to receive notifications when this connection is closed.
void	removeIOErrorListener(IOErrorListener l) Removes the specified I/O error listener so that it no longer receives I/O error events.
void	removeLifecycleListener(LifecycleListener l) Removes the specified lifecycle event listener so that it no longer receives lifecycle events.
void	removePMSuspendListener(PMSuspendListener l) Removes the specified PMSuspend listener so that it no longer receives PMSuspend events.
void	removePMWakeupListener(PMWakeupListener l) Removes the specified PMWakeup listener so that it no longer receives PMWakeup events.
void	restore(java.lang.String from) Restores a domain saved to disk by Domain.save().
Secret	secretDefineXML(java.lang.String xmlDesc) If XML specifies a UUID, locates the specified secret and replaces all attributes of the secret specified by UUID by attributes specified in xml (any attributes not specified in xml are discarded).
Secret	secretLookupByUUID(int[] uuid) Looks up a secret based on its UUID in array form.
Secret	secretLookupByUUID(java.util.UUID uuid) Fetch a secret based on its globally unique id
Secret	secretLookupByUUIDString(java.lang.String uuid) Looks up a secret based on its uuid in String form.
void	setConnectionErrorCallback(Libvirt.VirErrorCallback callback)
void	setDom0Memory(long memory) change the amount of memory reserved to Domain0.
static void	setErrorCallback(Libvirt.VirErrorCallback callback) Sets the error function to a user defined callback
boolean	setKeepAlive(int interval, int count) Start sending keepalive messages.
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
Stream	streamNew(int flags) Creates a new stream object which can be used to perform streamed I/O with other public API function.
void	unregisterCloseListener() Unregister the previously registered close listener.

Methods inherited from class java.lang.Object

clone, getClass, 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.net.URI uri,
               Connect.OpenFlags... flags)
        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

Connect

public Connect(java.net.URI uri,
               ConnectAuth auth,
               Connect.OpenFlags... 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

Connect

public Connect(java.net.URI uri,
               ConnectAuth auth)
        throws LibvirtException

Constructs a Connect object from the supplied URI, using the supplied authentication callback

Parameters:

uri - The connection URI

auth - a ConnectAuth object

Throws:

LibvirtException

See Also:

The URI documentation

Method Detail

connectionVersion

@Deprecated
public static long connectionVersion(Connect conn)

Deprecated. Use getLibVersion() instead.

Get the version of a connection.

Parameters:

conn - the connection to use.

Returns:

-1 in case of failure, versions have the format major * 1,000,000 + minor * 1,000 + release.

See Also:

Libvirt Documentation

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

getLibVersion

public long getLibVersion()
                   throws LibvirtException

Get the libvirt library version of this connection.

Returns:

The version of libvirt used by the daemon running on the connected host in the format major * 1,000,000 + minor * 1,000 + release.

Throws:

LibvirtException

See Also:

Libvirt Documentation

setErrorCallback

public static void setErrorCallback(Libvirt.VirErrorCallback callback)
                             throws LibvirtException

Sets the error function to a user defined callback

Parameters:

callback - a Class to perform the callback

Throws:

LibvirtException

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

baselineCPU

public java.lang.String baselineCPU(java.lang.String[] xmlCPUs)
                             throws LibvirtException

Computes the most feature-rich CPU which is compatible with all given host CPUs.

Parameters:

xmlCPUs - array of XML descriptions of host CPUs

Returns:

XML description of the computed CPU or NULL on error.

Throws:

LibvirtException

close

public int close()
          throws LibvirtException

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

Returns:

number of remaining references (>= 0)

Throws:

LibvirtException

registerCloseListener

public void registerCloseListener(ConnectionCloseListener l)
                           throws LibvirtException

Register the specified connection close listener to receive notifications when this connection is closed.

Note: There can only be at most one registered listener at a time.

Parameters:

l - the connection close listener

Throws:

LibvirtException - on failure

See Also:

unregisterCloseListener()

unregisterCloseListener

public void unregisterCloseListener()
                             throws LibvirtException

Unregister the previously registered close listener. When there currently is no registered close listener, this method does nothing.

Throws:

LibvirtException

See Also:

registerCloseListener(org.libvirt.event.ConnectionCloseListener)

compareCPU

public CPUCompareResult compareCPU(java.lang.String xmlDesc)
                            throws LibvirtException

Compares the given CPU description with the host CPU

Parameters:

xmlDesc -

Returns:

comparison result according to enum CPUCompareResult

Throws:

LibvirtException

See Also:

Libvirt Documentation

deviceCreateXML

public Device deviceCreateXML(java.lang.String xmlDesc)
                       throws LibvirtException

Create a new device on the VM host machine, for example, virtual HBAs created using vport_create.

Parameters:

xmlDesc - the device to create

Returns:

the Device object

Throws:

LibvirtException

deviceLookupByName

public Device deviceLookupByName(java.lang.String name)
                          throws LibvirtException

Fetch a device based on its unique name

Parameters:

name - name of device to fetch

Returns:

Device object

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

addIOErrorListener

public void addIOErrorListener(IOErrorListener l)
                        throws LibvirtException

Adds the specified I/O error listener to receive I/O error events for domains of this connection.

Parameters:

l - the I/O error listener

Throws:

LibvirtException - on failure

See Also:

Libvirt Documentation

addLifecycleListener

public void addLifecycleListener(LifecycleListener l)
                          throws LibvirtException

Adds the specified listener to receive lifecycle events for domains of this connection.

Parameters:

l - the lifecycle listener

Throws:

LibvirtException - on failure

See Also:

removeLifecycleListener(org.libvirt.event.LifecycleListener), Domain.addLifecycleListener(org.libvirt.event.LifecycleListener), virConnectDomainEventRegisterAny

addPMSuspendListener

public void addPMSuspendListener(PMSuspendListener l)
                          throws LibvirtException

Adds the specified listener to receive PMSuspend events for domains of this connection.

Parameters:

l - the PMSuspend listener

Throws:

LibvirtException - on failure

Since:

1.5.2

See Also:

removePMSuspendListener(org.libvirt.event.PMSuspendListener), Domain.addPMSuspendListener(org.libvirt.event.PMSuspendListener), virConnectDomainEventRegisterAny

removePMSuspendListener

public void removePMSuspendListener(PMSuspendListener l)
                             throws LibvirtException

Removes the specified PMSuspend listener so that it no longer receives PMSuspend events.

Parameters:

l - the PMSuspend listener

Throws:

LibvirtException

Since:

1.5.2

See Also:

virConnectDomainEventDeregisterAny

addPMWakeupListener

public void addPMWakeupListener(PMWakeupListener l)
                         throws LibvirtException

Adds the specified listener to receive PMWakeup events for domains of this connection.

Parameters:

l - the PMWakeup listener

Throws:

LibvirtException - on failure

Since:

1.5.2

See Also:

removePMWakeupListener(org.libvirt.event.PMWakeupListener), Domain.addPMWakeupListener(org.libvirt.event.PMWakeupListener), virConnectDomainEventRegisterAny

removePMWakeupListener

public void removePMWakeupListener(PMWakeupListener l)
                            throws LibvirtException

Removes the specified PMWakeup listener so that it no longer receives PMWakeup events.

Parameters:

l - the PMWakeup listener

Throws:

LibvirtException

See Also:

virConnectDomainEventDeregisterAny

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener l)
                             throws LibvirtException

Removes the specified lifecycle event listener so that it no longer receives lifecycle events.

Parameters:

l - the lifecycle event listener

Throws:

LibvirtException

See Also:

virConnectDomainEventDeregisterAny

addRebootListener

public void addRebootListener(RebootListener l)
                       throws LibvirtException

Adds the specified reboot listener to receive reboot events for domains of this connection.

Parameters:

l - the reboot listener

Throws:

LibvirtException - on failure

Since:

1.5.2

See Also:

Domain.addRebootListener(org.libvirt.event.RebootListener), virConnectDomainEventRegisterAny

removeIOErrorListener

public void removeIOErrorListener(IOErrorListener l)
                           throws LibvirtException

Removes the specified I/O error listener so that it no longer receives I/O error events.

Parameters:

l - the I/O error listener

Throws:

LibvirtException

See Also:

virConnectDomainEventDeregisterAny

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

domainXMLFromNative

public java.lang.String domainXMLFromNative(java.lang.String nativeFormat,
                                            java.lang.String nativeConfig,
                                            int flags)
                                     throws LibvirtException

Reads a native XML configuration document, and generates generates a domain configuration file describing the domain. The format of the native data is hypervisor dependant.

Returns:

domain XML as String, or null on error

Throws:

LibvirtException

domainXMLToNative

public java.lang.String domainXMLToNative(java.lang.String nativeFormat,
                                          java.lang.String domainXML,
                                          int flags)
                                   throws LibvirtException

Reads a domain XML configuration document, and generates generates a native configuration file describing the domain. The format of the native data is hypervisor dependant.

Returns:

domain XML as String, or null on error

Throws:

LibvirtException

finalize

protected 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

getCellsFreeMemory

public long getCellsFreeMemory(int startCells,
                               int maxCells)
                        throws LibvirtException

NUMA Support

Throws:

LibvirtException

getFreeMemory

public long getFreeMemory()
                   throws LibvirtException

Returns the free memory for the connection

Throws:

LibvirtException

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

@Deprecated
public long getHypervisorVersion(java.lang.String type)
                                      throws LibvirtException

Deprecated. To get the version of the running hypervisor use getVersion() instead.

Returns the version of the hypervisor against which the library was compiled. Since libvirt 0.9.3 this simply returns the same version number as Library.getVersion().

Parameters:

type - The type of connection/driver to look at. See getType(). May be null.

Returns:

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

Throws:

LibvirtException

getLibVirVersion

@Deprecated
public long getLibVirVersion()
                                  throws LibvirtException

Deprecated. use Library.getVersion() instead

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

getSecurityModel

public SecurityModel getSecurityModel()
                               throws LibvirtException

Returns the security model of the connected node.

Throws:

LibvirtException

getSysinfo

public java.lang.String getSysinfo()
                            throws LibvirtException

Returns the XML description of the sysinfo details for the host on which the hypervisor is running.

This information is generally available only for hypervisors running with root privileges.

Returns:

sysinfo details in the same format as the <sysinfo> element of a domain XML.

Throws:

LibvirtException

Since:

1.5.2

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

interfaceDefineXML

public Interface interfaceDefineXML(java.lang.String xmlDesc)
                             throws LibvirtException

Define an interface (or modify existing interface configuration)

Parameters:

xmlDesc - the interface to create

Returns:

the Interface object

Throws:

LibvirtException

interfaceLookupByMACString

public Interface interfaceLookupByMACString(java.lang.String mac)
                                     throws LibvirtException

Try to lookup an interface on the given hypervisor based on its MAC.

Throws:

LibvirtException

interfaceLookupByName

public Interface interfaceLookupByName(java.lang.String name)
                                throws LibvirtException

Try to lookup an interface on the given hypervisor based on its name.

Throws:

LibvirtException

isEncrypted

public int isEncrypted()
                throws LibvirtException

Determine if the connection is encrypted

Returns:

1 if encrypted, 0 if not encrypted

Throws:

LibvirtException

See Also:

Libvirt Documentation

isSecure

public int isSecure()
             throws LibvirtException

Determine if the connection is secure

Returns:

1 if secure, 0 if not secure

Throws:

LibvirtException

See Also:

Libvirt Documentation

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

listDefinedInterfaces

public java.lang.String[] listDefinedInterfaces()
                                         throws LibvirtException

Provides the list of names of defined interfaces on this host

Returns:

an Array of Strings that contains the names of the interfaces on this host

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

listDevices

public java.lang.String[] listDevices(java.lang.String capabilityName)
                               throws LibvirtException

List the names of the devices on this node

Parameters:

capabilityName - optional capability name

Throws:

LibvirtException

listDomains

public int[] listDomains()
                  throws LibvirtException

Lists the active domains.

Returns:

and array of the IDs of the active domains

Throws:

LibvirtException

listInterfaces

public java.lang.String[] listInterfaces()
                                  throws LibvirtException

Provides the list of names of interfaces on this host

Returns:

an Array of Strings that contains the names of the interfaces on this host

Throws:

LibvirtException

listNetworkFilters

public java.lang.String[] listNetworkFilters()
                                      throws LibvirtException

Lists the names of the network filters

Returns:

an Array of Strings that contains the names network filters

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

listSecrets

public java.lang.String[] listSecrets()
                               throws LibvirtException

Retrieve the List UUIDs of defined secrets

Returns:

an Array of Strings that contains the uuids of the defined secrets

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

networkFilterDefineXML

public NetworkFilter networkFilterDefineXML(java.lang.String xmlDesc)
                                     throws LibvirtException

Defines a networkFilter

Parameters:

xmlDesc - the descirption of the filter

Returns:

the new filer

Throws:

LibvirtException

See Also:

Libvirt Documentation

networkFilterLookupByName

public NetworkFilter networkFilterLookupByName(java.lang.String name)
                                        throws LibvirtException

Fetch a network filter based on its unique name

Parameters:

name - name of network filter to fetch

Returns:

network filter object

Throws:

LibvirtException

See Also:

Libvirt Documentation

networkFilterLookupByUUID

public NetworkFilter networkFilterLookupByUUID(int[] uuid)
                                        throws LibvirtException

Looks up a network filter 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 network filter object

Throws:

LibvirtException

networkFilterLookupByUUID

public NetworkFilter networkFilterLookupByUUID(java.util.UUID uuid)
                                        throws LibvirtException

Fetch a network filter based on its globally unique id

Parameters:

uuid - a java UUID

Returns:

a new network filter object

Throws:

LibvirtException

networkFilterLookupByUUIDString

public NetworkFilter networkFilterLookupByUUIDString(java.lang.String uuid)
                                              throws LibvirtException

Looks up a network filter based on its uuid in String form.

Parameters:

uuid - the uuid in canonical String representation

Returns:

the Network Filter object

Throws:

LibvirtException

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

@Deprecated
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

numOfDefinedInterfaces

public int numOfDefinedInterfaces()
                           throws LibvirtException

Provides the number of defined interfaces.

Returns:

the number of interfaces

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

numOfDevices

public int numOfDevices(java.lang.String capabilityName)
                 throws LibvirtException

Provides the number of node devices.

Returns:

the number of inactive domains

Throws:

LibvirtException

numOfDomains

public int numOfDomains()
                 throws LibvirtException

Provides the number of active domains.

Returns:

the number of active domains

Throws:

LibvirtException

numOfInterfaces

public int numOfInterfaces()
                    throws LibvirtException

Provides the number of interfaces.

Returns:

the number of interfaces

Throws:

LibvirtException

numOfNetworkFilters

public int numOfNetworkFilters()
                        throws LibvirtException

Provides the number of network filters

Returns:

the number of network filters

Throws:

LibvirtException

numOfNetworks

public int numOfNetworks()
                  throws LibvirtException

Provides the number of active networks.

Returns:

the number of active networks

Throws:

LibvirtException

numOfSecrets

public int numOfSecrets()
                 throws LibvirtException

Fetch number of currently defined secrets.

Returns:

the number of secrets

Throws:

LibvirtException

numOfStoragePools

public int numOfStoragePools()
                      throws LibvirtException

Provides the number of active storage pools

Returns:

the number of pools found

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

secretDefineXML

public Secret secretDefineXML(java.lang.String xmlDesc)
                       throws LibvirtException

If XML specifies a UUID, locates the specified secret and replaces all attributes of the secret specified by UUID by attributes specified in xml (any attributes not specified in xml are discarded). Otherwise, creates a new secret with an automatically chosen UUID, and initializes its attributes from xml.

Parameters:

xmlDesc - the secret to create

Returns:

the Secret object

Throws:

LibvirtException

secretLookupByUUID

public Secret secretLookupByUUID(int[] uuid)
                          throws LibvirtException

Looks up a secret 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 Secret object

Throws:

LibvirtException

secretLookupByUUID

public Secret secretLookupByUUID(java.util.UUID uuid)
                          throws LibvirtException

Fetch a secret based on its globally unique id

Parameters:

uuid - a java UUID

Returns:

a new domain object

Throws:

LibvirtException

secretLookupByUUIDString

public Secret secretLookupByUUIDString(java.lang.String uuid)
                                throws LibvirtException

Looks up a secret based on its uuid in String form.

Parameters:

uuid - the uuid in canonical String representation

Returns:

the Domain object

Throws:

LibvirtException

setConnectionErrorCallback

public void setConnectionErrorCallback(Libvirt.VirErrorCallback callback)
                                throws LibvirtException

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

@Deprecated
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

streamNew

public Stream streamNew(int flags)
                 throws LibvirtException

Creates a new stream object which can be used to perform streamed I/O with other public API function.

Parameters:

flags - use Stream.VIR_STREAM_NONBLOCK if non-blocking is required

Returns:

the new object

Throws:

LibvirtException

isConnected

public boolean isConnected()
                    throws LibvirtException

Verify the connect is active.

Returns:

boolean The true connected, or false not.

Throws:

LibvirtException

isAlive

public boolean isAlive()
                throws LibvirtException

Determine if the connection to the hypervisor is still alive.

A connection will be classed as alive if it is either local, or running over a channel (TCP or UNIX socket) which is not closed.

Returns:

true if alive, false otherwise.

Throws:

LibvirtException

setKeepAlive

public boolean setKeepAlive(int interval,
                            int count)
                     throws LibvirtException

Start sending keepalive messages. After interval seconds of inactivity, consider the connection to be broken when no response is received after count keepalive messages sent in a row.

In other words, sending count + 1 keepalive message results in closing the connection.

When interval is <= 0, no keepalive messages will be sent.

When count is 0, the connection will be automatically closed after interval seconds of inactivity without sending any keepalive messages.

Note: client has to implement and run event loop to be able to use keepalive messages. Failure to do so may result in connections being closed unexpectedly.

Note: This API function controls only keepalive messages sent by the client. If the server is configured to use keepalive you still need to run the event loop to respond to them, even if you disable keepalives by this function.

Parameters:

interval - number of seconds of inactivity before a keepalive message is sent

count - number of messages that can be sent in a row

Returns:

true when successful, false otherwise.

Throws:

LibvirtException