From nobody Mon Feb 9 11:05:52 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1648469501; cv=none; d=zohomail.com; s=zohoarc; b=XFbReN11u35K+GZnmUA8ik5NNXO5hIRawNn4ccTxp/r1q+xtF1QuCPtBRtvzT3rVyZQwLj8SPpt12/u0kpVPwROrrbMJj+1cDGNF6huxl2omqjc5MzaGSmM1qLfoLoRmGtq6JYGMIqyuY41h693rWUjMYPwN9IneHfetQ/8+aPo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469501; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=jY9merixyPCCndkp821uOXQCU2/ezUhIx0JxzFgJ7CI=; b=EiLgj6VfulpVdVaN+LhT4FlE5vOTFQfBZpucZeNecWZ32gRRBPhu/phtqOEMUZz/8nVuMCOB9eVpiLQzWwOervfJMFg2KHkbk330cBjWjDwj4J2oCtfyDj7chLSdDYpSfcKiZGIKKvCXCJ9lFc3SzF2Jvu7l2mFUHXoxERExIHw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1648469501178316.4434237949205; Mon, 28 Mar 2022 05:11:41 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-447-5INTuhbjPamTE369-Sqaag-1; Mon, 28 Mar 2022 08:11:16 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 034F02A59574; Mon, 28 Mar 2022 12:11:14 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id E0B1A401DBC; Mon, 28 Mar 2022 12:11:13 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 363FC1940379; Mon, 28 Mar 2022 12:11:13 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 8CEF51940344 for ; Mon, 28 Mar 2022 12:11:12 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 7F986145455A; Mon, 28 Mar 2022 12:11:12 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0B2BE141DC29 for ; Mon, 28 Mar 2022 12:11:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469499; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=jY9merixyPCCndkp821uOXQCU2/ezUhIx0JxzFgJ7CI=; b=P6rlu+Af3lGxWtQbHwhV67bRZgf15DjMToRdbkfkvLZxlQfpatw2lznELwVKGCqG/kM4su bzloYehwmb19DE/MVpDo+fsaz+AtDk2K7ZrATwA7WH3GWp+p4HZg8hTgj6XV3CdTgL84gX h+wZXmSfiMIzTtf3Xr5eDJXpf50gIow= X-MC-Unique: 5INTuhbjPamTE369-Sqaag-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 26/29] docs: Convert 'java' page to rST Date: Mon, 28 Mar 2022 14:10:41 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469502754100001 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 @@ - - - - -

Java API bindings

- -

Presentation

-

The Java bindings make use of JNA - 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: -

- - - -

Maven

-

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 repository available on -gitlab.com: -

-
-git clone https://gitlab.com/libvirt/libvirt-java.git
-
- -

Building

-

The code is built using ant, and assumes that you have the jna jar inst= alled. 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 -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 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:<= /p> - 

import =
org.libvirt.*;
-public class minitest {
-    public static void main(String[] args) {
-        Connect conn=3Dnull;
-        try{
-            conn =3D new Connect("test:///default", true);
-        } catch (LibvirtException e) {
-            System.out.println("exception caught:"+e);
-            System.out.println(e.getError());
-        }
-        try{
-            Doma=
in testDomain=3Dconn.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 mapp= ing -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 rais= ed
    • -
  • extracting and printing some information about the domain using - various meth= ods - associated to the Domain class.
    • -
-

Maven

-

Up until version 0.4.7 the Java bindings were available from the cent= ral maven repository.

-

If you want to use 0.4.8 or higher, please add the following reposito= ry to your pom.xml

- 
<repositories>
-  <repository>
-    <id>libvirt-org</id>
-    <url>https://libvirt.org/maven2 </url>
-  </repository>
-</repositories>
- - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Java API bindings +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Presentation +------------ + +The Java bindings make use of `JNA `__ to expos= e 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 `__ +- `libvirt.org HTTP server `__ + +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 `__ repository available on +`gitlab.com `__: + +:: + + git clone https://gitlab.com/libvirt/libvirt-java.git + +Building +-------- + +The code is built using ant, and assumes that you have the jna jar install= ed. +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. Functio= ns in +the `C API `__ 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 usi= ng +extra classes to map complex arguments. The +`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 fou= nd in +``src`` in the source tree: + +:: + + import org.libvirt.*; + public class minitest { + public static void main(String[] args) { + Connect conn=3Dnull; + try{ + conn =3D new Connect("test:///default", true); + } catch (LibvirtException e) { + System.out.println("exception caught:"+e); + System.out.println(e.getError()); + } + try{ + Domain testDomain=3Dconn.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 fro= m 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 m= aven +repository. + +If you want to use 0.4.8 or higher, please add the following repository to= your +pom.xml + +:: + + + + libvirt-org + https://libvirt.org/maven2 + + 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 =3D [ 'formatnwfilter', 'index', 'internals', - 'java', 'logging', 'php', 'python', @@ -92,6 +91,7 @@ docs_rst_files =3D [ 'governance', 'hacking', 'hooks', + 'java', 'libvirt-go', 'libvirt-go-xml', 'macos', --=20 2.35.1