This article explains how to install eXist-db as a stand-alone or embedded server.
There are three ways to deploy the eXist-db database:
- In a Servlet Context
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 is deployed according to instructions provided in the Basic Installation Guide.
In this mode all resources used by eXist-db will have paths relative to the web application's current context. For example, eXist will store all its database files in the
WEB-INF/datadirectory of the web application (unless specifically configured otherwise).
- 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, WebDAV protocol or the REST-style HTTP API.
- 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 JVM as the client, no network connection is needed. The client has full access to the database.
All three deployments are thread-safe and allow concurrent operations by multiple users. 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.
Detailed instructions on how to set up eXist-db for use with a servlet-engine are provided in the Basic Installation Guide. The sections in this document address the other two deployment options.
Section 2 introduces 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
Section 4 addresses the required steps to directly embed eXist into an application, including how to embed it in the XMLdbGUI.
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 therefore 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. The user should not have to be aware of where a resource is physically located. 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.
- In a Servlet Context
Use the following URI to points to the Shakespeare collection on a remote server which is running in a servlet engine:
The host part:
localhost:8080/exist/xmlrpcdescribes the path to the XML-RPC listener, which is running as a servlet. The collection part (
/db/shakespeare) defines the collection to retrieve.
- Stand-alone Server Process
If eXist had started as a stand-alone server, the URI would change its port to
- Embedded in an Application
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:
You can use the Java Admin Client, which utilizes the XML:DB API to access the database, to experiment with these settings. The Login dialog offers a text field where you can specify an XML:DB URI to connect to.
By default, the client tries to access the database engine located at the base URI:
Change the entry in the GUI to try another URI or pass it using the
-ouri option on the command line. For example:
This will cause a local database instance to run in the same Java virtual machine as the client.
There is also a short form for this command. The
-l option causes the client to launch a local database instance. For
The standard distribution by default launches eXist-db as a web application deployed in a Jetty servlet container.
The Jetty configuration can be found in
tools/jetty/webapps/exist-webapp-context.xml. It defines a single web application context value
<Set name="contextPath">/exist</Set>, mapped to the
webapp directory. This value can be set to either
/. Users modifying this value should subsequently remove the
portal folder at
/tools/jetty/webapps, which contains the default exist-db splashscreen displayed during certain redirects.
Jetty is small, efficient and stable, so there is 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 all major releases. You may either download that or, if you already installed
the standard distribution, build a
.war archive yourself. For details on how to do this, see Building eXist-db
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. For instance:
jar xfv exist.war
Please remember that the
log directories need to be writable!
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
To start the Java Admin Client, use the following command (from within
web application's root directory):
java -jar WEB-INF/lib/start.jar client -ls
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.
The stand-alone deployment is more reliable and performs better than the web application setup, since no other threads (simultaneous tasks) are running. 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.
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
To start the server use either the
bin/server.sh (Unix) or the
bin\server.bat (Windows) command.
The server is multi-threaded, a server thread is assigned to each client request. If the specified maximum number of threads is reached,
the server will block the client until one of the server-threads is available to respond. By default, the maximum number of threads is 5. To
change this, use the
-t option, e.g.:
bin\server.bat -t 20
To access the stand-alone server using the Java Admin Client (or by your own Java classes),
start the XML:DB server URI to
tools/jetty/etc/standalone/WEB-INF/web.xml configuration file is used when the server operates in standalone mode.
An instance of the Jetty web server is configured using its settings. The services offered with eXist have their own configuration servlet
element in this file.
Currently, the servlet API alternatives are "
xmlrpc", and "
rest". Any of
these servlets can be disabled by setting a init-param
enabled attribute to "
You can control the binding address by changing the addConnector
<Call> element in
The port on which the server will listen. The Jetty web server will bind to port
The host-name on which the server will respond.
The IP address on which the server should bind. This may be useful when the server has multiple addresses that serve the same host-name.
The WebDAV servlet provides services at the context address specified. This servlet is represented by the
<webdav> element in
server.xml configuration file. For this element, the
context attribute controls the web server
context at which the WebDAV services are provided. If the
context attribute is not specified, it defaults to
The XML-RPC servlet provides database API services to clients, like the Admin GUI client. This servlet is represented by the
<xmlrpc> element in the
server.xml configuration file. For this element, the
attribute controls the web server context at which the XMLRPC services are provided. If the
context attribute is not
specified, it defaults to
If you disable this servlet, you disable the use of the Java Admin Client.
The REST servlet provides HTTP/REST-style interactions with the database. It is configured by a
<servlet> element with
org.exist.http.servlets.EXistServlet in the
tools/jetty/etc/standalone/WEB-INF/web.xml configuration file.
It depends on the
XQueryURLRewrite filter for context, default is
The REST Servlet has a number of other parameters that can be set by child elements:
The default encoding of form POSTs.
The default encoding of the servlet container for all HTTP interactions except POSTs.
A boolean value (
false) that indicates whether the effective user must be used for non-authenticated interactions. If any of these fails a simple AUTH interaction is undertaken.
The username of the default user.
The password of the default user.
Any servlet can be configured to run in the Jetty server by adding a
<servlet> element to the
configuration file. The
<servlet> element has the standard attributes of
context, as well as
class attribute to specify the servlet implementation class.
This element can have any number of
<param> child-elements to set parameters for the servlet. For example:
The forwarding-request settings allow you to map incoming URL requests to specific resources on the server (e.g. queries). This is done
<forwarding> element. Inside this element is a single
<root> element and any number of
<forward> element specifies a specific primary URL that is forwarded to secondary URL. This allows you to map a "clean"
URL to an XQuery or some other resource within the server. The target is always specified by a
destination attribute. For
Here the first
<forward> element maps the URI path
/admin to the XQuery resource
/db/admin/admin.xql, the second one maps the URI path
/docs to the document
<root> element maps requests to the root directory of the server (for instance
/) to a specified
resource. For example:
This maps a requests for the (default) server root to the XQuery resource
shutdown.bat (Windows/DOS) and
shutdown.sh (Unix) scripts to shutdown the database. These
commands connect to the default server URI, usually
If your database is running in stand-alone mode, you must specify a different server URI. For instance, to stop eXist when running in
stand-alone mode, listening on port
java -jar start.jar shutdown --uri=xmldb:exist://localhost:8088/xmlrpc
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-db into any Java application using the XML:DB API.
To prepare the environment for using an embedded eXist, follow the steps below:
log4j.xmlto the target directory.
Create a subdirectory
datain the target directory.
filesattribute in the
conf.xmlto point to this data directory.
Do the same for the
To see logging output, edit
log4j.xml. The simplest way is to change the
console. This will result in most log messages being written to the console.
libdirectory below the target directory and copy the following
.jarfiles from eXist-db into it:
If you plan to use extension modules (like the n-gram index), copy the corresponding jars from
lib/extensions. The default eXist configuration needs:
For the Lucene module copy the jars from
lib/endorseddirectory furthermore plays a special role: the Java releases come with their own XML support libraries, including Xalan (for XSLT processing), an XML parser, and the standard Java interfaces for SAX and DOM. Some features of eXist will not work properly with a wrong version of Xerces or the resolver
.jar(schema validation, catalog loading, ...). To ensure the correct versions are available, we have included these versions of Xerces, Xalan and Saxon, plus the standard interfaces used by both of them. You can use Java's endorsed library loading mechanism to ensure the correct XML support libraries are loaded.
Create a directory
.jarfiles from eXist's
lib/endorseddirectory into the newly created directory
-Djava.endorsed.dirs=lib/endorsedsystem property on the Java command line will force the JVM to prefer any library it finds in the endorsed directory over its own system libraries (copying the jars into
$JAVA_HOME/jre/lib/endorsedwill do the same thing). Note that the batch and shell scripts included with eXist all set the
java.endorsed.dirssystem property to point to
Make sure your
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 (for instance
localhost:8088/xmlrpc/) from the URI. For
To start an embedded database instance, simply set the system property
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 absent) and launch the database.
The driver must be able to read the configuration file
conf.xml. It seraches for
conf.xml in the
directory specified by the
exist.home system property. You should therefore ensure a copy of
present in the correct directory. For example, to launch your own application, while setting
java -Dexist.initdb=true -Dexist.home=/home/exist/eXist MyApp
The paths to the data and log directories in
conf.xml need to point to writable
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 within your Java code. Set the
create-database property on the
Database object to
true. For example:
When running eXist in embedded mode, ensure proper shutdown the database before your application exits. The main reason 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 disk, and this thread will keep running unless you shutdown the database.
There is a special XML:DB service,
DatabaseInstanceManager, which contains a single method:
To properly shutdown 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, store it into the target directory (which we prepared above), and compile and
run it with:
javac TestDB.java java -Dexist.initdb=true -Dexist.home=. TestDB