diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod
index ae24820dc..cae70eae6 100644
--- a/java/examples/guestfs-java.pod
+++ b/java/examples/guestfs-java.pod
@@ -70,6 +70,43 @@ The output looks similar to this:
  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 EXAMPLE 1: CREATE A DISK IMAGE
 
 @EXAMPLE1@