eXist: A NoSQL Document Database and Application Platform (2015)

Appendix A. XQuery Extension Modules

This appendix provides an overview of the available XQuery extension modules in eXist.

You might have noticed that in other chapters we’ve often mentioned and described extension modules. For instance, “Controlling the Database from Code” explains in part how to manipulate the database using the xmldb extension module. This is because we think it is better to describe an extension module within its context as much as possible. However, there are a lot of extension modules we haven’t covered elsewhere, so we provide an overview here to assist you.

We won’t handle all the extension modules that come with eXist. As is often the case with open source products, experiments creep in and are not removed. Some of the modules seem to hold interesting functionality, but documentation is missing. And some are very specialized and of interest only to a very small group of users. We therefore took the liberty to describe only those modules that we thought would be of general interest and for which at least some kind of documentation was available (often just the information in eXist’s function documentation browser). Apologies to all module creators whose modules we left out. If you think something we left out deserves a place in this appendix, please drop us a line and we’ll try to rectify this in a future edition of the book.

What we also won’t do here is describe all functions in detail. eXist provides an online function documentation browser, and we saw no reason to duplicate this information; it would have made the book too heavy and the information would probably soon be out of date. What we willdo is provide you with a list of modules available in the version of eXist (2.1) that this book was written for, tell you a little bit about them, and provide examples when we think it is appropriate.

Extension Modules by Category

This section contains a list of the extension modules discussed here, grouped by category. Categorizing is always a bit arbitrary, but hopefully this will you help find the module/functionality you’re looking for more quickly. The brief descriptions provided for each module give an indication of what they are used for or contain.

Core

These modules form a core of useful extension functionality that you would not want to do without when working with XQuery in eXist:

Data Handling

Modules in this category provide additional data handling capabilities to eXist, such as reading and writing of ZIP files, conversion to JSON, and image handling:

Data Type Extensions

These modules supply additional functionality for existing data types:

Database Functionality

This category of modules enables additional database-related functionality, like caching, scheduling, and the repository manager:

Indexing

These are modules that work with indexes:

Protocols/Interfaces

These modules enable access to various communication protocols and interfaces from XQuery code:

XML Technologies

These modules provide access to additional XML technologies:

XQuery

These are modules that provide additional XQuery-related functionality:

Extension Module Descriptions

This section lists all the extension modules and tells you what they’re useful for, sometimes providing a small example.

Every module starts with a table that has the following information:

Module name

Description

A (very) short description of the module.

Namespace

The namespace for the module, including the preferred prefix. You can, of course, decide to use a different prefix.

Type/default status

The type of the module (Java or XQuery), and whether it is enabled by default and (for Java modules) built into eXist. Information about what this means exactly and how to change it can be found in “Enabling Extension Modules”.

Class

The Java class name (for Java-based modules) or the location (for XQuery-based modules) of the module.

cache

Description

Systemwide global cache

Namespace

cache="http://exist-db.org/xquery/cache"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.cache.CacheModule

The cache extension module adds a systemwide global cache to eXist. It allows you to create data that is not only sessionwide (for which you would use the session module) but also systemwide. It adds true global variables to eXist, with all the benefits but also the ugly dangers of global data.

The following example creates a cache (or gets a reference to it if it already exists) and stores the current date/time in it. The cache:put function returns the previous value, which we display alongside the new value:

let $cache := cache:cache('test')

let $previous-value := cache:put('test', 'KEY', current-dateTime())

return

<cache previous="{$previous-value}" now="{cache:get('test', 'KEY')}"/>

If you run this example from different sessions (run it, close your browser, run it again), you’ll find that the value stored is retained: the now value from the first session is the previous value in the second session.

compression

Description

Handling of ZIP, GZIP, and TAR files

Namespace

compression="http://exist-db.org/xquery/compression"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.compression.CompressionModule

This module allows you to create and read ZIP, GZIP, and TAR compressed files.

Let’s take a ZIP file as example (GZIP and TAR work likewise). You can create a ZIP file by calling compression:zip and feeding it a sequence of items to compress:

§ If such an item is of type xs:anyURI, it is supposed to be the URI of a resource or a collection. A collection is zipped in its entirety and its directory structure is mimicked in the ZIP file.

§ If it’s an entry element, its content is zipped. It takes three attributes:

§ The name attribute is used as the path of the resource in the ZIP file.

§ The type attribute tells the module how to interpret the contents of the entry element. Possible values are collection, uri, binary, xml, and text.

§ The optional method attribute tells the module whether the resource should be compressed before being added to the ZIP file (the default) or simply stored as is. (The latter is useful when, for instance, creating ebook files in ePub format, which requires a noncompressed Internet media type file.)

Here is an example that zips a part of the book’s examples and adds an extra XML file:

let $stuff-to-compress as item()+ := (

xs:anyURI('/db/eXist-book/getting-started'),

<entry name="EXTRA/x.xml" type="xml">

<Extra>Some extra stuff...</Extra>

</entry>

)

let $file-uri := '/some/path/on/your/disk/out.zip'

let $zipfile := compression:zip($stuff-to-compress, true())

return

file:serialize-binary($zipfile, $file-uri)

contentextraction

Description

Indexing binary content

Namespace

contentextraction="http://exist-db.org/xquery/contentextraction"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.contentextraction.xquery.ContentExtractionModule

The contentextraction module is an absolute wonder! It allows you to extract text content from binary resources like Word or PDF files, based on the Apache Tika toolkit. Everyone who has ever coped with this problem knows how difficult, frustrating, and time-consuming it can be.

The Tika toolkit supports many formats. For instance, you can feed it an HTML page and it will output well-formed and valid XHTML. Feed it a text file (in any character encoding) and it will neatly create paragraphs from it. Other formats supported include Microsoft Office, Open Document, PDF, ePub, RTF, mbox, and even the textual/metadata parts of audio, image, and video files (see the Tika website for details).

To use the contentextraction module, insert the following import module statement in the prolog of your XQuery script:

import module namespace content="http://exist-db.org/xquery/contentextraction"

at "java:org.exist.contentextraction.xquery.ContentExtractionModule";

The module has three functions (use the XQuery Function Documentation app from the dashboard to inspect them). The following code will return the metadata and contents of a (recognized) binary file:

let $file := 'some/path/to/a/binary/file'

return

content:get-metadata-and-content(util:binary-doc($file))

An interesting use case of contentextraction is, of course, indexing using the full-text index capabilities of eXist and allowing the user to search binary documents stored in the database (read more about this in “Manual Full-Text Indexing”). For indexing large documents the third, somewhat complicated, function, content:stream-content, comes in handy. There is an interesting content extraction example in the eXist-db demo apps (available through the dashboard) that uses this.

counter

Description

Persistent counters

Namespace

counter="http://exist-db.org/xquery/counter"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.counter.CounterModule

This module adds eXist global persistent counters. It allows you to count things and keep the results across sessions and database restarts.

datetime

Description

Date and time operations

Namespace

datetime="http://exist-db.org/xquery/datetime"

Type/default status

Java; disabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.datetime.DateTimeModule

This module has functions for working with dates and times, like parsing strings into dates, counting days in a month, and creating date/time ranges. It can also format dates/times into more user-friendly strings. Much of its functionality has already been superceded by newer (more portable) modules.

exi

Description

Working with EXI (XML binary)

Namespace

exi="http://exist-db.org/xquery/exi"

Type/default status

Java; disabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.exi.ExiModule

This module allows encoding and decoding XML into/from the Efficient XML Interchange (EXI) format. EXI is a binary format for XML data.

exiftool

Description

Extracting EXIF data from binary files

Namespace

exiftool="http://exist-db.org/xquery/exiftool"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.exiftool.xquery.ExiftoolModule

This module extracts EXIF data from binary files—for instance, photos shot with a modern digital camera. It relies, however, on the presence of Perl at /usr/bin/perl.

file

Description

Managing files and directories on the filesystem

Namespace

file="http://exist-db.org/xquery/file"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.file.FileModule

This module allows you to work with files and directories on the filesystem (outside the database). There are functions like file:mkdir, file:move, and file:serialize (in several variants). You need DBA privileges to use it.

WARNING

For Windows, passing file and directory names to functions in the file module can lead to some odd behavior. This only seems to work when you do not specify the file:// prefix, only use backslashes as the path separator, and always start the name with a backslash (e.g., \C:\test\erik\test.xml instead of file://c:/test/erik/test.xml).

ft

Description

Querying Lucene’s full-text index

Namespace

ft="http://exist-db.org/xquery/lucene"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.modules.lucene.LuceneModule

This module provides access to Lucene’s full-text index results. How to do this is described in “Searching with the Full-Text Index”.

ftpclient

Description

Performing FTP requests as a client

Namespace

ftpclient="http://exist-db.org/xquery/ftpclient"

Type/default status

Java; disabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.ftpclient.FTPClientModule

This module allows you to use eXist as a client against an FTP server. You can read and write (binary) files and get directory listings.

http

Description

Performing HTTP requests as a client (EXPath)

Namespace

http="http://expath.org/ns/http-client"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.expath.exist.HttpClientModule

This is a module that allows you to send out HTTP requests according to the EXPath HTTP Client module specifications (refer to http://www.expath.org/modules/http-client/ and http://www.expath.org/spec/http-client). The functions expect an XML fragment that contains the specification of the request and returns an XML fragment with its results.

For instance, the following example fires an HTTP GET request at the local eXist REST interface (see “Querying the Database Using REST”). The result is a directory listing of /db:

let $http-request-data := <request xmlns="http://expath.org/ns/http-client"

method="GET" href="http://localhost:8080/exist/rest/db"/>

return

http:send-request($http-request-data)

The result is another XML fragment that provides you with the result and all the HTTP properties surrounding this:

<http:response xmlns:http="http://expath.org/ns/http-client"

status="200"

message="OK">

<http:header name="date" value="Tue, 20 Nov 2012 14:49:55 GMT"/>

<http:header name="set-cookie"

value="JSESSIONID=1jkifx0ip6jin6kswi0n96q54;Path=/exist"/>

<http:header name="expires" value="Thu, 01 Jan 1970 00:00:00 GMT"/>

<http:header name="content-type" value="application/xml; charset=UTF-8"/>

<http:header name="last-modified" value="Tue, 25 Sep 2012 08:15:31 GMT"/>

<http:header name="created" value="Tue, 25 Sep 2012 08:15:31 GMT"/>

<http:header name="transfer-encoding" value="chunked"/>

<http:header name="server" value="Jetty(8.1.3.v20120416)"/>

<http:body media-type="application/xml"/>

</http:response>

<exist:result xmlns:exist="http://exist.sourceforge.net/NS/exist">

<exist:collection name="/db" created="2012-09-25T10:15:30.686+02:00"

owner="SYSTEM" group="dba" permissions="rwxr-xr-x">

<exist:collection name="eXist-book" created="2012-09-05T10:03:28+02:00"

owner="admin" group="dba" permissions="rwxr-xr-x"/>

<!-- Etc. -->

</exist:collection>

</exist:result>

eXist also contains an HTTP Client module of its own (see the next section). Both modules have roughly the same functionality, but if you’re ever going to do cross-platform XQuery programming, the EXPath one is the better choice.

httpclient

Description

Performing HTTP requests as a client (eXist native)

Namespace

httpclient="http://exist-db.org/xquery/httpclient"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.httpclient.HTTPClientModule

This module allows you to send out HTTP requests as if eXist were a client. It has functions like httpclient:put and httpclient:get. All functions return an extensive XML fragment with details of the request’s response. An example of using the httpclient:post function can be found in “POST Requests”.

eXist also contains an EXPath-conformant HTTP Client module (see http). Both modules have roughly the same functionality, but if you’re ever going to do cross-platform XQuery programming, the EXPath one is the better choice.

image

Description

Performing operations on images stored in eXist

Namespace

image="http://exist-db.org/xquery/image"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.image.ImageModule

This module has functions for performing various operations on images stored in eXist, like requesting their metadata, width, and height. It can also crop and scale images and do bulk thumbnail conversions.

Most functions take the image as xs:base64Binary for input. Converting is easy: use the util:binary-doc function. The following example tells you the height of an image stored in eXist:

let $image-uri as xs:anyURI := xs:anyURI('/db/some/path/to/an/image/file')

return

image:get-height(util:binary-doc($image-uri))

There is also an example of using this module in “RESTXQ”.

inspect

Description

Retrieving xqDoc information from XQuery modules

Namespace

inspect="http://exist-db.org/xquery/inspection"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.inspect.InspectionModule

This module allows you to inspect XQuery modules and their xqDoc documentation. More about this can be found in “XQuery Documentation with xqDoc”.

jfreechart

Description

Generating charts using the JFreeChart library

Namespace

jfreechart="http://exist-db.org/xquery/jfreechart"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.jfreechart.JFreeChartModule

This module allows you to create all kinds of beautiful pie, bar, and other fancy charts using the JFreeChart library.

jndi

Description

eXist JNDI interface

Namespace

jndi="http://exist-db.org/xquery/jndi"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.jndi.JNDIModule

This module is an interface for XQuery to use the Java Naming and Directory Interface (JNDI).

json

Description

Transforming XML into JSON

Namespace

json="http://www.json.org"

Type/default status

XQuery; enabled in $EXIST_HOME/conf.xml

Location

resource:org/exist/xquery/lib/json.xq

This module transforms (data-centric) XML into straightforward JSON. The module contains a number of functions, but the main entry point is json:xml-to-json. The rules for the JSON conversion are the same as those used in the JSON Serializer (see “JSON serialization”). For an alternative, see also xqjson.

jsonp

Description

Transforming XML into JSONP

Namespace

jsonp="http://www.jsonp.org"

Type/default status

XQuery; enabled in $EXIST_HOME/conf.xml

Location

resource:org/exist/xquery/lib/jsonp.xq

This module transforms (data-centric) XML into JSON, which is wrapped inside a named JavaScript function. This usage pattern is known as JSONP. The module contains a number of functions, but the only really useful one is its main entry point, jsonp:xml-to-jsonp. The first argument is the XML node to convert to JSON, and the second is the name to use for the JavaScript function wrapper.

kwic

Description

Keywords in context

Namespace

kwic="http://exist-db.org/xquery/kwic"

Type/default status

XQuery; enabled in $EXIST_HOME/conf.xml

Location

resource:org/exist/xquery/lib/kwic.xql

This module allows you to easily show fragments of text found in full-text or NGram search operations. The module is described in “Using Keywords in Context”.

mail

Description

Email-related functions

Namespace

mail="http://exist-db.org/xquery/mail"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.mail.MailModule

This module allows you to send and receive email messages using the Java mail libraries. The following example shows sending a message through a straight SMTP server (without required authorization):

let $receiver-email := 'your@email.address'

let $smtp-server := 'your.smtp.server.address'

let $message :=

<mail>

<from>E. Mailtester <emailtester@dummy.org></from>

<to>{$receiver-email}</to>

<subject>Testing send-email()</subject>

<message>

<text>Test message, Testing 3, 2, 1 at {current-dateTime()}</text>

<xhtml>

<html>

<head>

<title>Testing</title>

</head>

<body>

<h1>Testing</h1>

<p>Test message, Testing 3, 2, 1 at {current-dateTime()}</p>

</body>

</html>

</xhtml>

</message>

</mail>

let $props :=

<properties>

<property name="mail.smtp.auth" value="false"/>

<property name="mail.smtp.port" value="25"/>

<property name="mail.smtp.host" value="{$smtp-server}"/>

</properties>

let $session := mail:get-mail-session( $props )

return

mail:send-email($session, $message)

map

Description

map data type functions

Namespace

map="http://www.w3.org/2005/xpath-functions/map"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.map.MapModule

This module supports the map data type, as described in “The map data type proposed for XQuery 3.1”.

math

Description

Mathematical functions

Namespace

math="http://exist-db.org/xquery/math"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.math.MathModule

This module includes various mathematical functions like sin, pi, and exp.

WARNING

This module is now deprecated by the math functions from the namespace http://www.w3.org/2005/xpath-functions/math as defined by the XPath and XQuery Functions and Operators 3.0 specification.

metadata

Description

Document key/value metadata functions

Namespace

md="http://exist-db.org/metadata"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.storage.md.xquery.MetadataModule

This module incudes functions for associating key/value metadata pairs with a document, rerieving key/value pairs associated with documents, and searching for documents based on key/value pairs.

WARNING

While useful, the metadata module should be considered highly experimental and not yet ready for production use.

For example, say you wish to store a key/value pair of metadata for the document /db/my-docs/doc1.xml. You can do this as follows:

xquery version "1.0";

import module namespace md = "http://exist-db.org/metadata";

md:set-value(doc("/db/my-docs/doc1.xml"), "roll-number", 12345)

Each time you set a metadata key/value pair, you are also returned a UUID (universally unique identifier) that represents the intersection of document, key, and value.

You can find all of the metadata keys set for a document like so:

xquery version "1.0";

import module namespace md = "http://exist-db.org/metadata";

md:keys(doc("/db/my-docs/doc1.xml"))

And you can retrieve the document(s) with the metadata key roll-number and the value 12345 like this:

xquery version "1.0";

import module namespace md = "http://exist-db.org/metadata";

md:document-by-pair("roll-number", "12345")

Other available functions in the metadata module include md:set-value-by-url, md:uuid, md:uuid-by-url, md:document-by-uuid, md:keys-by-url, md:get-value, md:get-value-by-url, md:search, and md:delete.

ngram

Description

NGram index–related functions

Namespace

ngram="http://exist-db.org/xquery/ngram"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.modules.ngram.NGramModule

This module supports using an NGram index in XPath queries. Use of this module is explained in “Using the NGram Indexes”.

repo

Description

Working with the EXPath repository manager

Namespace

repo="http://exist-db.org/xquery/repo"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.modules.expathrepo.ExpathPackageModule

This module allows you to manage the local EXPath package repository of your eXist installation. The package repository manages external packages (.xar archives), which can include everything from third-party XQuery libraries to full applications or other XML technology functionality.

The module distinguishes between installation and deployment steps. This is because although the installation process is standardized by the EXPath packaging specification, the deployment step is not. It is implementation-defined and specific to eXist-db. Installation will register a package with the EXPath packaging system, but will not copy anything into the database. Deployment will deploy the application into the database as specified by repo.xml.

The packaging mechanism and this module are described in “Packaging”. Background information is available at http://exist-db.org/exist/apps/doc/repo.xml.

request

Description

Handling HTTP requests

Namespace

request="http://exist-db.org/xquery/request"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.functions.request.RequestModule

This module provides functions to handle an HTTP request in XQuery, like finding out the URI and the parameters. It is described in “The request Extension Module”.

response

Description

Controlling the HTTP response

Namespace

response="http://exist-db.org/xquery/response"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.response.ResponseModule

This module allows you to control the HTTP response in XQuery—for instance, by setting headers or streaming binary data. It is described in “The response Extension Module”.

restxq

Description

Module for eXist’s RESTXQ interface

Namespace

restxq="http://exquery.org/ns/restxq"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.extensions.exquery.restxq.impl.xquery.RestXqModule

This module supports eXist’s RESTXQ interface. For more information, see “Building Applications with RESTXQ”.

restxqex

Description

Module for eXist’s RESTXQ resource function registry

Namespace

restxqex="http://exquery.org/ns/restxq/exist"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.extensions.exquery.restxq.impl.xquery.exist.ExistRestXqModule

This module is specific to eXist and provides some reporting and control over the registration of RESTXQ resource functions with eXist’s implementation of the RESTXQ resource function registry. For more information, see “Building Applications with RESTXQ”.

scheduler

Description

Scheduling jobs

Namespace

scheduler="http://exist-db.org/xquery/scheduler"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.scheduler.SchedulerModule

The scheduler module allows you to run a job (for instance, an XQuery script) at regular intervals. For instance, starting a script that will run five times at a 10-second interval is done with this call (for details, please refer to the module documentation):

scheduler:schedule-xquery-periodic-job('/path/to/your/script.xq', 10000,

'JobName', (), 0, 5 )

Jobs can be stopped, paused, and examined. Calling scheduler:get-scheduled-jobs may surprise you by showing that there are quite a few system jobs running that you weren’t aware of.

NOTE

Jobs scheduled with the scheduler module are not persisted across restarts of the database. If you wish to create persistent scheduled jobs, you need to add them to the scheduler configuration section of $EXIST_HOME/conf.xml as well.

If your job doesn’t seem to run or does not behave as you expect, consult the $EXIST_HOME/webapp/WEB-INF/logs/exist.log file. For more information on eXist’s scheduler, see “Scheduled Jobs”.

sequences

Description

Working with sequences

Namespace

sequences="http://exist-db.org/xquery/sequences"

Type/default status

XQuery; enabled in $EXIST_HOME/conf.xml

Location

resource:org/exist/xquery/lib/sequences.xq

This module includes utility functions for working with sequences like filter and fold.

session

Description

Functions for working with HTTP sessions

Namespace

session="http://exist-db.org/xquery/session"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.session.SessionModule

NOTE

The HTTP session is a piece of memory that is allocated by the Java application server underlying eXist and associated with a series of requests from a single client. So that the Java application server can identify each request from a client as belonging to the same session, a unique identifier is generated and given to the client. This is expected to be sent back to the server on each request. This identifier may take the form of an HTTP cookie or a parameter in the HTTP URL query string; either way, it will be named JSESSIONID.

A session can contain data that is kept alive between requests. Access to a session is provided through this module. It is described in “The session Extension Module”.

sm

Description

Security Manager functions

Namespace

sm="http://exist-db.org/xquery/securitymanager"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.securitymanager.SecurityManagerModule

This module is for managing eXist’s security settings. You can, for instance, check whether you have access to a resource by calling sm:has-access. More about security can be found in Chapter 8.

sort

Description

Indexes for efficient sorting

Namespace

sort="http://exist-db.org/xquery/sort"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.modules.sort.SortModule

The sort module lets you create (global, systemwide) indexes to speed up sorting (with order by clauses) on nodes in FLWOR expressions. This works only for nodes stored in the database, not nodes in temporary, in-memory XML fragments.

As an example, assume we have an XML document stored in our database that looks like this:

<NodeSet>

<Node>a</Node>

<Node>B</Node>

<Node>c</Node>

<Node>D</Node>

<Node>e</Node>

<Node>F</Node>

</NodeSet>

Not terribly interesting and not at all difficult or time-consuming to sort, but it serves the purpose of illustrating how a sort index works. Assume we want to sort the Node elements based on the uppercase value of their contents, using a sort index. To do this we first have to create a function that converts the node to sort into an atomic value. In this case:

declare function local:sort-callback($node as node()) as xs:string {

upper-case(normalize-space($node))

};

Now we can create the index using this function:

let $node-set as element()+ := doc('/db/path/to/nodeset/document')/*/Node

let $index-id as xs:string := 'SORTINDEX'

let $sort-index := sort:create-index-callback(

$index-id,

$node-set,

local:sort-callback#1,

()

)

With this we’ve created a sort index for our nodes with identifier SORTINDEX. The sort:create-index-callback always returns the empty sequence (). Its fourth argument can be an XML fragment for specifying the sort order and what to do with empty values:

<options order? = "ascending" | "descending"

empty? = "least" | "greatest"

Using the created sort index in a FLWOR expression is easy:

for $node in$node-set

order by sort:index($index-id, $node)

return

string($node)

This returns the expected:

a B c D e F

Once created, a sort index is available globally, systemwide. All queries, in any session, can access it. So, if you need sort indexes in your application, it would be best to create them in some kind of initialization script. If you want to check whether a sort index exists, use sort:has-index.

sql

Description

Database access using JDBC

Namespace

sql="http://exist-db.org/xquery/sql"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.sql.SQLModule

This module allows you to access SQL databases from eXist using the Java Database Connectivity (JDBC) API. Find more information at http://atomic.exist-db.org/HowTo/SQLDatabases/.

system

Description

Information about eXist and the system environment

Namespace

system="http://exist-db.org/xquery/system"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.system.SystemModule

This module contains several utility functions for working with eXist and the system environment. For instance, you can use it to get the memory settings, the eXist version, and a list of running XQueries, and to shut down the database.

text

Description

Text-searching extension functions

Namespace

text="http://exist-db.org/xquery/text"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.text.TextModule

This module contains several functions for searching in and working with text—for instance, finding all matches to a regular expression. Many of these functions work together with the full-text index.

transform

Description

XSLT-related functions

Namespace

transform="http://exist-db.org/xquery/transform"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.transform.TransformModule

This module allows you to perform XSLT transformations within your XQuery code. It is described in “XSLT”.

util

Description

Utility functions

Namespace

util="http://exist-db.org/xquery/util"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.util.UtilModule

This module comprises a miscellaneous collection of functions for performing all sorts of not easily categorized tasks; for instance, creating UUIDs, dynamically setting XQuery options, and various type conversions.

validation

Description

Validating XML

Namespace

validation="http://exist-db.org/xquery/validation"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.validation.ValidationModule

This module is for validating XML against DTDs, XML schemas and/or RELAX NG schemas, and Schematron. It is described in “Validation”.

versioning

Description

Access to versioning extensions

Namespace

versioning="http://exist-db.org/versioning"

Type/default status

XQuery; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Location

resource:org/exist/versioning/xquery/versioning.xqm

This module provides access to eXist’s versioning extension. This provides basic versioning capabilities for resources stored in the database. The versioning extension is described in Chapter 16.

xmlcalabash

Description

Access to the XML Calabash XProc module (experimental)

Namespace

calabash="http://xmlcalabash.com"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.xmlcalabash.XMLCalabashModule

This is an experimental module for running XProc pipelines with the XML Calabash implementation. It registers a single function called process.

This module doesn’t follow the normal pattern for Java modules: it does not register a default namespace prefix. You’ll have to add import module namespace xmlc="http://xmlcalabash.com"; at the top of your script (which is good practice anyway) to be able to callxmlc:process.

xmldb

Description

Core module for working with the database

Namespace

xmldb="http://exist-db.org/xquery/xmldb"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xquery.functions.xmldb.XMLDBModule

This module contains all the base functions for working with the database: exploring the database content, creating collections and resources, logging in, and so on. More information is available in “Controlling the Database from Code”.

xmldiff

Description

Comparing XML documents

Namespace

xmldiff="http://exist-db.org/xquery/xmldiff"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.xmldiff.XmlDiffModule

This module allows you to compare two XML documents with the xmldiff:compare function. It only returns whether the documents are equal (not a difference list).

xmpp

Description

Access to the XMPP instant messaging protocol

Namespace

xmpp="http://exist-db.org/xquery/xmpp"

Type/default status

Java; disabled in $EXIST_HOME/conf.xml; disabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.xmpp.XMPPModule

This module is an XQuery interface to the Extensible Messaging and Presence Protocol (XMPP) used for instant messaging, chatting, and so on.

xqdm

Description

Retrieving xqDoc information from XQuery modules (XQuery 1.0 only)

Namespace

xqdm="http://exist-db.org/xquery/xqdoc"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.exist.xqdoc.xquery.XQDocModule

This is an older implementation of the XQuery documentation system xqDoc, as described in “XQuery Documentation with xqDoc”. It only works with pure XQuery 1.0 modules and does not support XQuery 3.0.

xqjson

Description

Module for serializing XML into JSON, and parsing JSON into XML.

Namespace

xqjson="http://xqilla.sourceforge.net/lib/xqjson"

Type/default status

XQuery; installable as an EXPath package.

Location

xmldb:///db/system/repo/xqjson-0.1.5/content/xqjson.xql

This module provides a different approach to conversion to/from JSON by introducing a custom XML grammar for representing a parsed JSON document. The two main functions of interest are xqjson:serializejson and xqjson:parse-json. You can find further details about the module and its XML grammar on the XQJSON GitHub page.

xslfo

Description

Rendering with XSL-FO

Namespace

xslfo="http://exist-db.org/xquery/xslfo"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml; enabled in $EXIST_HOME/extensions/build.properties

Class

org.exist.xquery.modules.xslfo.XSLFOModule

This module provides access to eXist’s XSL-FO capabilities. This is described in full in “XSL-FO”.

zip

Description

Accessing resources in ZIP files

Namespace

zip="http://expath.org/ns/zip"

Type/default status

Java; enabled in $EXIST_HOME/conf.xml

Class

org.expath.exist.ZipModule

This module allows you to read resources from ZIP files using the standard EXPath functions for this; for further information, see http://expath.org/spec/zip.