2013-05-03 14:25:37 +00:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2017-07-26 17:01:25 +00:00
|
|
|
<!DOCTYPE html>
|
2013-05-03 14:25:37 +00:00
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
2008-07-22 17:49:53 +00:00
|
|
|
<body>
|
|
|
|
|
<h1>Java API bindings</h1>
|
|
|
|
|
|
|
|
|
|
<h2>Presentation</h2>
|
2009-07-29 21:28:50 +00:00
|
|
|
<p>The Java bindings make use of <a href="https://jna.dev.java.net/">JNA</a>
|
2009-09-22 10:54:57 +00:00
|
|
|
to expose the C API in a Java friendly way. The bindings are based on
|
2009-07-29 21:28:50 +00:00
|
|
|
work initiated by Toth Istvan.</p>
|
2008-07-22 17:49:53 +00:00
|
|
|
|
|
|
|
|
<h2>Getting it</h2>
|
|
|
|
|
<p>
|
|
|
|
|
The latest versions of the libvirt Java bindings can be downloaded from:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li><a href="ftp://libvirt.org/libvirt/java/">libvirt.org FTP server</a></li>
|
2017-10-13 15:30:41 +00:00
|
|
|
<li><a href="https://libvirt.org/sources/java/">libvirt.org HTTP server</a></li>
|
2008-07-22 17:49:53 +00:00
|
|
|
</ul>
|
|
|
|
|
|
2009-07-29 21:28:50 +00:00
|
|
|
<h3>Maven</h3>
|
2017-10-13 15:30:41 +00:00
|
|
|
<p>A maven repository is located at <a href="https://libvirt.org/maven2/">https://libvirt.org/maven2/</a>
|
2009-07-29 21:28:50 +00:00
|
|
|
which you can use to include this in your maven projects.</p>
|
2008-07-22 17:49:53 +00:00
|
|
|
|
2009-07-29 21:28:50 +00:00
|
|
|
<h2>GIT source repository</h2>
|
|
|
|
|
<p> The Java bindings code source is now maintained in a <a
|
2020-08-25 22:44:00 +00:00
|
|
|
href="https://git-scm.com/">git</a> repository available on
|
2020-06-03 10:42:34 +00:00
|
|
|
<a href="https://gitlab.com/libvirt/libvirt-java/">gitlab.com</a>:
|
2009-07-29 21:28:50 +00:00
|
|
|
</p>
|
|
|
|
|
<pre>
|
2020-06-03 10:42:34 +00:00
|
|
|
git clone https://gitlab.com/libvirt/libvirt-java.git
|
2009-07-29 21:28:50 +00:00
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h2>Building</h2>
|
|
|
|
|
<p>The code is built using ant, and assumes that you have the jna jar installed. Once you have downloaded
|
|
|
|
|
the code you can build the code with</p>
|
2008-07-22 17:49:53 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
2009-07-29 21:28:50 +00:00
|
|
|
% cd libvirt-java
|
|
|
|
|
% ant build
|
2008-07-22 17:49:53 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2009-07-29 21:28:50 +00:00
|
|
|
|
2008-07-22 17:49:53 +00:00
|
|
|
<h2>Content</h2>
|
|
|
|
|
<p>The bindings are articulated around a few
|
2009-07-29 21:28:50 +00:00
|
|
|
classes in the <code>org/libvirt</code> package, notably the
|
2008-07-22 17:49:53 +00:00
|
|
|
<code>Connect</code>, <code>Domain</code> and <code>Network</code>
|
2014-12-01 13:36:13 +00:00
|
|
|
ones. Functions in the <a href="html/index.html">C API</a>
|
2008-07-22 17:49:53 +00:00
|
|
|
taking <code>virConnectPtr</code>, <code>virDomainPtr</code> or
|
|
|
|
|
<code>virNetworkPtr</code> as their first argument usually become
|
|
|
|
|
methods for the classes, their name is just stripped from the
|
|
|
|
|
virConnect or virDomain(Get) prefix and the first letter gets converted to
|
|
|
|
|
lower case, for example the C functions:</p>
|
|
|
|
|
<p>
|
2014-12-01 13:36:13 +00:00
|
|
|
<code>int <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
|
2008-07-22 17:49:53 +00:00
|
|
|
(virConnectPtr conn);</code>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2014-12-01 13:36:13 +00:00
|
|
|
<code>int <a href="html/libvirt-libvirt-domain.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
|
2008-07-22 17:49:53 +00:00
|
|
|
(virDomainPtr domain, unsigned long memory);</code>
|
|
|
|
|
</p>
|
|
|
|
|
<p>become</p>
|
|
|
|
|
<p>
|
2009-07-29 21:28:50 +00:00
|
|
|
<code>virConn.numOfDomains()</code>
|
2008-07-22 17:49:53 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2009-07-29 21:28:50 +00:00
|
|
|
<code>virDomain.setMaxMemory(long memory)</code>
|
2008-07-22 17:49:53 +00:00
|
|
|
</p>
|
|
|
|
|
<p> There is of course some functions where the mapping is less direct
|
2017-10-13 15:30:41 +00:00
|
|
|
and using extra classes to map complex arguments. The <a href="https://libvirt.org/sources/java/javadoc">Javadoc</a> is available online or as
|
2008-07-22 17:49:53 +00:00
|
|
|
part of a separate libvirt-java-javadoc package.</p>
|
|
|
|
|
<p>So let's look at a simple example inspired from the
|
|
|
|
|
<code>test.java</code> test found in <code>src</code> in the source tree:</p>
|
|
|
|
|
<pre>import <span style="color: #0071FF; background-color: #FFFFFF">org.libvirt.*</span>;
|
|
|
|
|
public class minitest {
|
|
|
|
|
public static void main(String[] args) {
|
|
|
|
|
Connect conn=null;
|
|
|
|
|
try{
|
|
|
|
|
conn = new <span style="color: #0071FF; background-color: #FFFFFF">Connect</span>("test:///default", true);
|
2014-08-20 11:00:30 +00:00
|
|
|
} catch (<span style="color: #0071FF; background-color: #FFFFFF">LibvirtException</span> e) {
|
2008-07-22 17:49:53 +00:00
|
|
|
System.out.println("exception caught:"+e);
|
|
|
|
|
System.out.println(e.getError());
|
|
|
|
|
}
|
|
|
|
|
try{
|
|
|
|
|
<span style="color: #0071FF; background-color: #FFFFFF">Domain</span> testDomain=conn.<span style="color: #007F00; background-color: #FFFFFF">domainLookupByName</span>("test");
|
|
|
|
|
System.out.println("Domain:" + testDomain.<span style="color: #E50073; background-color: #FFFFFF">getName</span>() + " id " +
|
|
|
|
|
testDomain.<span style="color: #E50073; background-color: #FFFFFF">getID</span>() + " running " +
|
|
|
|
|
testDomain.<span style="color: #E50073; background-color: #FFFFFF">getOSType</span>());
|
2014-08-20 11:00:30 +00:00
|
|
|
} catch (<span style="color: #0071FF; background-color: #FFFFFF">LibvirtException</span> e) {
|
2008-07-22 17:49:53 +00:00
|
|
|
System.out.println("exception caught:"+e);
|
|
|
|
|
System.out.println(e.getError());
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
<p>There is not much to comment about it, it really is a straight mapping
|
|
|
|
|
from the C API, the only points to notice are:</p>
|
|
|
|
|
<ul>
|
2009-07-29 21:28:50 +00:00
|
|
|
<li>the import of the modules in the <code><span style="color: #0071FF; background-color: #FFFFFF">org.libvirt</span></code> package</li>
|
2008-07-22 17:49:53 +00:00
|
|
|
<li>getting a connection to the hypervisor, in that case using the
|
|
|
|
|
readonly access to the default test hypervisor.</li>
|
|
|
|
|
<li>getting an object representing the test domain using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
|
|
|
|
|
<li>if the domain is not found a LibvirtError exception will be raised</li>
|
|
|
|
|
<li>extracting and printing some information about the domain using
|
|
|
|
|
various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
|
|
|
|
|
associated to the Domain class.</li>
|
|
|
|
|
</ul>
|
2012-09-27 20:48:17 +00:00
|
|
|
<h2>Maven</h2>
|
|
|
|
|
<p>Up until version 0.4.7 the Java bindings were available from the central maven repository.</p>
|
|
|
|
|
<p>If you want to use 0.4.8 or higher, please add the following repository to your pom.xml</p>
|
|
|
|
|
<pre><repositories>
|
|
|
|
|
<repository>
|
|
|
|
|
<id>libvirt-org</id>
|
2017-10-13 15:30:41 +00:00
|
|
|
<url>https://libvirt.org/maven2</url>
|
2012-09-27 20:48:17 +00:00
|
|
|
</repository>
|
|
|
|
|
</repositories></pre>
|
|
|
|
|
|
2008-07-22 17:49:53 +00:00
|
|
|
</body>
|
|
|
|
|
</html>
|
