docs: Convert 'java' page to rST

Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
author: Peter Krempa <pkrempa@redhat.com> 2022-03-10 17:57:54 +0100
committer: Peter Krempa <pkrempa@redhat.com> 2022-04-01 16:33:20 +0200
commit: 1b2477c674127780ffe986b336415a0ebede1dff (patch)
tree: 6648ac1e76f8ef0d69e4dd860484294811e7ca68
parent: 8ec0e9a800f87033300f7a7a051d43d49399e4c9 (diff)
download: libvirt-1b2477c674127780ffe986b336415a0ebede1dff.tar.gz
3 files changed, 129 insertions, 122 deletions
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>&lt;repositories&gt;
-  &lt;repository&gt;
-    &lt;id&gt;libvirt-org&lt;/id&gt;
-    &lt;url&gt;https://libvirt.org/maven2&lt;/url&gt;
-  &lt;/repository&gt;
-&lt;/repositories&gt;</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 f1d42f8b96..1237458ac3 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -30,7 +30,6 @@ docs_html_in_files = [
   'formatstoragecaps',
   'index',
   'internals',
-  'java',
   'logging',
   'php',
   'python',
@@ -92,6 +91,7 @@ docs_rst_files = [
   'governance',
   'hacking',
   'hooks',
+  'java',
   'libvirt-go',
   'libvirt-go-xml',
   'macos',
author	Peter Krempa <pkrempa@redhat.com>	2022-03-10 17:57:54 +0100
committer	Peter Krempa <pkrempa@redhat.com>	2022-04-01 16:33:20 +0200
commit	1b2477c674127780ffe986b336415a0ebede1dff (patch)
tree	6648ac1e76f8ef0d69e4dd860484294811e7ca68
parent	8ec0e9a800f87033300f7a7a051d43d49399e4c9 (diff)
download	libvirt-1b2477c674127780ffe986b336415a0ebede1dff.tar.gz