xquare

Samples summary

XQuare Bridge 1.1


Notice: Read this document if you need to get off-the-shelf simple examples of XQuare Bridge use in typical situations. It should be used as a practical complement to reference guides and manuals.

This document describes the use-case samples included in the XQuare Bridge distribution.

XQuare Bridge - Examples of use

This directory contains examples of use for XQuare Bridge. The directory for each individual example generally contains:

  • a load.sql file, used to create the relational schema and insert relational data (if required). This file can be loaded using your favorite RDBMS command-line utility. This script is written using the most portable syntax, however if an alternate script is not provided for your RDBMS (check for load_rdbms.sql files) you may need to adjust it by yourself.
  • In the case of extraction examples, a list of files containing queries.
  • In the case of insertion examples, the schema, mapping and document files.
  • In the case of examples using Java code (XML/DBC API and insertion with generators), the source code itself, the Ant build.xml file used to compile the example, plus any support file required to run the example.

Note that all the source files have been compiled using Ant (version 1.5.4). Any other build tool should work as well, but you will need to write your own build file.

The command-line examples given below assume that the XQuare Bridge command-line tool has been properly configured, as detailed in the installation guide.

Note
1. For insertion examples, after the command has been executed, the database can be consulted to check that the data has been correctly inserted
2. The extraction (XQuery) example commands will print the query results on the standard output.
3. For all kinds of samples, the SQL instructions present in the load.sql file must have been previously executed in order to create the required relational structures and data.
Example directoryDescription
samples/xqueryThis directory contains several subdirectories of examples showing the Bridge querying capabilities.
+ W3C-use-cases-4RThis directory contains a set of XQuery files (.xqy), adapted from the relational use-cases specified by the W3C. Each query can be executed using the following command:
xqbridge -q q4-xx.xqy
samples/xquery/viewsThis directory contains several subdirectories of examples showing the Bridge querying capabilities using XQuery views (functions).
+ 1-XMPThis directory contains a set of XQuery files (.xqy), view files (.mod) and schema files (.xsd) adapted from the use-cases "XMP" specified by the W3C. Each query can be executed using the following command:
xqbridge -q q1-xx.xqy
+ 4-R This directory contains a set of XQuery files (.xqy), view files (.mod) and schema files (.xsd) adapted from the use-cases "XMP" specified by the W3C. In fact, queries have been appreciably modified to demonstrate views but data and results have been preserved. Each query can be executed using the following command:
xqbridge -q q4-xx.xqy
+ simpleThis directory contains a set of XQuery files (.xqy) and view files (.mod). The specificity of the contained examples is that the view used is not typed. Each query can be executed using the following command:
xqbridge -q qxx.xqy
samples/mappingStorage examples.
+ basic This directory contains an example based on a purchase order schema, together with a basic mapping to store XML data in relational columns, without storing any relations between document elements. XML data can be stored in the database using the following command:
xqbridge -i po.map po1.xml
+ auction This directory contains another simple example based on an auction database, which is used in the provided XQuery samples. XML data can be stored in the database using the following command:
xqbridge -i auction.map auction.xml
Once this data is loaded, sample XQueries can also be executed without the need to set up the database using the provided SQL scripts.
+ purchaseOrder This directory contains a more complex example based on the same purchase order schema, but using a complex mapping to store both XML data in relational columns and relations between document elements. This example also uses user-defined generators to generate internal primary keys while storing the document content. Note that those generators must be compiled before running the samples. This example can be executed by using the following command:
xqbridge -i po.map po1.xml
+ references This directory contains a mapping example showing one solution to use the mapping directives to implement data transcoding based on reference tables. Another solution could use a substitution generator (see transform example). This example can be executed by using the following command:
xqbridge -i product.map product.xml
+ association This directory contains a mapping example showing how to write a mapping that generates an N-N relation using an association table. It uses the org.xquark.mapping.KeyGenerator built-in generator for key generation. This example can be executed by using the following command:
xqbridge -i association.map association.xml
+ simpleContent This directory contains a mapping example showing how to map entirely a simple content element (potentially with attributes) on a table. This kind of mapping uses a mapping language "trick" since it does not allow the user to define both a table and a column mapping on an element. This example can be executed by using the following command:
xqbridge -i simple.map simple.xml
+ transformThis sample shows how to use both a plain and a sustitution generator to perform simple XML data transformation before storage (the example taken is capitalization of a string). This example can be executed by using the following command:
xqbridge -i transform.map transform.xml
samples/xdbcAPI examples.
+ querier1 This example is provided as an illustration of the use of the XML/DBC API. It creates a very simple application which reads a query from a file, executes it and prints the query results on the standard output. The Main.java source should be adapted to your environnement. You should modify the user name, the user password and the JDBC connection URL of the underlying database to be used. After the source code has been compiled, the example can be executed using the run script:
run <query file>
+ querier2 This example is provided as an illustration of the use of the XML/DBC API. It creates a very simple application which reads a query from a file, executes it and prints the query results on the standard output. A configuration file config.xml should be updated according your environnement. You should modify the user name, the user password, the JDBC connection URL of the underlying database and also the relational schema to be used. The <catalogue> element describes the relational tables on which the XQuery requests will be processed. After the source code has been compiled, the example can be executed using the run script:
run <query file>
+ mapper This example is provided as an illustration of the use of the mapping API. It creates a very simple application which stores an XML document in the database, based on the specified mapping file. Database access is hard-coded in the source code and will probably need to be updated for the example to run correctly. After the source code has been compiled, the example can be executed using the runscript:
run <map file> <xml file>
samples/servletThis example is provided as an illustration of the use of the API within a simple servlet. It creates a simple Web application which can either store an XML document in the database, based on some predefined mapping files, or issue an XQuery and produce an XML document. This example can be deployed as a standard Web application in the Apache Tomcat Web server. The location of the Web server deployment directory must be specified by setting the catalina.home variable in the Ant build.xml file or in the build.properties file. The servlet accesses a jndi data source that should be configured in your favorite web server configuration files, the name of the source is 'jdbc/TestDB'. You must in fact fill all the properties of the build.properties file, just following the instructions given inside. After the source code has been compiled and deployed (using the 'compile' and 'deploy' ant tasks), be sure to add your favourite DBMS JDBC driver in the lib folder under the Tomcat 'xqbridge' application folder (avoid .zip files, use .jar). The example can be run using the following URL (assuming Tomcat is running locally in its standard configuration):
http://localhost:8080/xqbridge
Note: You will need to execute the load.sql scripts contained in the xqbridge\WEB-INF\mappings folders in order to use the "insert document" function of the servlet.On the other hand, the generators are automatically compiled during servlet build.
by Odonata