org.libvirt
Class VirConnect

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

public class VirConnect
extends java.lang.Object

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


Constructor Summary
VirConnect(java.lang.String uri)
          Constructs a read-write VirConnect object from the supplied URI.
VirConnect(java.lang.String uri, boolean readOnly)
          Constructs a VirConnect object from the supplied URI.
 
Method Summary
 void close()
          Closes the connection to the hypervisor/driver.
 void finalize()
           
 java.lang.String getCapabilities()
          Provides capabilities of the hypervisor / driver.
 java.lang.String getHostName()
          Returns the system hostname on which the hypervisor is running.
 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 domains
 java.lang.String[] listDefinedNetworks()
          Lists the inactive networks
 int[] listDomains()
          Lists the active domains.
 java.lang.String[] listNetworks()
          Lists the active networks.
 int numOfDefinedDomains()
          Provides the number of inactive domains.
 int numOfDefinedNetworks()
          Provides the number of inactive networks.
 int numOfDomains()
          Provides the number of active domains.
 int numOfNetworks()
          Provides the number of active networks.
 void restore(java.lang.String from)
          Restores a domain saved to disk by VirDomain.save().
 void setDom0Memory(long memory)
          change the amount of memory reserved to Domain0.
 VirDomain virDomainCreateLinux(java.lang.String xmlDesc, int flags)
          Launches a new Linux guest domain.
 VirDomain virDomainDefineXML(java.lang.String xmlDesc)
          Defines a domain, but does not start it
 VirDomain virDomainLookupByID(int id)
          Finds a domain based on the hypervisor ID number.
 VirDomain virDomainLookupByName(java.lang.String name)
          Looks up a domain based on its name.
 VirDomain virDomainLookupByUUID(int[] UUID)
          Looks up a domain based on its UUID in array form.
 VirDomain virDomainLookupByUUIDString(java.lang.String UUID)
          Looks up a domain based on its UUID in String form.
 long virGetHypervisorVersion(java.lang.String type)
          Returns the version of the hypervisor against which the library was compiled.
 long virGetLibVirVersion()
          Gets the version of the native libvirt library that the JNI part is linked to.
 VirNetwork virNetworkCreateXML(java.lang.String xmlDesc)
          Creates and starts a new virtual network.
 VirNetwork virNetworkDefineXML(java.lang.String xmlDesc)
          Defines a network, but does not create it.
 VirNetwork virNetworkLookupByName(java.lang.String name)
          Looks up a network on the based on its name.
 VirNetwork virNetworkLookupByUUID(int[] UUID)
          Looks up a network based on its UUID represented as an int array.
 VirNetwork virNetworkLookupByUUIDString(java.lang.String UUID)
          Looks up a network based on its UUID represented as a String.
 VirNodeInfo virNodeInfo()
          Returns a VirNodeInfo object describing the hardware configuration of the node.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

VirConnect

public VirConnect(java.lang.String uri,
                  boolean readOnly)
           throws LibvirtException
Constructs a VirConnect object from the supplied URI.

Parameters:
uri - The connection URI
readOnly - Whether the connection is read-only
Throws:
LibvirtException
See Also:
The URI documentation

VirConnect

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

Parameters:
uri -
Throws:
LibvirtException
See Also:
The URI documentation
Method Detail

finalize

public void finalize()
              throws LibvirtException
Overrides:
finalize in class java.lang.Object
Throws:
LibvirtException

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

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

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

virGetLibVirVersion

public long virGetLibVirVersion()
                         throws LibvirtException
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

virGetHypervisorVersion

public long virGetHypervisorVersion(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

listDefinedDomains

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

Returns:
an Array of Strings that contains the names of the defined domains
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

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

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

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

virNetworkLookupByName

public VirNetwork virNetworkLookupByName(java.lang.String name)
                                  throws LibvirtException
Looks up a network on the based on its name.

Parameters:
name - name of the network
Returns:
The VirNetwork object found
Throws:
LibvirtException

virNetworkLookupByUUID

public VirNetwork virNetworkLookupByUUID(int[] UUID)
                                  throws LibvirtException
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 VirNetwork object found
Throws:
LibvirtException

virNetworkLookupByUUIDString

public VirNetwork virNetworkLookupByUUIDString(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 VirNetwork object found
Throws:
LibvirtException

virNetworkCreateXML

public VirNetwork virNetworkCreateXML(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 VirNetwork object representing the created network
Throws:
LibvirtException
See Also:
The XML format description

virNetworkDefineXML

public VirNetwork virNetworkDefineXML(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:
Throws:
LibvirtException
See Also:
The XML format description

virDomainLookupByID

public VirDomain virDomainLookupByID(int id)
                              throws LibvirtException
Finds a domain based on the hypervisor ID number.

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

virDomainLookupByName

public VirDomain virDomainLookupByName(java.lang.String name)
                                throws LibvirtException
Looks up a domain based on its name.

Parameters:
name - the name of the domain
Returns:
the VirDomain object
Throws:
LibvirtException

virDomainLookupByUUID

public VirDomain virDomainLookupByUUID(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 VirDomain object
Throws:
LibvirtException

virDomainLookupByUUIDString

public VirDomain virDomainLookupByUUIDString(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 VirDomain object
Throws:
LibvirtException

virDomainCreateLinux

public VirDomain virDomainCreateLinux(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 VirDomain object
Throws:
LibvirtException
See Also:
The XML format description

virDomainDefineXML

public VirDomain virDomainDefineXML(java.lang.String xmlDesc)
                             throws LibvirtException
Defines a domain, but does not start it

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

restore

public void restore(java.lang.String from)
             throws LibvirtException
Restores a domain saved to disk by VirDomain.save().

Parameters:
from - the path of the saved file on the remote host
Throws:
LibvirtException

virNodeInfo

public VirNodeInfo virNodeInfo()
                        throws LibvirtException
Returns a VirNodeInfo object describing the hardware configuration of the node.

Returns:
a VirNodeInfo object
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