=head1 NAME

guestfs-java - How to use libguestfs from Java

=head1 SYNOPSIS

 import com.redhat.et.libguestfs.*;
 
 GuestFS g = new GuestFS ();
 g.add_drive ("disk.img",
              new HashMap<String,Object>() {
                {
                    put ("readonly", Boolean.TRUE);
                    put ("format", "raw");
                }
              });
 g.launch ();

=head1 DESCRIPTION

This manual page documents how to call libguestfs from the Java
programming language.  This page just documents the differences from
the C API and gives some examples.  If you are not familiar with using
libguestfs, you also need to read L<guestfs(3)>.

=head2 CLOSING THE HANDLE

The handle is closed when it is reaped by the garbage collector.
Because libguestfs handles include a lot of state, it is also
possible to close (and hence free) them explicitly by calling
the C<close> method.

=head2 EXCEPTIONS

Errors from libguestfs functions are mapped into the
C<LibGuestFSException> exception.  This has a single parameter which
is the error message (a C<String>).

Calling any method on a closed handle raises the same exception.

If L<malloc(3)> or some other allocation fails inside the bindings,
the C<LibGuestFSOutOfMemory> exception is thrown.

=head2 EVENTS

The L<libguestfs event API|guestfs(3)/EVENTS> is fully supported from
Java.  Create a class which implements the C<EventCallback> interface,
create an instance of this class, and then call the C<GuestFS#set_event_callback>
method to register this instance.  The C<event> method of the class is
called when libguestfs generates an event.

For example, this will print all trace events:

 GuestFS g = new GuestFS ();
 g.set_trace (true);
 g.set_event_callback (
   new EventCallback () {
     public void event (long event, int eh,
                        String buffer, long[] array) {
       System.out.println (GuestFS.eventToString (event) +
                           ": " + buffer);
     }
   },
   GuestFS.EVENT_TRACE);
 g.add_drive_ro ("disk.img");
 // etc.

The output looks similar to this:

 EVENT_TRACE: add_drive_ro "disk.img"
 EVENT_TRACE: add_drive_ro = 0
 // etc.

=head2 OPTIONAL ARGUMENTS

Some methods take an optional map of optional parameters.  An example
of this is C<g.add_drive> which can be called in one of two ways:

 g.add_drive ("disk.img");

or with optional arguments:

 Map<String, Object> optargs =
   new HashMap<String, Object>() {
   {
     put ("readonly", Boolean.TRUE);
     put ("format", "raw");
   }
 };
 g.add_drive ("disk.img", optargs);

For more information on this topic, see
L<guestfs(3)/CALLS WITH OPTIONAL ARGUMENTS>.

=head3 Optional handle parameters

When creating the handle you can also pass a map of optional
parameters:

 Map<String, Object> optargs =
   new HashMap<String, Object>() {
   {
     put ("close_on_exit", Boolean.FALSE);
     put ("environment", Boolean.TRUE);
   }
 };
 GuestFS g = new GuestFS (optargs);

For more information, see L<guestfs(3)/guestfs_create_flags>.

=head1 COMPILING AND RUNNING

Libguestfs for Java is a Java Native Interface (JNI) extension,
supplied in three parts:

=over 4

=item F<libguestfs.jar>

=item F<libguestfs-I<VERSION>.jar>

The pure Java JAR file which contains several classes, the primary one
being C<com.redhat.et.libguestfs.GuestFS>.  Upstream, the JAR file
contains a version number in the filename, but some Linux distros may
rename it without the version number.

=item F<libguestfs_jni.so>

The JNI code (written in C).  This contains private native functions
that interface between Java code and the regular libguestfs C library.
You should B<not> call these directly.

=item F<libguestfs.so>

The regular libguestfs C library.

=back

To compile your Java program, you need to locate the JAR file and add
it to the class path.  For example:

 export CLASSPATH=/usr/share/java/libguestfs.jar
 javac MyProgram.java

To run your Java program, you also need to ensure that the JAR file is
on the class path, as well as the path of your program.  For example:

 export CLASSPATH=.:/usr/share/java/libguestfs.jar
 java MyProgram

=head1 EXAMPLE 1: CREATE A DISK IMAGE

@EXAMPLE1@

=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

@EXAMPLE2@

=head1 SEE ALSO

L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
L<guestfs-golang(3)>,
L<guestfs-lua(3)>,
L<guestfs-ocaml(3)>,
L<guestfs-perl(3)>,
L<guestfs-python(3)>,
L<guestfs-recipes(1)>,
L<guestfs-ruby(3)>,
L<http://libguestfs.org/>,
L<http://caml.inria.fr/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2011-2025 Red Hat Inc.