Repository

This article is part of the XQuery Portal. It shows how to add external packages to BaseX, using the EXPath Packaging API.

Introduction

The functionality of an XQuery processor can be extended with a variety of libraries. This, however, becomes often a difficult task as there is no common defined installation process and different libraries comply with different rules. EXPath addresses this problem by creating a generic mechanism for extending an XQuery processor with packages.

BaseX offers an implementation of this mechanism based on the specification created by EXPath. A package is a .xar archive encapsulating one or more extension libraries. The implementation of BaseX currently supports extensions with XQuery libraries and java libraries packed as .jar files.

Repository Commands

All packages are stored in the package repository. The repository is a directory named BaseXRepo or repo, which resides in your home directory.

BaseX provides three commands for interaction with the package repository – REPO INSTALL, REPO DELETE and REPO LIST. The syntax of these commands is described in Commands. Since Template:Mark, a Repository Module exists, which can also be used to manage packages via XQuery.

Here we give simple examples of their usage and the usage of a package after it is installed.

Installing a Package

A package can be installed using the REPO INSTALL command. The path to the package has to be given as a parameter. An example:

REPO INSTALL http://files.basex.org/modules/functx-1.0.xar

The installation will only succeed if the package fully conforms to the specification. If you know that your package is valid, you may as well unzip and copy its files directly to the repository, or edit its contents without reinstalling the package.

Using a Package

Installed packages can be addressed by importing them as modules. Since we have the package repository in which all packages are located, it is sufficient to just specify the namespace of a module:

import module namespace functx = "http://www.functx.com";

When this statement is parsed, the query processor will check if the namespace "http://www.functx.com" is used in any of the installed packages and, if yes, will load and parse the modules. In the remaining query, you can call the parsed module functions in the standard way, e.g.:

functx:capitalize-first("test")

Package encapsulating Java archives can be imported in the same way as pure XQuery modules (see below).

Deleting a Package

A package can be deleted with the command REPO DELETE and by specifying either its name or the name of its directory:

REPO DELETE http://www.functx.com  ...or...
REPO DELETE functx-1.0

Listing installed packages

All currently installed packages can be listed using the REPO LIST command. It will list the names of all packages which currently reside in the repository along with their versions:

URI                    Version  Directory
-------------------------------------------------------
http://www.functx.com  1.0      http-www.functx.com-1.0

1 package(s).

Structure

The EXPath specification defines how the structure of a .xar archive shall look like. The package contains at its root a package descriptor named expath-pkg.xml. This descriptor presents some meta data about the package as well as the libraries which it contains and their dependencies on other libraries or processors. Apart from the package descriptor a .xar archive contains a directory which includes the actual XQuery libraries. For example the FunctX XQuery Library is packaged as follows:

expath-pkg.xml
functx/
  functx.xql
  functx.xsl

In case you want to extend BaseX with a Java archive, some additional requirements have to be fulfilled:

• Apart from the package descriptor expath-pkg.xml the package has to contain at its root a descriptor defining the included jars and the binary names of the public classes from them. It has to be named basex.xml and has to have the following structure:

<package xmlns="http://expath.org/ns/pkg">
  <jar>...</jar>
    ....
    <class>...</class>
    <class>...</class>
    ....
</package>

• The jar file itself along with an XQuery file defining wrapper functions around the java methods has to reside in the module directory. The following example illustrates how java methods are wrapped with XQuery functions:

Example:
Suppose we have a simple class Printer having just one public method print():

package test;

public final class Printer {
  public String print(final String s) {
    return new Writer(s).write();
  }
}

We want to extend BaseX with this class and use its method. In order to make this possible we have to define an XQuery function which wraps the print method of our class. This can be done in the following way:

import module namespace j="http://basex.org/lib/testJar";

declare namespace p="java:test.Printer";

declare function j:print($str as xs:string) as xs:string {
  let $printer := p:new()
  return p:print($printer, $str)
};

As it can be seen, the class Printer is declared with its binary name as a namespace prefixed with "java" and the XQuery function is implemented using the Java Bindings offered by BaseX.

On our file server, you can find some example libraries packaged as XML archives (xar files). You can use them to try our packaging API or just as a reference for creating your own packages.