EXPath Packaging System prototype implementation for eXist

Posted by Florent Georges, on 2009-09-12, in exist, expath and xquery.

During the past few weeks, I have been working on the Packaging System for EXPath (see also this blog entry for more info.) The concept is quite simple: defining a package format to enable users to install libraries in their processor with just a few clicks, and to enable library authors to provide a single package to be installed on every processors, without the need to document (and maintain) the installation process for each of them.

Of course, this system should be supported right into the processors themselves, as this is intimately related to the way each processor manages its queries and/or stylesheets. But to convince vendors, we first have to show something that does work, and to show that users are actually interested. So I have written a prototype implementation for eXist (as well as one for Saxon, but it still needs some cosmetic work in order to be released.)

The package manager for eXist is a graphical application (a textual front-end will be provided soon,) and is provided as a single JAR file. Go to the implementations page, or use this following direct link to get the JAR. Run it as usual, for instance by double-clicking on it or by executing the command java -jar expath-pkg-exist-0.1.jar. That will launch the package manager window.

The manager acts on an eXist instance, that is, the directory where you installed eXist on your machine (the one that contains the conf.xml file.) You can have several instances installed on a same computer, but the package manager only acts on a single one at a time. You can select it via the File menu, item Open instance. Just select the correct directory. By default, if the environment variable EXIST_HOME is set, the manager will use this directory. If not, it will display a warning and wait for you to select an instance:

The manger stores some info in a file created in the instance directory. If this file does not exist, the manager asks you to confirm to create it. That is kind of initializing this instance for the EXPath Packaging system. You can safely answer yes:

Once an eXist instance is selected, the manager shows a list of the packages installed in this instance. Using the menu, you can deleting a package previously installed, or install a new one. To install a new package, you have to select it through the file selection dialog. Package files have the *.xar extension.

In order to test the system, you can use the following packages. The first one is actually nothing else than Priscilla Walmsley's FunctX for XQuery, that I packaged (just because this is a more interesting and useful example of a library written in standard XQuery than a simple hello world example...) The second one is a simple XQuery module that use eXist extension functions (remember that a XAR is simply a ZIP file, so you can open it and see the actual XQuery file within it.) Technically, it is deployed exactly as a standard XQuery file, but in the package it is flagged as dependent on eXist. And the last one is a simple module written in Java. It provides a simple function that says hello.

If you want to test the installation, start your eXist instance (or restart it, but I would say it is safer to stop it to install packages) and try one of those queries: 

(: test the first package: FunctX... :)
import module namespace f = "http://www.functx.com";
f:date(1979, 9, 1)

(: ...or test the second package... :)
import module namespace v = "http://www.example.com/version";
v:info()

(: ...or test the third package :)
import module namespace t = "http://www.example.com/ext";
t:hello('you')

How does it work? The easiest is maybe to open the XAR files and see what they contain. For instance, the package for FunctX contains (when opened as a ZIP file) a file expath-pkg.xml and a file functx/functx-1.0-doc-2007-01.xq. The later is simply the XQuery file, exactly as you can find it on the FunctX website. The former is the package descriptor. This is a little XML file describing the content of the package. In this case, it contains: 

<package xmlns="http://expath.org/mod/expath-pkg">
   <module version="1.0" name="functx">
      <title>FunctX library for XQuery 1.0</title>
      <xquery>
         <namespace>http://www.functx.com</namespace>
         <file>functx-1.0-doc-2007-01.xq</file>
      </xquery>
   </module>
</package>

You can see that this descriptor contains the name of the library (here functx) as well as a user-friendly title, and its version number. Then the XQuery file is registered with its target namespace. This info is used by the manager to update the eXist's conf.xml file. The actual XQuery file is wrapped in a JAR file that is put in the eXist classpath, to enable eXist to find it as a resource. If you open the package descriptor of the 2 other packages, you will discover that they are slightly different (to differenciate the different kinds of libraries, in particular those written in Java.)

If you have any comment, idea or criticism, please tell us on the EXPath mailing list. I hope to release the package manager for Saxon quite soon, I will announce it on the list.

Posted by Florent Georges, on 2009-09-12T20:11:00, tags: exist, expath and xquery.