Repository

From BaseX Documentation
Revision as of 10:19, 19 October 2011 by Michael (talk | contribs) (→‎Interacting with the package repository: repo commands are no longer available only inside the snapshot)
Jump to navigation Jump to search

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.

What is a package?

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.

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 library, 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://www.basex.org/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.

Here you can find the FunctX library packaged as a .xar and a sample package containing a .jar file. You can use them to try our packaging API or just as a reference if you want to create your own packages.

Package repository

Unzipped packages are stored in the package repository. This is a directory named BaseXRepo, which is located in your home folder. Depending on your Configuration, the location of your home folder varies.

Interacting with the package repository

Now after you know what is a package and where it is stored, it comes the question how can you install and make use of such packages. BaseX offers three commands for interaction with the package repository - REPO INSTALL, REPO DELETE and REPO LIST. The syntax of these commands is described in Commands. Here we give just 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 on the file system has to be given as a parameter. An example:

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

Using a package

The functionality offered by an already installed package can be used by a module import. Since we have the package repository where all packages reside, it is not needed to indicate the exact place of the module you want to use. It is enough to just import its namespace:

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

At "seeing" this statement BaseX will check if the namespace "http://www.functx.com" is used in some of the installed packages and if yes, it will load their modules. After that you can call the functions from a module in the standard way, e.g:

functx:capitalize-first("test")

If you want to use a package which encapsulates jar files, you will have to import in the same way the namespace of the module which wraps the java methods and call the XQuery wrapper functions for these methods.

Deleting a package

A package can be deleted either by its name or by the name of its directory. This can be done with the command REPO DELETE. e.g.

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:

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

1 package(s).