XQuare Bridge 1.1
Notice: This is the first document to read in order to proceed XQuare products installation.
XQuare Bridge installation guide.
Installing and running XQuare Bridge
This document describes the steps that are required to setup and configure your system to run XQuare Bridge. XQuare Bridge 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. This second approach is recommended, as the startup overhead (JVM startup, JDBC connection setup, etc.) is generally not acceptable in production environments.
Each mode requires specific configuration steps, which are described below.
XQuare Bridge runs on the following platforms:
- JVM: Sun's JRE 1.3.1 or 1.4.x
- Databases: major databases are supported, including MySQL, Oracle, SQLServer and Sybase. See the release notes for the detailed information and the latest news on database support.
- XML parsers: JAXP-compliant parsers are supported.
Integration with application servers has only been tested on Tomcat 4, although the software is known to work with BEA WebLogic.
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.
The xqbridge 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 Bridge 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, as well as user-defined Java-based generators used in insertion mode (see user documentation for details). Alternatively, this classpath can be controlled by setting the xqbridge.classpath property to the appropriate value (see below).
If running under Windows 9x:
XQBRIDGE_HOME: this variable must be set to the directory where XQuare Bridge was installed.
In order to work, XQuare Bridge needs to connect to a database. The default connection parameters can be set in the bin/XQBridge.properties file. Note that this default configuration is not required and can be overwritten by providing connection parameters on the command line (see command-line options for details).
The properties that must be set are:
database.url: the JDBC connection string to the database instance
database.user: the database user
database.password: the database password
xqbridge.classpath: the additional classpath that is used to locate database drivers and user-defined generators used in insertion mode
XQuare Bridge attemps to load all the JDBC drivers that it supports from the classpath, so there is no need to specify the JDBC driver class name.
Running the command-line tool
The command-line tool can be executed by invoking the following commands:
xqbridge -i <map file> <XML file>
The -q option runs the XQuare Bridge in extraction mode, the -i option in insertion mode.
prints a message on the standard output detailing command-line options. Options are also described in the user guide.
Using XQuare Bridge as a software component
Integrating XQuare Bridge 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:
|lib/xquark-bridge.jar||Main 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.jar||Runtime JAR containing XQuare XML schema implementation.
|lib/xquark-xdbc.jar||Runtime JAR containing the XQuare XML/DBC API (interface definitions only).
|lib/xquark-xpath.jar||Runtime JAR containing XQuare XPath implementation.
|lib/xquark-xquery.jar||Runtime JAR containing XQuare XQuery front-end.
|lib/xquark-jdbcutils.jar||Runtime JAR containing tools providing an abstraction layer over JDBC.
|lib/xquark-mapper.jar||Runtime JAR containing XQuare mapping implementation for storing XML documents in relational databases.
|lib/xquark-extractor.jar||Runtime JAR containing the XQuery back-end for relational database access.
|lib/xml-apis.jar||Support JAR, containing the JAXP, DOM2 and SAX2 interfaces. It is only used at compilation time.
|lib/jdbc2_0-stdext.jar||Support JAR, containing the standard javax.sql.* interfaces. It is only used at compilation time.
|lib/crimson.jar||Support 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.jar||Support JAR, containing the redistributable JDBC driver for MySQL.
|lib/xerces-regex.jar||Support JAR, containing Apache Xerces regular expressions implementation.
All JAR files in the distribution must be present in the classpath at compilation time, except lib/crimson.jar and lib/mysql-connector-java-3.0.9-stable-bin.jar.
When integrating XQuare Bridge in an application, it is only necessary to add:
lib/crimson.jar (or an alternate JAXP implementation),
- 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 Bridge in an application server.