Database Deployment

Overview

There are three ways to deploy the eXist-db database:

1. In a Servlet Context

   In this case, the database is deployed as part of a web application. eXist will happily live together with other servlets. This is the default mode established when the database has been deployed according to instructions provided in the Quick Start Guide.

   All resources used by eXist-db in this mode will have paths relative to the web application's current context. For example, eXist will store all its database files in the WEB-INF/data directory of the web application.

2. Stand-alone Server Process

   In stand-alone mode, eXist-db runs in its own Java virtual machine (JVM). Clients have to access the database through the network, either using the XML-RPC or WebDAV protocol or the REST-style HTTP API (see the Developer's Guide).

3. Embedded in an Application

   In embedded mode, the database is basically used as a Java library, controlled by the client application. It runs in the same Java virtual machine as the client, thus no network connection is needed and the client has full access to the database.

Note that all three deployments are thread-safe and allow concurrent operations by multiple users. Also note that servlets running in the same web application context will have direct access to the database. External client applications may still use the supplied network interfaces.

As detailed instructions on how to set up eXist-db for use with a servlet-engine are provided in the Quick Start Guide, the sections in this document concern the other two deployment options. In section 2, we introduce the XML:DB URI and explain how different servers are addressed by Java clients. Section 3 deals with running eXist as a stand-alone server, and in Section 4 we discuss the required steps to directly embed eXist into an application, including how to embed in the XMLdbGUI.

Addressing Different Servers using the XML:DB URI

One way to access eXist-db from Java applications is to use the XML:DB API. The XML:DB API uses a specific URI scheme to locate a collection of XML resources on the server. You will encounter XML:DB URIs when working with the Java client, the backup tools and sometimes in XQuery functions. It is thus important to understand how the URI scheme addresses servers and resources.

eXist's XML:DB API implementation supports transparent access to remote as well as embedded database servers. This means the database on the server is available on the client as though it were locally connected to the client - i.e. the user should not have to be aware of where a resource is physically located. Given this transparency, applications need not be affected by how the database has been deployed.

The XML:DB URI identifies the database implementation, the name of the collection, and optionally the location of the database server on the network. For example, the URI:

xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare

points to the shakespeare-collection on a remote server which is running in a servlet-engine. The host part: localhost:8080/exist/xmlrpc describes the path to the XML-RPC listener, which is running as a servlet. The collection part (/db/shakespeare) defines the collection to retrieve. If eXist had started as a stand-alone server, the URI would change its port to 8088 to become:

xmldb:exist://localhost:8088/xmlrpc/db/shakespeare

Finally, to access an embedded instance of the database, we simply drop the host part altogether, and use three forward slashes (///) in front of the collection path:

xmldb:exist:///db/shakespeare

You can use the command-line client to experiment with these settings. The client utilizes the XML:DB API to access the database. The Login dialog offers a text field where you can specify an XML:DB URI to connect to. The default URI shown here is configured through a properties-file called client.properties. By default, the client tries to access the database engine located at the base URI:

xmldb:exist://localhost:8080/exist/xmlrpc/

To use the client with another server, you can simply change the uri property for the server location. For permanent changes, edit the properties-file client.properties. To make temporary changes, pass the -ouri option on the command line. For example, if you start the Admin client using the command:

bin/client.sh -ouri=xmldb:exist://

this will cause a local database instance to run in the same Java virtual machine as the client. Note that the short form for this particular command uses the -l option that causes the client to launch a local database instance - i.e.:

bin/client.sh -l

Deploying eXist-db in a Servlet Container

The standard distribution does by default launch eXist-db as a web application deployed in a servlet container (if you start eXist via bin/startup.sh or bin\startup.bat). The container used is Jetty.

The Jetty configuration can be found in tools/jetty/etc/jetty.xml. It defines a single web application context /exist, mapped to the webapp directory.

We think that Jetty is small, efficient and stable, so there's no need to switch to a different servlet engine unless your server setup requires this. However, it is not difficult to deploy eXist in a different servlet container, e.g. Apache's Tomcat.

We usually provide a .war web archive for download for all major releases. You may either download that or - if you already installed the standard distribution - build a .war archive yourself. For building the .war, you need the eXist sources. In the installer GUI, include the "source" module when selecting installable packages. To build the .war file, just call the main build script (build.sh or build.bat) with the target dist-war:

build.sh dist-war

To install the .war, just copy it into the corresponding folder below your servlet engine installation (usually webapps) and rename it to exist.war. The servlet engine will normally unpack the file when you restart the server. To have better control of where the file is unpacked, you can also create a directory exist below the webapps folder and manually extract the .war there, e.g. with:

jar xfv exist.war

There are a few differences between the standard distribution and the .war install: in particular, the configuration files are found in the WEB-INF directory, including the important files conf.xml (eXist configuration) and log4j.xml (logging). The example data is in samples.

To start the Java admin client (described in the QuickStart), use the following command line (from within the exist web application root directory:

java -jar WEB-INF/lib/start.jar client -ls

Running eXist-db as a Stand-alone Server

There are many cases in which it is preferable to have the database engine running in its own Java virtual machine. In stand-alone mode, eXist will launch its own, embedded web server to provide XML-RPC, WebDAV and REST services to the outside world. The embedded server is based on a stripped-down Jetty. It uses a limited configuration, excluding all the additional services available in a full-blown servlet environment.

In general, the stand-alone deployment is more reliable and performant than the web application setup, since no other threads (simultaneous tasks) are running. If your application does not need WebDAV or SOAP, you should use the stand-alone server.

The stand-alone database server offers XML-RPC, WebDAV and REST-style HTTP interfaces for external client access. Please note that it does not support SOAP. The XML-RPC and REST interfaces are explained in-depth in the Developer's Guide.

By default, the stand-alone server listens on port 8088, though this can be changed (see configuration below). The Java class for launching the server is org.exist.jetty.StandaloneServer.

bin/server.sh

bin\server.bat

bin\server.bat -t 20

xmldb:exist://localhost:8088/xmlrpc

xmldb:exist://localhost:8080/exist/xmlrpc

java -jar start.jar shutdown --uri=xmldb:exist://localhost:8088/xmlrpc

Embedding eXist in an Application

In the embedded mode, the database runs in the same Java virtual machine as the client application. The database will not be accessible by any outside application, and no network listeners are started.

You can embed eXist into any Java application using the XML:DB API. Other APIs might be added in the future. In particular, we are currently working to implement JSR 225: the "XQuery API for Java" (XQJ). However, until alternatives are available, we recommend using the XML:DB.

To prepare the environment for using an embedded eXist, follow the steps below:

Internally, eXist has two different XML:DB driver implementations: the first communicates with a remote database engine using XML-RPC calls; the second has direct access to a local instance of eXist. Which implementation is selected depends on the XML:DB URI as described above. To access an embedded database, simply drop the host portion (i.e. localhost:8088/xmlrpc/) from the URI - for instance:

xmldb:exist:///db

To start an embedded database instance, simply set the system property exist.initdb to true. This will notify the XML:DB driver to read the configuration settings when starting the database if none has been previously started. For example, to launch your own Java application with an embedded instance, you may enter the command:

java -Dexist.initdb=true MyApp

The driver will try to read the eXist configuration file, create the required database files if they have not already been created, and launch the database. This of course implies that the driver should be able to read the configuration file conf.xml. In fact, the driver looks for conf.xml in the directory specified by the exist.home system property. You should therefore ensure a copy of conf.xml is placed in the correct directory. For example, to launch your own application, while setting exist.home, you may enter:

java -Dexist.initdb=true 
				-Dexist.home=/home/exist/eXist MyApp

Instead of using the -Dexist.initdb property, you can also tell the database driver to create a local database instance during the initialization of the XML:DB database manager. To do this, simply set the create-database property on the created Database object to true - for example:

When running eXist in embedded mode, you must ensure to properly shut down the database before your application exits. The main reason for this action is to flush all of the unwritten data buffers to disk. The database uses a background thread to periodically synchronize its buffers with the data files on the disk, and this thread will keep running if you don't shut down the database.

There is a special XML:DB service, DatabaseInstanceManager, which contains a single method: shutdown. To properly shut down the database instance, retrieve the service from the /db-collection and call shutdown(). For example:

To summarize, a minimal working class with a single static main to start/stop the db may look like this:

Put this code into a Java file TestDB.java and store it into the target directory, which we already prepared above. Compile and run it with:

javac TestDB.java
			java -Dexist.initdb=true -Dexist.home=. TestDB