xquare

Command-line tool user guide

XQuare Bridge 1.1.1


Notice: Use this document if you need to install, configure and run a command-line tool to test or demonstrate XQuare Bridge features.

This document is the XQuare Bridge command-line tool user guide.

XQuare Bridge - Command-line utility

Warning
This tool is mainly provided for demonstration or test purposes since the launching and database connection overhead does not allow the tool to reach the performance of server-side use through the API.

Synopsis

xqbridge -q [ options ] queryFile [outFile]

xqbridge -i [ options ] mapFile xmlFile1 [xmlFileI]*

options
command-line options
queryFile
file containing an XQuery
outFile
file in which the query results are written
mapFile
XML file containing a mapping specification
xmlFileI
XML file containing the data to be inserted

XML file containing the data to be inserted Description

The XQuare Bridge tool is used to extract XML data from a database, using the XQuery language, and to insert XML data into a database, using a mapping specification. The first behavior is obtained using the -q option, and the second one using the -i option.

Configuration

Environment variables

The XQuare Bridge tool uses several environment variable:

  • 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.

If running under Windows 9x:

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

When using XQuare Bridge in insertion mode, the user can define Java-based generators used to fill column values. Those classes need to be in the classpath used by the command-line tool. This can be controlled by setting the standard CLASSPATH environment variable to the appropriate value.

Database connection

In order to work, XQuare Bridge needs to connect to a database. The installation guide describes how to set up the default connection. The default setup can be overidden by specifying connection parameters on the command line (see options below), by creating a Java properties file containing the appropriate parameters, or by creating an XML configuration file (see XQuery Manual for details).

The properties that must be set in the properties file 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.

If no properties or configuration file is specified on the command line, XQuare Bridge will try to load the first XQBridge.properties file found in the classpath.

Tracing

XQBridge uses Apache Log4J for logging . You can configure the trace by modifying the bin/log4j.properties file (refer to Log4J documentation for more details). For instance, to produce debug logs, set the log4j.rootLogger property to DEBUG.

Options

-?, -help
Lists the options on the standard output.
-p properties file
A properties file, in the format described above.
-conf XML file
A configuration file, in the format described in the XQuery Manual.
-driver javaDriverClassName
java class name of the JDBC driver to use for database connection.
-url jdbcString
JDBC connection string to the database.
-user userName
Database user name.
-password password
Database user password.
-cp classpath
A classpath, in the standard pratform-specific format.
-f file
A file containing a list of parameters. When the -q option is used, each line of the file must contain a query file and an optional output file. When the -i option is used, each line of the file must contain a mapping specification file and one or several XML files. Lines starting with # are ignored.
-debug
Writes debug information to the standard output.
by Odonata