Provide working example commands for Java.

This is slightly harder than for other languages, because of the way
that classpaths and JNI work; and because there isn't a standard
place to put third-party libraries.

So now we recommend that Java folks copy the JNI and jar files into
this repository's root, set their CLASSPATH environment variable,
and then run simple commands that should work on that basis.

Our example code is now in the "code.java" package, because that's
its layout on disk; otherwise we have to mess with the classpath
even more to get things to run properly.

Author: jaylett

code/java/delete1.java

@@ -1,3 +1,5 @@
+package code.java;
+
 import org.xapian.WritableDatabase;
 import org.xapian.XapianConstants;
 

code/java/index1.java

@@ -1,3 +1,5 @@
+package code.java;
+
 import java.io.File;
 import java.io.FileNotFoundException;
 import java.util.Scanner;
@@ -11,6 +13,8 @@
 import org.xapian.XapianConstants;
 import org.xapian.XapianJNI;
 
+import code.java.support;
+
 public class index1 {
 
     // Command line args - datapath dbpath

code/java/index1.java.data=2f100-objects-v1.csv_db.out

@@ -1,3 +1,5 @@
+package code.java;
+
 import org.xapian.Database;
 import org.xapian.Document;
 import org.xapian.Enquire;

code/java/search1.java

@@ -1,4 +1,6 @@
 /* Support code for Java examples */
+package code.java;
+
 import java.util.ArrayList;
 
 public class support {

code/java/support.java

@@ -325,7 +325,7 @@ def xapian_code_example_command(ex):
         return "cli-csc -unsafe -target:exe -out:%s.exe %s -r:XapianSharp.dll\n./%s.exe" \
             % (ex, xapian_code_example_filename(ex), ex)
     elif highlight_language == 'java':
-        return "javac %s\njava %s" \
+        return "javac %s\njava code.java.%s" \
             % (xapian_code_example_filename(ex), ex)
     else:
         print "Unhandled highlight_language '%s'" % highlight_language
@@ -555,8 +555,20 @@ def run(self):
 directives.register_directive('xapiancodesnippet', XapianCodeSnippet)
 
 class XapianInclude(Include):
+
+    option_spec = {
+        'optional': directives.flag,
+    }
+    option_spec.update(Include.option_spec)
+
     def run(self):
         self.arguments[0] = re.sub(r'\bLANGUAGE\b', highlight_language, self.arguments[0])
+        if 'optional' in self.options:
+            # We want to silently fail if we can't find the file.
+            # Don't bother to process this 'properly', because we should
+            # only use it with straightforward paths.
+            if not os.path.exists(directives.path(self.arguments[0])):
+                return []
         return super(XapianInclude, self).run()
 
 # Usage:

conf.py

@@ -0,0 +1,22 @@
+Since there isn't a standard location to install third-party Java
+libraries, you will likely have to set the ``CLASSPATH`` variable
+appropriately to indicate that you wish to use the Xapian Java
+bindings.
+
+There are two parts to the bindings: a jarfile (``xapian.jar``)
+containing the Java classes, and the JNI library (such as
+``libxapian_jni.so`` on Linux, or ``libxapian_jni.jnilib`` on macOS)
+that connects them to Xapian itself. The easiest way to get this
+working is to copy those two files to the top-level directory of this
+repository. If you built your own Java bindings, the files will be in
+``java/built`` in the bindings source code. Then you can use the
+following classpath (if on Linux)::
+
+  xapian.jar:libxapian_jni.so:.
+
+If you set the ``CLASSPATH`` variable to this, then the example
+commands will work as shown. For instance, if you're using the
+``bash`` shell, you should run the following before any example
+commands (again, on Linux)::
+
+  export CLASSPATH=xapian.jar:libxapian_jni.so:.

language_specific/java/running_examples.rst

@@ -123,6 +123,9 @@ examples, we provide the commands needed to compile (if necessary) and run
 the code described. These commands are intended to be run from the top-level
 directory of the source for this guide.
 
+.. xapianinclude:: language_specific/LANGUAGE/running_examples.rst
+   :optional:
+
 .. todo:: link to here from every howto and everything that needs the data files and example code
 
 Contributing