Friday, July 31, 2009

eXist extension functions in Java

Investigating into opportunities for an implementation of EXPath
Packaging for eXist, I am
looking at the way to implement extension functions with Java. I
detail here the key points I found to write Java extensions for eXist
using NetBeans. But those info should be generic enough to be used
with any Java IDE.

If you want to provide an extension function written in Java within
eXist, you actually have to provide a full module in Java. You cannot
provide the module part in XQuery and part in Java (though you can
provide an XQuery module that imports a private module written in
Java.)

The module is represented by a class that extends the eXist abstract
class AbstractInternalModule.
Along some information like the namespace URI of the module, the
default prefix to use, and a description, you have to provide a list
of extension functions through the base class constructor:

This module contains one single function, implemented by the class
SimpleFunction. An extension function is a Java class
that extends the eXist abstract class BasicFunction.
It has to provide some information to the base class constructor (its
qualified name, a documentation string, its parameter list and its
return type.) The logic of the function itself is located in the
eval
function:

In order to compile those files with NetBeans, you have to add two JAR
files to the build path of the project you used for those files.
Right-click on the project and choose Properties, then
Libraries and the button Add JAR/Folder.
You will find the JARs in the eXist install directory:
$EXIST_HOME/exist.jar and
$EXIST_HOME/lib/core/xmldb.jar. Then you compile your
project to get the JAR file with your both class (the module and its
single function) compiled. The best choice for the project's type is
a library of Java classes.

Now you have the JAR file containing the Java implementation of your
module and its function. The next step is to plug them within an
eXist instance. Copy the JAR file to
$EXIST_HOME/lib/extensions/ and configure it in
$EXIST_HOME/conf.xml. The configuration only requires to
add a new module element to the
builtin-modules element:

This will call the method eval on a SimpleFunction
object, discovered through a SimpleModule object
configured in conf.xml. Soon, you should be able to
package the JAR file to an EXPath package and install it within eXist
through a graphical console...