XQuery FAQ

Q: Where can I find example code and how do I run it?

Some Java examples can be found in the samples/org/exist/examples directory. These examples have already been compiled into examples.jar. If you want to compile them yourself, call

To run an example class, you need all the jars from lib/core, exist.jar and examples.jar in your classpath. However, you can also use the bootstrap loader (in start.jar), which takes care to set up a correct environment for eXist. For example:

runs the XQueryExample class.

Q: How do I properly shut down eXist when running as a servlet in Tomcat?

If you are using one of the development snapshots, the EXistServlet or XQueryServlet implement Servlet.destroy() and should correctly shut down the db. This is missing in 1.0b1, I think.

If you are running the standard distribution, you can also go to the status page:

enter admin user and password and press shutdown. This will only shut down the db, not tomcat.

should also work. However, it assumes eXist is running at http://localhost:8080/exist/. If you have a different setup, specify the -l parameter and enter the XML:DB URI of the root collection, e.g.

Q: How do I shut down an embedded database instance?

I am trying to close embeded daatbase instance with DatabaseInstanceManager method shutdown, but I'm getting this exeption: Exception in thread "main" org.xmldb.api.base.XMLDBException: only users in group dba may shut down the database.

A: As the message says, only database administrators, i.e. members of the "dba" group are allowed to shut down the database. You should thus use the admin user when opening the collection from which you retrieve the DatabaseInstanceManager service:

Q: How do I get eXist to start at boot on a Linux box?

A: The installer generates a standard Unix start/stop script in tools/wrapper/bin/exist.sh. Create a link to this file from /etc/init.d:

Depending on your distribution, you have to create another link in /etc/rc.d. On Debian, you can just do:

Q: Does the XML:DB API driver always use XMLRPC calls to talk to the database?

I was wondering: eXist has its own implementation of XML:DB.

When eXist is running in Tomcat as a servlet and I'm trying to access the db with the eXist XML:DB api with another servlet, does the xmldb getCollection use XMLRPC to connect to the database?

Does this mean it always communicates trough XMLRPC when in servlet mode? I can't get the overall picture of what happens when accessing the database, now it seems to mee that it will alway channel trough the eXist xmlrpc server.

Is there a simple way to explain what the different access methods makes them unique, and whicht to prefer?

A: eXist provides two XML:DB database drivers:

1. the local driver tries to establish a direct connection to the database, using eXist's internal API. No network connection is used in this case.

1. the remote driver is based on XMLRPC and all XML:DB method calls will be translated into the corresponding XMLRPC calls.

Which driver is selected does simply depend on the XML:DB URI passed to getCollection: if the URI specifies a hostname, the connection will be remote. If the hostname part is empty (///db), the connection will be local.

You can also use both types of connections if eXist is running in servlet mode. But: using the local XML:DB driver is only possible if eXist is running within the same servlet context as your application servlet. The database instance has to live in the same context or you won't be able to connect to it.

Q: I can't access request or session parameters when connecting to a remote server

Using the XQueryGenerator, everything is ok when I connect to the embedded (default) db, but when I connect to a stand-alone instance using the parameter <map:parameter name="collection" value="xmldb:exist://localhost:8081/db"/> I get the following exception:

A: The request, response and session objects from the current HTTP context are NOT forwarded to a remote server, so the request:request-parameter() function complains that these objects are missing.

Thus, when working with a remote server, you have to explicitely declare parameters as XQuery variables, for example, by passing them via map:parameter (all additional Cocoon parameters are declared as XQuery variables).

Forwarding of HTTP request data could be implemented, but the benefits are rather questionable: first, marshalling/unmarshalling the data in the XMLRPC request sent to the server implies a lot of overhead; second,there would be some confusion about which request object is actually passed to the query: the one of the XMLRPC request or a forwarded one.

Q: I get exceptions trying to access uploaded files from an xquery script

A: To access the uploaded file parameter, you should use the special function: request:get-uploaded-file(param). This returns a Java File object which can then be passed to xdb:store(collection, docName, file).

Q: Why do I get errors when trying to use some Cocoon blocks?

A: The cocoon included with eXist has been compiled with just a minimal set of blocks (otherwise the package would be much larger), in particular: databases, xmldb and xsp. If you need other blocks, you have to get them from the official cocoon distribution.

Q: Wrong character encoding of query parameters?

When using the eXist .war distribution, e.g. installed in Tomcat, character encodings do not correctly arrive at my XQuery script on the server. The parameter encodings are messed up.

A: It depends on the default character encoding used by the servlet engine (and your operating system). If the web browser sends correct UTF-8 but the servlet engine transcodes this into latin-1, parameter values will be a mess.

Both, the XQueryServlet and Cocoon provide parameters in WEB-INF/web.xml to force request parameters into the desired encoding:

You probably have to change the container-encoding to ISO-8859-1. The Jetty version packaged with eXist handles encodings correctly, so UTF-8 is specified for both parameters.