Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/java.html.in | 121 ------------------------------------------- docs/java.rst | 128 ++++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 129 insertions(+), 122 deletions(-) delete mode 100644 docs/java.html.in create mode 100644 docs/java.rst diff --git a/docs/java.html.in b/docs/java.html.in deleted file mode 100644 index 1f8c255d26..0000000000 --- a/docs/java.html.in +++ /dev/null @@ -1,121 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Java API bindings</h1> - -<h2>Presentation</h2> - <p>The Java bindings make use of <a href="https://jna.dev.java.net/";>JNA</a> - to expose the C API in a Java friendly way. The bindings are based on - work initiated by Toth Istvan.</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="https://libvirt.org/sources/java/";>libvirt.org HTTP server</a></li> -</ul> - -<h3>Maven</h3> -<p>A maven repository is located at <a href="https://libvirt.org/maven2/";>https://libvirt.org/maven2/</a> -which you can use to include this in your maven projects.</p> - -<h2>GIT source repository</h2> -<p> The Java bindings code source is now maintained in a <a -href="https://git-scm.com/";>git</a> repository available on -<a href="https://gitlab.com/libvirt/libvirt-java/";>gitlab.com</a>: -</p> -<pre> -git clone https://gitlab.com/libvirt/libvirt-java.git -</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> - -<pre> - -% cd libvirt-java -% ant build -</pre> - - -<h2>Content</h2> -<p>The bindings are articulated around a few -classes in the <code>org/libvirt</code> package, notably the -<code>Connect</code>, <code>Domain</code> and <code>Network</code> -ones. Functions in the <a href="html/index.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-domain.html#virConnectNumOfDomains">virConnectNumOfDomains</a> -(virConnectPtr conn);</code> - </p> - <p> - <code>int <a href="html/libvirt-libvirt-domain.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="https://libvirt.org/sources/java/javadoc";>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> package</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> -<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> - <url>https://libvirt.org/maven2 </url> - </repository> -</repositories></pre> - - </body> -</html> diff --git a/docs/java.rst b/docs/java.rst new file mode 100644 index 0000000000..df846c6fc6 --- /dev/null +++ b/docs/java.rst @@ -0,0 +1,128 @@ +================= +Java API bindings +================= + +.. contents:: + +Presentation +------------ + +The Java bindings make use of `JNA <https://jna.dev.java.net/>`__ to expose the +C API in a Java friendly way. The bindings are based on work initiated by Toth +Istvan. + +Getting it +---------- + +The latest versions of the libvirt Java bindings can be downloaded from: + +- `libvirt.org FTP server <ftp://libvirt.org/libvirt/java/>`__ +- `libvirt.org HTTP server <https://libvirt.org/sources/java/>`__ + +A maven repository is located at https://libvirt.org/maven2/ which you can use +to include this in your maven projects. + +GIT source repository +--------------------- + +The Java bindings code source is now maintained in a +`git <https://git-scm.com/>`__ repository available on +`gitlab.com <https://gitlab.com/libvirt/libvirt-java/>`__: + +:: + + git clone https://gitlab.com/libvirt/libvirt-java.git + +Building +-------- + +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 + +:: + + + % cd libvirt-java + % ant build + +Content +------- + +The bindings are articulated around a few classes in the ``org/libvirt`` +package, notably the ``Connect``, ``Domain`` and ``Network`` ones. Functions in +the `C API <html/index.html>`__ taking ``virConnectPtr``, ``virDomainPtr`` or +``virNetworkPtr`` 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: + +``int virConnectNumOfDomains (virConnectPtr conn);`` + +``int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);`` + +become + +``virConn.numOfDomains()`` + +``virDomain.setMaxMemory(long memory)`` + +There is of course some functions where the mapping is less direct and using +extra classes to map complex arguments. The +`Javadoc <https://libvirt.org/sources/java/javadoc>`__ is available online or as +part of a separate libvirt-java-javadoc package. + +So let's look at a simple example inspired from the ``test.java`` test found in +``src`` in the source tree: + +:: + + import org.libvirt.*; + public class minitest { + public static void main(String[] args) { + Connect conn=null; + try{ + conn = new Connect("test:///default", true); + } catch (LibvirtException e) { + System.out.println("exception caught:"+e); + System.out.println(e.getError()); + } + try{ + Domain testDomain=conn.domainLookupByName("test"); + System.out.println("Domain:" + testDomain.getName() + " id " + + testDomain.getID() + " running " + + testDomain.getOSType()); + } catch (LibvirtException e) { + System.out.println("exception caught:"+e); + System.out.println(e.getError()); + } + } + } + +There is not much to comment about it, it really is a straight mapping from the +C API, the only points to notice are: + +- the import of the modules in the ``org.libvirt`` package +- getting a connection to the hypervisor, in that case using the readonly + access to the default test hypervisor. +- getting an object representing the test domain using ``lookupByName`` +- if the domain is not found a LibvirtError exception will be raised +- extracting and printing some information about the domain using various + methods associated to the Domain class. + +Maven +----- + +Up until version 0.4.7 the Java bindings were available from the central maven +repository. + +If you want to use 0.4.8 or higher, please add the following repository to your +pom.xml + +:: + + <repositories> + <repository> + <id>libvirt-org</id> + <url>https://libvirt.org/maven2</url> + </repository> + </repositories> diff --git a/docs/meson.build b/docs/meson.build index a0e96e2453..e1b618438c 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -27,7 +27,6 @@ docs_html_in_files = [ 'formatnwfilter', 'index', 'internals', - 'java', 'logging', 'php', 'python', @@ -92,6 +91,7 @@ docs_rst_files = [ 'governance', 'hacking', 'hooks', + 'java', 'libvirt-go', 'libvirt-go-xml', 'macos', -- 2.35.1
