diff --git a/ChangeLog b/ChangeLog index a91cc3fefd..d4fbf64c21 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Jul 22 19:48:51 CEST 2008 Daniel Veillard + + * docs/java.html docs/java.html.in: added documentation for the + java bindings + Tue Jul 22 18:11:13 CEST 2008 Jim Meyering better diagnostic when failing to undefine a running domain via ID diff --git a/docs/java.html b/docs/java.html new file mode 100644 index 0000000000..2b0c15f20a --- /dev/null +++ b/docs/java.html @@ -0,0 +1,236 @@ + + + + + + + + + libvirt: Java API bindings + + + + +
+ +
+

Java API bindings

+

Presentation

+

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. Futher release will try +as much as possible to stay compatible

+

Getting it

+

+ The latest versions of the libvirt Java bindings can be downloaded from: +

+ +

Hourly development snapshots

+

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:

+ +

CVS repository access

+

The master source repository uses CVS and anonymous access +is provided. Prior to accessing the server is it necessary to authenticate +using the password anoncvs. This can be accomplished with +the cvs login command: +

+ 
+  # cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs login
+
+

+ Once authenticated, a checkout can be obtained using +

+ 
+
+  # cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt-java
+
+

+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 autogen.sh command. As an example, to do a complete +build and install it into your home directory run: +

+ 
+  ./autogen.sh --prefix=$HOME/usr
+  make
+  make install
+
+

Other build system are not currently available but as usual we take patches +(Eclipse/ant/...) would be welcome !

+

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.

+

Libvirt-java bindings development occurs on the same mailing-list as +the normal libvirt work see the associated contact +page

+

GIT repository mirror

+

+ The CVS source repository is also mirrored using GIT, and is available + for anonymous access via: +

+ 
 
+  git clone git://git.et.redhat.com/libvirt-java
+
+

+ It can also be browsed at +

+ 
+
+  http://git.et.redhat.com/?p=libvirt-java.git;a=summary
+
+

Content

+

The bindings are articulated around a few +classes in the org/libvirt namespace, 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:

+ 
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 namespace
  • 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.
+
+
+ + + diff --git a/docs/java.html.in b/docs/java.html.in new file mode 100644 index 0000000000..316070cf35 --- /dev/null +++ b/docs/java.html.in @@ -0,0 +1,160 @@ + + + +

Java API bindings

+ +

Presentation

+

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. Futher release will try +as much as possible to stay compatible

+ +

Getting it

+

+ The latest versions of the libvirt Java bindings can be downloaded from: +

+ + + +

Hourly development snapshots

+

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:

+ + + +

CVS repository access

+ +

The master source repository uses CVS and anonymous access +is provided. Prior to accessing the server is it necessary to authenticate +using the password anoncvs. This can be accomplished with +the cvs login command: +

+ +
+  # cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs login
+
+ +

+ Once authenticated, a checkout can be obtained using +

+ +
+
+  # cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt-java
+
+ +

+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 autogen.sh command. As an example, to do a complete +build and install it into your home directory run: +

+
+  ./autogen.sh --prefix=$HOME/usr
+  make
+  make install
+
+

Other build system are not currently available but as usual we take patches +(Eclipse/ant/...) would be welcome !

+

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.

+

Libvirt-java bindings development occurs on the same mailing-list as +the normal libvirt work see the associated contact +page

+ +

GIT repository mirror

+ +

+ The CVS source repository is also mirrored using GIT, and is available + for anonymous access via: +

+ +
 
+  git clone git://git.et.redhat.com/libvirt-java
+
+ +

+ It can also be browsed at +

+ +
+
+  http://git.et.redhat.com/?p=libvirt-java.git;a=summary
+
+ +

Content

+

The bindings are articulated around a few +classes in the org/libvirt namespace, 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:

+ 
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:

+ + +