java: Add guestfs-java(3) man page.

15 files changed, 332 insertions, 2 deletions

diff --git a/.gitignore b/.gitignore
index 19d971b3..4777a4fa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -118,6 +118,7 @@ haskell/Guestfs.hs
 html/guestfish.1.html
 html/guestfs.3.html
 html/guestfs-examples.3.html
+html/guestfs-java.3.html
 html/guestfs-ocaml.3.html
 html/guestfs-perl.3.html
 html/guestfs-python.3.html
@@ -182,6 +183,8 @@ java/com/redhat/et/libguestfs/Version.java
 java/com/redhat/et/libguestfs/VG.java
 java/com/redhat/et/libguestfs/XAttr.java
 java/doc-stamp
+java/examples/guestfs-java.3
+java/examples/stamp-guestfs-java.pod
 *.la
 libguestfs.pc
 libguestfs.spec
diff --git a/Makefile.am b/Makefile.am
index baa6f60b..e1ddf0da 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -52,7 +52,7 @@ if HAVE_RUBY
 SUBDIRS += ruby ruby/examples
 endif
 if HAVE_JAVA
-SUBDIRS += java
+SUBDIRS += java java/examples
 endif
 if HAVE_HASKELL
 SUBDIRS += haskell
@@ -131,6 +131,7 @@ EXTRA_DIST = \
 HTMLFILES = \
 	html/guestfs.3.html \
 	html/guestfs-examples.3.html \
+	html/guestfs-java.3.html \
 	html/guestfs-ocaml.3.html \
 	html/guestfs-perl.3.html \
 	html/guestfs-python.3.html \
diff --git a/configure.ac b/configure.ac
index fc94224e..57ae0a91 100644
--- a/configure.ac
+++ b/configure.ac
@@ -819,6 +819,7 @@ AC_CONFIG_FILES([Makefile
                  images/Makefile
                  inspector/Makefile
                  java/Makefile
+                 java/examples/Makefile
                  libguestfs.pc
                  ocaml/META
                  ocaml/Makefile
diff --git a/examples/guestfs-examples.pod b/examples/guestfs-examples.pod
index 775675e9..39259e16 100644
--- a/examples/guestfs-examples.pod
+++ b/examples/guestfs-examples.pod
@@ -33,6 +33,7 @@ libguestfs, you also need to read L<guestfs(3)>.
 =head1 SEE ALSO
 
 L<guestfs(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-python(3)>,
diff --git a/examples/guestfs-recipes.pod b/examples/guestfs-recipes.pod
index 595c2c48..97a80533 100644
--- a/examples/guestfs-recipes.pod
+++ b/examples/guestfs-recipes.pod
@@ -386,6 +386,7 @@ https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#c
 L<guestfs(3)>,
 L<guestfish(1)>,
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-python(3)>,
diff --git a/java/examples/CreateDisk.java b/java/examples/CreateDisk.java
new file mode 100644
index 00000000..4742b5a1
--- /dev/null
+++ b/java/examples/CreateDisk.java
@@ -0,0 +1,87 @@
+// Example showing how to create a disk image.
+
+import java.io.*;
+import java.util.Map;
+import java.util.HashMap;
+import com.redhat.et.libguestfs.*;
+
+public class CreateDisk
+{
+    static String output = "disk.img";
+
+    public static void main (String[] argv)
+    {
+        try {
+            GuestFS g = new GuestFS ();
+
+            // Create a raw-format sparse disk image, 512 MB in size.
+            RandomAccessFile f = new RandomAccessFile (output, "rw");
+            f.setLength (512 * 1024 * 1024);
+            f.close ();
+
+            // Set the trace flag so that we can see each libguestfs call.
+            g.set_trace (true);
+
+            // Set the autosync flag so that the disk will be synchronized
+            // automatically when the libguestfs handle is closed.
+            g.set_autosync (true);
+
+            // Attach the disk image to libguestfs.
+            Map<String, Object> optargs = new HashMap<String, Object>() {
+                {
+                    put ("format", "raw");
+                    put ("readonly", Boolean.FALSE);
+                }
+            };
+            g.add_drive_opts (output, optargs);
+
+            // Run the libguestfs back-end.
+            g.launch ();
+
+            // Get the list of devices.  Because we only added one drive
+            // above, we expect that this list should contain a single
+            // element.
+            String[] devices = g.list_devices ();
+            if (devices.length != 1)
+                throw new Error ("expected a single device from list-devices");
+
+            // Partition the disk as one single MBR partition.
+            g.part_disk (devices[0], "mbr");
+
+            // Get the list of partitions.  We expect a single element, which
+            // is the partition we have just created.
+            String[] partitions = g.list_partitions ();
+            if (partitions.length != 1)
+                throw new Error ("expected a single partition from list-partitions");
+
+            // Create a filesystem on the partition.
+            g.mkfs ("ext4", partitions[0]);
+
+            // Now mount the filesystem so that we can add files.
+            g.mount_options ("", partitions[0], "/");
+
+            // Create some files and directories.
+            g.touch ("/empty");
+            String message = "Hello, world\n";
+            g.write ("/hello", message.getBytes());
+            g.mkdir ("/foo");
+
+            // This one uploads the local file /etc/resolv.conf into
+            // the disk image.
+            g.upload ("/etc/resolv.conf", "/foo/resolv.conf");
+
+            // Because 'autosync' was set (above) we can just close the handle
+            // and the disk contents will be synchronized.  You can also do
+            // this manually by calling g#umount_all and g#sync.
+            //
+            // Note also that handles are automatically closed if they are
+            // reaped by the garbage collector.  You only need to call close
+            // if you want to close the handle right away.
+            g.close ();
+        }
+        catch (Exception exn) {
+            System.err.println (exn);
+            System.exit (1);
+        }
+    }
+}
diff --git a/java/examples/InspectVM.java b/java/examples/InspectVM.java
new file mode 100644
index 00000000..d92aa70f
--- /dev/null
+++ b/java/examples/InspectVM.java
@@ -0,0 +1,99 @@
+// Example showing how to inspect a virtual machine disk.
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.redhat.et.libguestfs.*;
+
+public class InspectVM
+{
+    static final Comparator<String> COMPARE_KEYS_LEN =
+        new Comparator<String>() {
+        public int compare (String k1, String k2) {
+            return k1.length() - k2.length();
+        }
+    };
+
+    public static void main (String[] argv)
+    {
+        try {
+            if (argv.length != 1)
+                throw new Error ("usage: InspectVM disk.img");
+
+            String disk = argv[0];
+
+            GuestFS g = new GuestFS ();
+
+            // Attach the disk image read-only to libguestfs.
+            Map<String, Object> optargs = new HashMap<String, Object>() {
+                {
+                    //put ("format", "raw");
+                    put ("readonly", Boolean.TRUE);
+                }
+            };
+
+            g.add_drive_opts (disk, optargs);
+
+            // Run the libguestfs back-end.
+            g.launch ();
+
+            // Ask libguestfs to inspect for operating systems.
+            String roots[] = g.inspect_os ();
+            if (roots.length == 0)
+                throw new Error ("inspect_vm: no operating systems found");
+
+            for (String root : roots) {
+                System.out.println ("Root device: " + root);
+
+                // Print basic information about the operating system.
+                System.out.println ("  Product name: " +
+                                    g.inspect_get_product_name (root));
+                System.out.println ("  Version:      " +
+                                    g.inspect_get_major_version (root) +
+                                    "." +
+                                    g.inspect_get_minor_version (root));
+                System.out.println ("  Type:         " +
+                                    g.inspect_get_type (root));
+                System.out.println ("  Distro:       " +
+                                    g.inspect_get_distro (root));
+
+                // Mount up the disks, like guestfish -i.
+                //
+                // Sort keys by length, shortest first, so that we end up
+                // mounting the filesystems in the correct order.
+                Map<String,String> mps = g.inspect_get_mountpoints (root);
+                List<String> mps_keys = new ArrayList (mps.keySet ());
+                Collections.sort (mps_keys, COMPARE_KEYS_LEN);
+
+                for (String mp : mps_keys) {
+                    String dev = mps.get (mp);
+                    try {
+                        g.mount_ro (dev, mp);
+                    }
+                    catch (Exception exn) {
+                        System.err.println (exn + " (ignored)");
+                    }
+                }
+
+                // If /etc/issue.net file exists, print up to 3 lines.
+                String filename = "/etc/issue.net";
+                if (g.is_file (filename)) {
+                    System.out.println ("--- " + filename + " ---");
+                    String[] lines = g.head_n (3, filename);
+                    for (String line : lines)
+                        System.out.println (line);
+                }
+
+                // Unmount everything.
+                g.umount_all ();
+            }
+        }
+        catch (Exception exn) {
+            System.err.println (exn);
+            System.exit (1);
+        }
+    }
+}
diff --git a/java/examples/LICENSE b/java/examples/LICENSE
new file mode 100644
index 00000000..f8106cdc
--- /dev/null
+++ b/java/examples/LICENSE
@@ -0,0 +1,2 @@
+All the examples in the 'java/examples' subdirectory may be freely
+copied, modified and distributed without any restrictions.
diff --git a/java/examples/Makefile.am b/java/examples/Makefile.am
new file mode 100644
index 00000000..503b55d8
--- /dev/null
+++ b/java/examples/Makefile.am
@@ -0,0 +1,50 @@
+# libguestfs Java examples
+# Copyright (C) 2011 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+EXTRA_DIST = \
+	LICENSE \
+	CreateDisk.java \
+	InspectVM.java \
+	guestfs-java.pod
+
+CLEANFILES = \
+	*.class \
+	stamp-guestfs-java.pod
+
+man_MANS = guestfs-java.3
+noinst_DATA = $(top_builddir)/html/guestfs-java.3.html
+
+guestfs-java.3 $(top_builddir)/html/guestfs-java.3.html: stamp-guestfs-java.pod
+
+stamp-guestfs-java.pod: guestfs-java.pod CreateDisk.java InspectVM.java
+	$(top_srcdir)/podwrapper.sh \
+	  --section 3 \
+	  --man guestfs-java.3 \
+	  --html $(top_builddir)/html/guestfs-java.3.html \
+	  --verbatim CreateDisk.java:@EXAMPLE1@ \
+	  --verbatim InspectVM.java:@EXAMPLE2@ \
+	  $<
+	touch $@
+
+if HAVE_JAVA
+
+noinst_SCRIPTS = CreateDisk.class InspectVM.class
+
+%.class: %.java
+	$(JAVAC) $(JAVAC_FLAGS) -classpath ../libguestfs-$(VERSION).jar $<
+
+endif
diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod
new file mode 100644
index 00000000..abf62db6
--- /dev/null
+++ b/java/examples/guestfs-java.pod
@@ -0,0 +1,80 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfs-java - How to use libguestfs from Java
+
+=head1 SYNOPSIS
+
+ import com.redhat.et.libguestfs.*;
+ 
+ GuestFS g = new GuestFS ();
+ g.add_drive_opts ("disk.img", null);
+ 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.
+
+=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-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 Red Hat Inc. L<http://libguestfs.org/>
+
+The examples in this manual page may be freely copied, modified and
+distributed without any restrictions.
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod
index f0cffe9c..0978650c 100644
--- a/ocaml/examples/guestfs-ocaml.pod
+++ b/ocaml/examples/guestfs-ocaml.pod
@@ -79,6 +79,7 @@ function that you called.
 
 L<guestfs(3)>,
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-python(3)>,
 L<guestfs-recipes(1)>,
diff --git a/perl/examples/guestfs-perl.pod b/perl/examples/guestfs-perl.pod
index cf3011aa..0973382c 100644
--- a/perl/examples/guestfs-perl.pod
+++ b/perl/examples/guestfs-perl.pod
@@ -41,6 +41,7 @@ C<croak> (see L<Carp(3)>).
 L<Sys::Guestfs(3)>,
 L<guestfs(3)>,
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-python(3)>,
 L<guestfs-recipes(1)>,
diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod
index 7b9e03b5..cab7e9b9 100644
--- a/python/examples/guestfs-python.pod
+++ b/python/examples/guestfs-python.pod
@@ -43,6 +43,7 @@ Type:
 
 L<guestfs(3)>,
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-recipes(1)>,
diff --git a/ruby/examples/guestfs-ruby.pod b/ruby/examples/guestfs-ruby.pod
index 29660314..9197f9b7 100644
--- a/ruby/examples/guestfs-ruby.pod
+++ b/ruby/examples/guestfs-ruby.pod
@@ -37,6 +37,7 @@ string).
 
 L<guestfs(3)>,
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-python(3)>,
diff --git a/src/guestfs.pod b/src/guestfs.pod
index f480cce3..db9d8f06 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -728,7 +728,7 @@ and we are looking for help to complete this binding.
 =item B<Java>
 
 Full documentation is contained in the Javadoc which is distributed
-with libguestfs.
+with libguestfs.  For examples, see L<guestfs-java(3)>.
 
 =item B<OCaml>
 
@@ -3011,6 +3011,7 @@ enough.
 =head1 SEE ALSO
 
 L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
 L<guestfs-python(3)>,