[PATCH 26/29] docs: Convert 'java' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 28 12:10:41 UTC 2022
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
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
More information about the libvir-list
mailing list