mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 22:25:25 +00:00
161 lines
6.5 KiB
XML
161 lines
6.5 KiB
XML
<?xml version="1.0"?>
|
|
<html>
|
|
<body>
|
|
<h1>Java API bindings</h1>
|
|
|
|
<h2>Presentation</h2>
|
|
<p>The Java bindings are currently a work in progress based mostly
|
|
on the work of Toth Istvan. The first usable release is 0.2.0, where
|
|
most of the naming conventions were defined. Further release will try
|
|
as much as possible to stay compatible</p>
|
|
|
|
<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>
|
|
<li><a href="http://libvirt.org/sources/java/">libvirt.org HTTP server</a></li>
|
|
</ul>
|
|
|
|
<h2>Hourly development snapshots</h2>
|
|
<p> Once an hour, an automated snapshot is made from the latest CVS server
|
|
source tree. These snapshots should be usable, but we make no guarantees
|
|
about their stability: </p>
|
|
|
|
<ul>
|
|
<li><a href="ftp://libvirt.org/libvirt/java/libvirt-java-snapshot.tar.gz">libvirt.org FTP server</a></li>
|
|
<li><a href="http://libvirt.org/sources/java/libvirt-java-snapshot.tar.gz">libvirt.org HTTP server</a></li>
|
|
</ul>
|
|
|
|
<h2>CVS repository access</h2>
|
|
|
|
<p> The master source repository uses <a
|
|
href="http://ximbiot.com/cvs/cvshome/docs/">CVS</a> and anonymous access
|
|
is provided. Prior to accessing the server is it necessary to authenticate
|
|
using the password <code>anoncvs</code>. This can be accomplished with
|
|
the <code>cvs login</code> command:
|
|
</p>
|
|
|
|
<pre>
|
|
# cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs login
|
|
</pre>
|
|
|
|
<p>
|
|
Once authenticated, a checkout can be obtained using
|
|
</p>
|
|
|
|
<pre>
|
|
|
|
# cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt-java
|
|
</pre>
|
|
|
|
<p>
|
|
The libvirt-java build process uses GNU autotools, so after obtaining a checkout
|
|
it is necessary to generate the configure script and Makefile.in templates
|
|
using the <code>autogen.sh</code> command. As an example, to do a complete
|
|
build and install it into your home directory run:
|
|
</p>
|
|
<pre>
|
|
./autogen.sh --prefix=$HOME/usr
|
|
make
|
|
make install
|
|
</pre>
|
|
<p>Other build system are not currently available but as usual we take patches
|
|
(Eclipse/ant/...) would be welcome !</p>
|
|
<p> currently libvirt-java requires a version of libvirt >= 0.4.0 to be
|
|
installed as well as the associated libvirt development files/package. It
|
|
should compile with any java implementation >= 1.5, the bindings uses
|
|
the enum construct which appeared only in that version.</p>
|
|
<p>Libvirt-java bindings development occurs on the same mailing-list as
|
|
the normal libvirt work see <a href="contact.html">the associated contact
|
|
page</a></p>
|
|
|
|
<h2>GIT repository mirror</h2>
|
|
|
|
<p>
|
|
The CVS source repository is also mirrored using GIT, and is available
|
|
for anonymous access via:
|
|
</p>
|
|
|
|
<pre>
|
|
git clone git://git.et.redhat.com/libvirt-java
|
|
</pre>
|
|
|
|
<p>
|
|
It can also be browsed at
|
|
</p>
|
|
|
|
<pre>
|
|
|
|
<a href="http://git.et.redhat.com/?p=libvirt-java.git;a=summary">http://git.et.redhat.com/?p=libvirt-java.git;a=summary</a>
|
|
</pre>
|
|
|
|
<h2>Content</h2>
|
|
<p>The bindings are articulated around a few
|
|
classes in the <code>org/libvirt</code> namespace, notably the
|
|
<code>Connect</code>, <code>Domain</code> and <code>Network</code>
|
|
ones. Functions in the <a href="html/libvirt-libvirt.html">C API</a>
|
|
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>
|
|
<code>int <a href="html/libvirt-libvirt.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
|
|
(virConnectPtr conn);</code>
|
|
</p>
|
|
<p>
|
|
<code>int <a href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
|
|
(virDomainPtr domain, unsigned long memory);</code>
|
|
</p>
|
|
<p>become</p>
|
|
<p>
|
|
<code>virConn::numOfDomains()</code>
|
|
</p>
|
|
<p>
|
|
<code>virDomain::setMaxMemory(long memory)</code>
|
|
</p>
|
|
<p> There is of course some functions where the mapping is less direct
|
|
and using extra classes to map complex arguments. The <a href="http://libvirt.org/org/libvirt/package-summary.html">Javadoc</a> is available online or as
|
|
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);
|
|
} catch (<span style="color: #0071FF; background-color: #FFFFFF">LibvirtException</span> e){
|
|
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>());
|
|
} catch (<span style="color: #0071FF; background-color: #FFFFFF">LibvirtException</span> e){
|
|
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>
|
|
<li>the import of the modules in the <code><span style="color: #0071FF; background-color: #FFFFFF">org.libvirt</span></code> namespace</li>
|
|
<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>
|
|
</body>
|
|
</html>
|