WIX

Overview

WIX (Web Interface for XQuery) is a simple service that allows users to submit an XQuery to query an XML document. The servlet interface for submitting XQueries is simple and efficient and can easily be called from any programming language, other instances of XQuery, or an HTML form.

Under the hood, WIX uses the Saxon XQuery Engine to do the heavy lifting.

By offering a service that accepts XQueries and generates XML results, WIX implements the query shipping paradigm (as opposed to document shipping which is a standard part of XQuery). Query shipping has several advantages over document shipping:

• For large documents you limit the overhead of downloading and parsing the entire document locally.
• For large documents you also limit the local RAM requirements of loading the document in memory.
• Because the query is executed remotely, clients don't need an embedded XQuery engine to process documents.
• The target document may actually be a view of another document (i.e. the result of another query).

The main disadvantage to shipping queries instead of documents is that because it isn't a standard part of XQuery, the syntax can become a little more difficult. This is only a problem when calling from XQuery and the solution is just to be careful about escaping strings.

Using

Details of using WIX and a live WIX demo are available on the Using WIX - Web Interface for XQuery page. The demo and examples use the bib.xml sample file from W3C XQuery Use Cases.

Server Requirements

• Servlet Container that supports Servlet API 2.4 such as Apache Tomcat 5.x
• Java runtime version 5.0 or greater (for example, Sun Java)
• Roughly 5 times as much free memory as the size of your XML document. You may need to set the maximum amount of memory for your servlet container if you have a large document.

Downloads

1. War generator for deploying WIX to a server.
2. XQuery module for calling a WIX server from within an XQuery.

Setting up the server

To deploy WIX to your Servlet container, we have provided a simple program that generates a WAR file containing your XML file and optionally your schema file.

1. Download WIX.zip and unzip it.
2. Open the WAR generator by double clicking on wix.jar. This should work if Java is properly installed on your machine.
3. Once open, give your service a name by filling in the first field. The name should be web friendly (no spaces or special characters)
4. Enter a file path or URL for your document and optionally your schema. Any URL should work and local files or files on your server should both work
5. If you entered URLs or files on the server, check the box labeled [These files are on the server]. If your XML or schema files are on your local machine, leave this box unchecked.
6. Click [Generate War]

To finish the process, you will need to deploy your WAR file to the server. This varies from server to server and so you should check your vendor's documentation. We have included the following instructions if you use Tomcat:

1. Make sure you have permission to deploy a webapp and the username/password
2. User your web browser to go to your manager application (http://your/server:8080/manager/html)
3. Scroll down to [Deploy] and find [Select WAR file to upload]. Browse to your generated WAR file and click [Deploy]
4. Test your new webapp by clicking on the name you used in your application list. This should bring up the test html page.

Troubleshooting the Server

These are problems that you may encounter, please see your server documentation for specific solutions

• Problem: I get an OutOfMemory error!

  Solution: Java requires that applications specify the maximum amount of memory they will use. This number is likely set in the batch file or shell script that launched your server. If you find a line that contains the string "Xmx" then you can set the memory there with Xmx=512m. Remember that each document will need about 5 times as much memory as its size.

• Problem: When I submit a very long query using the XQuery API, it doesn't return a result.

  Solution: The problem is that some servers sets a maximum length for a URL. This limit will likely work for most queries, but in some cases you will need to increase it. For example, in tomcat's server.xml you can do this by adding maxHttpHeaderSize="8192" to the <Connector> stanza.