1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
=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-gobject(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-2023 Red Hat Inc.
|
