xquare

Installation Guide

XQuare Fusion 1.1


Notice: This is the first document to read in order to proceed XQuare products installation.

XQuare Fusion installation guide.

Installing and running XQuare Fusion

This document describes the few steps that are required to setup and configure your system to run XQuare Fusion. XQuare Fusion is a software component that can be used in two modes:

  • as a command-line tool
  • as a component library integrated in an application or application server environment.

Each mode requires specific configuration steps, which are described below.

Required configuration

XQuare Fusion runs on the following platform:

  • JVM: Sun's JRE 1.3.1 or 1.4.x
  • XQuare Bridge 1.x as a connector to relational data sources (supporting all major RDBMS vendors. See XQuare Bridge for detailed information.).
  • XML parsers: JAXP-compliant parsers are supported. An XML pull parser is provided in the package and is used internally.

Extracting the software package

The distribution is provided as a simple archive (.zip or .tgz depending on the target platform) to be extracted in any directory of your choice.

Configuring and running the command-line tool

The configuration of the command-line tool requires two steps:

  • Setting the environment variable.
  • Setting the database connection parameters.
Environment variables

The xqfusion script (which is found in the bin/ directory of the distribution) uses several environment variables:

  • JAVA_HOME: this variable must be set to the directory where the JRE 1.3.1 or 1.4.x can be found. If not set, the script will run the first java executable found on the execution path.
  • XQ_CLASSPATH: this variable defines the additional classpath which is appended to the standard one and to the XQuare Fusion distribution jars before running the software. It is used to load the JDBC driver classes and JAXP-compliant parsers that are not part of the delivery. Alternatively, the classpath can be controlled by setting the standard CLASSPATH environment variable to the appropriate value.

If running under Windows 9x:

  • XQFUSION_HOME: this variable must be set to the directory where XQuare Bridge was installed.
Configuration

XQuare Fusion must be configured in order to run properly. This is done through one or more configuration files. An example of these files can be found in the use-cases directory where the basic configuration file main.xml shows relevant parameters as well the configuration of the SQL wrappers WSQL1.cfg, WSQL2.cfg and WSQL3.cfg.

Running the command-line tool

The command-line tool can be executed by invoking the following command:

  • xqfusion -q <query file>

The command:

  • xqfusion -help

prints a message on the standard output detailing command-line options. Options are also described in the user guide.

Using XQuare Fusion as a software component

Integrating XQuare Fusion in an application or in an application server environment requires to properly set up the compilation and run-time classpaths.

JAR files available in the distribution

The list of JAR files present in the distribution is given in the table below, relatively to installation directory:

JAR nameContent
lib/xquark-fusion.jarMain JAR in the distribution. Must be present in both compilation and run-time classpaths. This file contains internal links to other JAR files in the distribution (except crimson.jar and JDBC drivers, see below), so that those files don't need to be explicitly included in the run-time classpath, as long as their relative paths do not change.
lib/xquark-schema.jarRuntime JAR containing XQuare XML schema implementation.
lib/xquark-xdbc.jarRuntime JAR containing the XQuare XML/DBC API (interface definitions only).
lib/xquark-xpath.jarRuntime JAR containing XQuare XPath implementation.
lib/xquark-xquery.jarRuntime JAR containing XQuare XQuery front-end.
lib/xquark-jdbcutils.jarRuntime JAR containing tools providing an abstraction layer over JDBC.
lib/xquark-extractor.jarRuntime JAR containing the XQuery back-end for relational database access.
lib/xml-apis.jarSupport JAR, containing the JAXP, DOM2 and SAX2 interfaces. It is only used at compilation time.
lib/crimson.jarSupport JAR, containing the JAXP, DOM2 and SAX2 interfaces, as well as a JAXP-compliant parser implementation. This file contains all the classes needed to parse XML files and build DOM2 in-memory representations. Either this file or another JAR file providing a JAXP implementation (e.g. Xerces) must be present in the runtime classpath.
lib/mysql-connector-java-3.0.9-stable-bin.jarSupport JAR, containing the redistributable JDBC driver for MySQL.
lib/xpp3-1.1.3.4-RC3.jarSupport JAR, containing the XPP pull parser, used to access XML documents from Fusion.
Compilation classpath

All JAR files in the distribution must be present in the classpath at compilation time, except lib/crimson.jar, lib/mysql-connector-java-3.0.9-stable-bin.jar and lib/xpp3-1.1.3.4-RC3.jar.

Run-time classpath

When integrating XQuare Fusion in an application, it is only necessary to add:

  • lib/xquark-fusion.jar,
  • lib/crimson.jar (or an alternate JAXP implementation),
  • lib/xpp3-1.1.3.4-RC3.jar
  • and the required JDBC driver JAR files to the classpath, as the former JAR file contains relative links to the other JAR in the distribution. Note however that all class loaders do not support links in JAR files: when using an application which uses a custom class loader, it might be necessary to add all the distribution JAR files to the application classpath. This is typically the case when integrating XQuare Fusion in an application server.
by Odonata