Qizx/open User's Guide

1.1. Requirements
1.2. Installing on Windows
1.3. Installing on Unixes
1.4. Contents of the distribution directory

3.1. Batch XQuery execution
3.2. XQuery Server

Note: this document introduces applications distributed with Qizx/open. It is important to remember that Qizx/open being above all a class library, these applications are examples of how Qizx/open can be used. Their source code is in all cases available and may be extended by users and application developers.

1. Installation

1.4. Contents of the distribution directory

LICENSE.txt	License file. (Mozilla Public License)
docs	Documentation. Contains both PDF and HTML versions of documents. See index.html for details.
bin	Contains launcher scripts for several Qizx/open applications: (.bat extension on Windows). These applications are documented below. qizxopen_studio: graphical interface. qizxopen_batch: batch execution of XQuery scripts. qizxopen_server: XQuery server accessible from remote clients (uses Java RMI).
lib	Main library jar of Qizx/open: qizxopen.jar. Executable with java -jar or by double-click on Windows. Jar for Qizx/open studio: qizxopen_studio.jar. Executable with java -jar or by double-click on Windows. Auxiliary jars: Sun's XML catalog resolver resolver.jar
config	A place for Java resources used by applications (part of classpath). By default contains XML catalogs and DTDs for XHTML et Docbook.
examples	miscellaneous examples and demos.
xqsp	XQuery Server Pages: a J2EE Servlet which runs XQuery scripts directly, bundled with demos. Contains a Ant build file to create the war archive.
src	Source code. Contains a Ant build file allowing to recompile Qizx/open. For XQuest, available only with a special license.

2. Qizx/open Studio

This is a GUI that allows to edit and run XQuery scripts. In Qizx/open, the purpose is mainly XQuery experimenting and training.

Figure 1. A screenshot of Qizx/studio (Java 5 / Linux look-and-feel)

Description of the GUI:

There are two main tabs:

Query tab: this is a query execution facility. It is composed of 4 areas:
XML Library browser: ( absent in Qizx/open): when XQuest studio is connected to a XML Library Server (either remote or embedded), this tab allows to browse :

Figure 2. An example of query execution with Node-type result.

Option switches

As for other Qizx/open applications, Qizx/open studio can be executed with command-line options:

-server registry_name

connect to a remote server (registry_name: simple name if local registry, or //host[:port]/name)

-remote

shorthand for: -server 'XQuestServer'

-Cname=value

specify a server connection property (e.g. username and password).

-Dvariable_name=value

initialize a XQuery global variable.

-- (double dash)

pass all following arguments to XQuery expressions: arguments are available in variable '$arguments', which is a sequence of strings.

-Xoption=value

set a XML serialization option. (See serialization documentation). For example -Xmethod=xhtml.

-docbase <path>

define base URI for locating parsed XML documents

-modbase <path>

define base URI for locating XQuery modules

-input <URI>

URI of a document used as input (XQuery function input())

-xinput <fragment>

a XML fragment used as input (XQuery function input())

-timezone duration

Defines the implicit timezone in the dynamic XQuery context. The value must be in xs:duration form, for example -timezone -PT5H.

-collation uri

Defines the default collation for string comparisons.

Collations are supported through Java collators. The URI of a collation follows the Java convention for locales: for example "en" or "fr-CH" can be used as collation URIs. A collation URI can be followed by a "fragment" or "reference" that has the value "primary", "secondary" or "tertiary", defining the "strength" of the collator (see the Java documentation for more details).

For example, the expression contains("The next café", "CAFE", "en#primary") should return true, because the collation with strength primary ignores case and accents.

The special URIs codepoint and "http://www.w3.org/2003/05/xpath-functions/collation/codepoint" refer to the basic Unicode codepoint matching (or absence of collation). This is the default collation.

-ext <full.class.name>

Allow specifically this class as Java extension.

-doc.cache <size_in_Kb>

define the parsed document cache size (default 8 Mb).

-tex

verbose display of exceptions

3. Command Line applications

The purpose of these tools is to run XQuery scripts in batch mode. For learning XQuery or getting accustomed with Qizx/open, it is recommended to use Qizx/open Studio, the GUI Tool.

3.1. Batch XQuery execution

qizxopen_batch is a command-line application of Qizx/open. Its purpose is to run XQuery scripts in batch mode.

This tool is launched by the qizxopen_batch wrapper scripts found in sub-directory bin (bin\qizxopen_batch.bat on Windows and bin/qizxopen_batch on Unixes).

Usually the tool will be run with an argument which is the path of a script file:

> qizxopen_batch myquery.xq

This tool can also be invoked without argument: it starts in interactive mode.

> qizxopen_batch
Qizx/open 1.0
[interactive mode]
Query ?

It can also be invoked by running directly from the executable xquest Jar archive:

java -jar qizxopen.jar arguments...

To get help on option switches:

qizxopen_batch -help

Option switches

-server registry_name

connect to a remote server (registry_name: simple name if local registry, or //host[:port]/name)

-remote

shorthand for: -server 'XQuestServer'

-Cname=value

specify a server connection property (e.g. username and password).

-Dvariable_name=value

Defines the value of a global variable. For example if the variable is declared like this:

declare variable $output external;

then the option -Doutput=foo initializes $output with the string value "foo".

If the variable is declared with a type, an attempt to cast the string value to the declared type is made.

If the variable is declared with an initial value, this value is overridden.

-- ...

The double dash switch is used to pass command-line arguments to a XQuery script. It stores all following command-line tokens into the predefined variable $arguments.

-Xoption=value

Defines a serialization option for result output. For example -Xmethod=html produces results in HTML markup.

-out file

output to a file (defaults to standard output)

-serial

Direct evaluation and serial output (more efficient mode, no tree construction): the query must evaluate as a well-formed document.

-docbase <path>

define base URI for locating parsed XML documents

-modbase <path>

define base URI for locating XQuery modules

-input path

Defines a single document as default input (XQuery function input()).

-xinput <fragment>

a XML fragment used as input (XQuery function input())

-timezone duration

Defines the implicit timezone in the dynamic XQuery context. The value must be in xs:duration form, for example -timezone -PT5H.

-collation uri

Defines the default collation for string comparisons.

For example, the expression contains("The next café", "CAFE", "en#primary") should return true, because the collation with strength primary ignores case and accents.

-wrap

wraps the displayed results in description tags. For example with -wrap the expression 1, "a" would display:

Query ? 1, "a"
<?xml version='1.0' encoding='UTF-8'?>
<query-results>
  <item type="xs:integer">1</item>
  <item type="xs:string">a</item>
</query-results>

instead of:

Query ? 1, "a"
1 a
-> 2 item(s)

-q

Quiet mode: do not display evaluation times.

-jt

trace load and use of Java extension functions (for debugging).

-tex

verbose display of run-time exceptions (for debugging).

3.2. XQuery Server

The purpose of this application is to provide a XQuery server remotely accessible by clients. It is meaningful mainly for XQuest, so that a XML Library can be queried from different machines.

However Qizx/open can also work as a server: although it can only use parsed documents stored in memory and has no indexes, it can still be quite effective for small applications.

Of course, running in server/client mode is less efficient than using an embedded XQuery engine. It is recommended to minimize exchanges between client and server by executing most of the work on the server and only retrieving final results in the client. The Java API allows to retrieve XML results efficiently as serialized XML text or as trees.