<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: deployment.xml 17299 2012-10-10 23:47:33Z joewiz $ --><book><bookinfo><productname>Open Source Native XML Database</productname><title>Database Deployment</title><date>February 2010</date><author><firstname>Wolfgang M.</firstname><surname>Meier</surname><affiliation><address format="linespecific"><email>wolfgang at exist-db.org</email></address></affiliation></author><author><firstname>Leif-Jöran</firstname><surname>Olsson</surname><affiliation><address format="linespecific"><email>ljo at exist-db.org</email></address></affiliation></author></bookinfo><chapter><title>Database Deployment</title><section><title>Overview</title><para>There are <emphasis>three</emphasis> ways to deploy the eXist-db database:</para><orderedlist><listitem><para><emphasis>In a Servlet Context</emphasis></para><para>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 <ulink url="quickstart.xml">Quick Start
                            Guide</ulink>.</para><para>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 <filename>WEB-INF/data</filename> directory of the web
                        application.</para></listitem><listitem><para><emphasis>Stand-alone Server Process</emphasis></para><para>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 <ulink url="devguide.xml">Developer's Guide</ulink>).</para></listitem><listitem><para><emphasis>Embedded in an Application</emphasis></para><para>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.</para></listitem></orderedlist><para>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.</para><para>As detailed instructions on how to set up eXist-db for use with a servlet-engine are
                provided in the <ulink url="quickstart.xml">Quick Start Guide</ulink>, 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 <ulink url="http://titanium.dstc.edu.au">XMLdbGUI</ulink>.</para></section><section><title>Addressing Different Servers using the XML:DB URI</title><para>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.</para><para>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.</para><para>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:</para><synopsis format="linespecific">xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare</synopsis><para>points to the shakespeare-collection on a remote server which is running in a
                servlet-engine. The host part: <filename>localhost:8080/exist/xmlrpc</filename>
                describes the path to the XML-RPC listener, which is running as a servlet. The
                collection part (<filename>/db/shakespeare</filename>) defines the collection to
                retrieve. If eXist had started as a stand-alone server, the URI would change its
                port to <option>8088</option> to become:</para><synopsis format="linespecific">xmldb:exist://localhost:8088/xmlrpc/db/shakespeare</synopsis><para>Finally, to access an embedded instance of the database, we simply drop the host
                part altogether, and use three forward slashes (<option>///</option>) in front of
                the collection path:</para><synopsis format="linespecific">xmldb:exist:///db/shakespeare</synopsis><para>You can use the command-line client to experiment with these settings. The client
                utilizes the XML:DB API to access the database. The <command>Login</command> 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 <filename moreinfo="none">client.properties</filename>. By default, the client tries to
                access the database engine located at the base URI:</para><synopsis format="linespecific">xmldb:exist://localhost:8080/exist/xmlrpc/</synopsis><para>To use the client with another server, you can simply change the
                    <option>uri</option> property for the server location. For permanent changes,
                edit the properties-file <filename moreinfo="none">client.properties</filename>. To
                make temporary changes, pass the <option>-ouri</option> option on the command line.
                For example, if you start the Admin client using the command:</para><synopsis format="linespecific">bin/client.sh -ouri=xmldb:exist://</synopsis><para>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
                    <option>-l</option> option that causes the client to launch a local database
                instance - i.e.:</para><synopsis format="linespecific">bin/client.sh -l</synopsis></section><section><title>Deploying eXist-db in a Servlet Container</title><para>The standard distribution does by default launch eXist-db as a web application
                deployed in a servlet container (if you start eXist via <filename>bin/startup.sh</filename> or <filename>bin\startup.bat</filename>). The
                container used is <ulink url="http://jetty.mortbay.org/">Jetty</ulink>.</para><para>The Jetty configuration can be found in <filename>tools/jetty/etc/jetty.xml</filename>.
                It defines a single web application context <command>/exist</command>, mapped to the
                    <filename>webapp</filename> directory.</para><para>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.</para><para>We usually provide a <filename>.war</filename> 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 (<filename>build.sh</filename> or <filename>build.bat</filename>) with the
                target <option>dist-war</option>:</para><synopsis>build.sh dist-war</synopsis><para>To install the .war, just copy it into the corresponding folder below your servlet
                engine installation (usually <filename>webapps</filename>) and rename it to
                    <filename>exist.war</filename>. 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 <filename>exist</filename> below the <filename>webapps</filename> folder and manually extract the .war there, e.g.
                with:</para><synopsis>jar xfv exist.war</synopsis><important><para>Please remember that the <filename>data</filename> and <filename>log</filename> directories need to be writable!</para></important><para>There are a few differences between the standard distribution and the .war
                install: in particular, the configuration files are found in the <filename>WEB-INF</filename> directory, including the important files <filename>conf.xml</filename> (eXist configuration) and <filename>log4j.xml</filename>
                (logging). The example data is in <filename>samples</filename>.</para><para>To start the Java admin client (described in the <ulink url="quickstart.xml">QuickStart</ulink>), use the following command line (from within the <filename>exist</filename> web application root directory:</para><synopsis>java -jar WEB-INF/lib/start.jar client -ls</synopsis></section><section><title>Running eXist-db as a Stand-alone Server</title><para>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.</para><para>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.</para><para>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 <ulink url="devguide.xml">Developer's Guide</ulink>.</para><para>By default, the stand-alone server listens on port <filename>8088</filename>,
                though this can be changed (see configuration below). The Java class for launching
                the server is <classname>org.exist.jetty.StandaloneServer</classname>.</para><section><title>Starting the Stand-alone Server</title><para>To start the server, launch either the Unix shell script:</para><synopsis format="linespecific">bin/server.sh</synopsis><para>OR the Windows/DOS batch file:</para><synopsis format="linespecific">bin\server.bat</synopsis><para>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
                        <option>-t</option> option, e.g.:</para><synopsis format="linespecific">bin\server.bat -t 20</synopsis><para>To access the stand-alone server using the interactive command line client (or
                    by your own Java classes), you must change the XML:DB server URI set by the
                        <option>uri</option> property, as described above, to the following:</para><synopsis format="linespecific">xmldb:exist://localhost:8088/xmlrpc</synopsis></section><section><title>StandaloneServer Configuration with tools/jetty/etc/standalone/WEB-INF/web.xml</title><para>The <filename>tools/jetty/etc/standalone/WEB-INF/web.xml</filename> configuration file is used when the
                    server operates in standalone mode, in which case, an instance of the Jetty web
                    server is configured using its settings. As for the services offered with eXist,
                    each has its own configuration servlet element in this file. Currently, the servlet API
                    alternatives are "<option>webdav</option>, "<option>xmlrpc</option>", and
                        "<option>rest</option>". Any of these servlets can be disabled by setting
                    a init-param <option>enabled</option> attribute to "<option>no</option>".</para>
		    <!--
                <note>
                    <para>Note that you can control the location of this document by setting the
                            <code>server.xml</code> Java system property when you start the server,
                        e.g.:</para>
                    <synopsis>java -Dserver.xml=server2.xml -jar start.jar standalone</synopsis>
                </note> --><para>The standalone.xml/web.xml document has the following basic structure:</para><example><title>Sample Configuration File: web.xml</title><programlisting><markup>fixme!/ljo
</markup></programlisting></example><section><title>Controlling the Binding Address (&lt;indexer&gt;)</title><para>You can control the binding address by changing the addConnector <sgmltag>Call</sgmltag> element in tools/jetty/etc/standalone.xml:</para><variablelist><varlistentry><term>port</term><listitem><para>The port on which the server will listen. The Jetty web server
                                    will bind to the port <filename>8088</filename>
                                    by default.</para></listitem></varlistentry><varlistentry><term>host</term><listitem><para>The hostname on which the server will respond.</para></listitem></varlistentry><varlistentry><term>address</term><listitem><para>The IP address on which the server should bind. This may be
                                    useful when the server has multiple addresses that serve the
                                    same hostname.</para></listitem></varlistentry></variablelist></section><section><title>WebDAV Servlet</title><para>The WebDAV servlet provides services at the context address specified.
                        This servlet is represented by the <sgmltag>webdav</sgmltag> element in the
                            <filename>server.xml</filename> configuration file. For this element,
                        the "<option>context</option>" attribute controls the web server context at
                        which the WebDAV services are provided. If the "<option>context</option>"
                        attribute is not specified, it defaults to <filename>/webdav/</filename>.</para></section><section><title>XML-RPC Servlet</title><para>The XML-RPC servlet provides database API services to clients like the
                        Admin GUI client. This servlet is represented by the
                            <sgmltag>xmlrpc</sgmltag> element in the <filename>server.xml</filename>
                        configuration file. For this element, the "<option>context</option>"
                        attribute controls the web server context at which the XMLRPC services are
                        provided. If the "<option>context</option>" attribute is not specified, it
                        defaults to <filename>/xmlrpc/</filename>. Note that if you disable this
                        servlet, you effectively disable the use of the admin client.</para></section><section><title>REST Servlet</title><para>NB! Updated for Jetty 7 in trunk from December 2009</para><para>The REST servlet provides HTTP/REST-style interactions with the database.
                        It is configured by a <sgmltag>servlet</sgmltag> element with  <sgmltag>servlet-class</sgmltag>org.exist.http.servlets.EXistServlet in the <filename>tools/jetty/etc/standalone/WEB-INF/web.xml</filename> configuration file. It depends on the XQueryURLRewrite filter for the context, defaults is <filename>/</filename>.</para><para>The RestServlet has a number of other parameters that can be
                        set by child elements:</para><example><title>RestServlet Structure</title><programlisting><markup>&lt;servlet&gt;
        &lt;servlet-name&gt;EXistServlet&lt;/servlet-name&gt;
        &lt;servlet-class&gt;org.exist.http.servlets.EXistServlet&lt;/servlet-class&gt;
      &lt;init-param&gt;
            &lt;param-name&gt;use-default-user&lt;/param-name&gt;
            &lt;param-value&gt;true&lt;/param-value&gt;
        &lt;/init-param&gt;
...
 &lt;/servlet&gt;</markup></programlisting></example><variablelist><varlistentry><term>form-encoding</term><listitem><para>The default encoding of form POSTs.</para></listitem></varlistentry><varlistentry><term>container-encoding</term><listitem><para>The default encoding of the servlet container for all HTTP
                                    interactions except POSTs.</para></listitem></varlistentry><varlistentry><term>use-default-user</term><listitem><para>A boolean value (<option>true</option>/<option>false</option>)
                                    that indicates whether a user you supply the credentials 
				    <option>user</option> and <option>password</option> for 
				    or if the <option>guest</option> user with default password should be
                                    used for non-authenticated interactions. 
				    If any of these fails a simple AUTH interaction is undertaken.
				</para></listitem></varlistentry><varlistentry><term>user</term><listitem><para>The username of the default user.</para></listitem></varlistentry><varlistentry><term>user</term><listitem><para>The password of the default user (required when every users
                                    has a password).</para></listitem></varlistentry></variablelist></section><section><title>Custom Servlets</title><para>Any servlet can be configured to run in the Jetty server by adding a
                        'servlet' element to the server.xml configuration file. The 'servlet'
                        element has the standard attributes of 'enabled' and 'context' as well as
                        the 'class' attribute to specify the servlet implementation class.</para><para>This element can have any number of <option>param</option> element
                        children to set parameters on the servlet. The structure looks like:</para><example><title>&lt;rest&gt;-&lt;param&gt; Structure</title><programlisting><markup>&lt;servlet enabled="yes" context="/myservlet/*" class="com.example.MyServlet"&gt;
      &lt;param name="auth" value="true"  /&gt;
      &lt;param name="demo" value="false"  /&gt;
 &lt;/servlet&gt;</markup></programlisting></example></section><section><title>Forwarding Requests</title><para>The forwarding-request settings allow you to map incoming URL requests to
                        specific resources on the server (e.g. queries). All of which are
                        encapsulated in the <sgmltag>forwarding</sgmltag> element. Inside this
                        element is a single <sgmltag>root</sgmltag> element and any number of
                            <sgmltag>forward</sgmltag> elements. Each of these latter elements
                        specifies a specific URL path that is forwarded to secondary URL path. 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 <option>destination</option>
                        attribute.</para><para>The <sgmltag>root</sgmltag> element maps requests to the root directory of
                        the server (i.e. the "<filename>/</filename>" path) to a specified resource.
                        For example:</para><example><title>Root Map (&lt;root&gt;)</title><programlisting><markup>&lt;root destination="/db/admin/admin.xql" /&gt;</markup></programlisting></example><para>The above element maps requests for the (default) server root to the
                        XQuery resource <filename>/db/admin/admin.xql</filename>.</para><para>The <sgmltag>forward</sgmltag>element, on the other hand, maps the request
                        specified by the <option>path</option> attribute to a resource. For
                        example:</para><example><title>Forward Maps (&lt;forward&gt;)</title><programlisting><markup>&lt;forward path="/admin" destination="/db/admin/admin.xql"/&gt;
&lt;forward path="/docs" destination="/db/products/docs.xml"/&gt;</markup></programlisting></example><para>In this example, the first element (&lt;forward&gt;) maps the URI path
                            <filename>/admin</filename> to the XQuery resource <filename>/db/admin/admin.xql</filename>, while the second element maps the URI
                        path <filename>/docs</filename> to the document <filename>/db/products/docs.xml</filename>.</para></section></section><section><title>Shutting Down the Database</title><para>By default, the <filename>shutdown.bat</filename> (Windows/DOS) and <filename>shutdown.sh</filename> (Unix) scripts try to connect to the default server
                    URI - i.e.:</para><synopsis format="linespecific">xmldb:exist://localhost:8080/exist/xmlrpc</synopsis><para>If your database is running in stand-alone mode, you must specify a different
                    server URI. Specifically, to stop eXist when running in stand-alone mode
                    listening on port <option>8088</option>, use the following:</para><synopsis format="linespecific">java -jar start.jar shutdown --uri=xmldb:exist://localhost:8088/xmlrpc</synopsis></section></section><section><title id="embedded">Embedding eXist in an Application</title><para>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.</para><para>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.</para><para>To prepare the environment for using an embedded eXist, follow the steps
                below:</para><procedure><step><para>Copy <filename>conf.xml</filename> and <filename>log4j.xml</filename> to
                        the target directory.</para></step><step><para>Create a subdirectory <filename>data</filename> in the target directory.
                        Edit the <option>files</option> attribute in the
                            <option>db-connection</option> section of <filename>conf.xml</filename>
                        to point to this data directory. Do the same for the
                            <option>journal-dir</option> in the <option>recovery</option>
                        element.</para><para>To see logging output, edit <filename>log4j.xml</filename>. The simplest
                        way is to change the <option>appender-ref</option> in the
                            <sgmltag>root</sgmltag> category to <option>"console"</option>, which
                        will result in most log messages being written to the console.</para></step><step><para>Create a <filename>lib</filename> directory below the target directory and
                        copy the following <filename>.jar</filename> files from eXist-db into it:</para><itemizedlist><listitem><para><filename>exist.jar</filename></para></listitem><listitem><para><filename>lib/extensions/exist-modules.jar</filename></para></listitem><listitem><para><filename>lib/core/antlr-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/commons-pool-X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/commons-collections-X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/commons-logging-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/log4j-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/optional/slf4j-api-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/optional/slf4j-log4j12-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/quartz-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/sunxacml.jar</filename></para></listitem><listitem><para><filename>lib/core/xmldb.jar</filename></para></listitem><listitem><para><filename>lib/core/xmlrpc-client-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/xmlrpc-common-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/xmlrpc-server-X.X.X.jar</filename></para></listitem><listitem><para><filename>lib/core/jta.jar</filename></para></listitem><listitem><para><filename>lib/core/pkg-repo.jar</filename></para></listitem></itemizedlist><para>If you plan to use extension modules (like the n-gram index), you also
                        need to copy the corresponding jars from <filename>lib/extensions</filename>. The default eXist configuration needs:</para><itemizedlist><listitem><para><filename>exist-ngram-module.jar</filename></para></listitem><listitem><para><filename>exist-lucene-module.jar</filename></para></listitem><listitem><para><filename>exist-versioning.jar</filename></para></listitem></itemizedlist><para>For the Lucene module you also need to copy the jars from <filename>extensions/indexes/lib</filename>:</para><itemizedlist><listitem><para><filename>lucene-core-X.X.X.jar</filename></para></listitem><listitem><para><filename>lucene-regex-X.X.X.jar</filename></para></listitem></itemizedlist><para>The <filename>lib/endorsed</filename> directory 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 that 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 that the correct XML support libraries are loaded. <itemizedlist><listitem><para>Create a directory <filename>endorsed</filename></para></listitem><listitem><para>Copy all jar files from eXist's <filename>lib/endorsed</filename> directory into the newly created
                                    directory</para></listitem></itemizedlist>Specifying the
                            <option>-Djava.endorsed.dirs=lib/endorsed</option> system 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
                            <filename>$JAVA_HOME/jre/lib/endorsed</filename> will do the same thing.
                        Note that the batch and shell scripts included with eXist all set the
                            <option>java.endorsed.dirs</option> system property to point to
                            <filename>lib/endorsed</filename>.</para></step><step><para>Make sure your CLASSPATH includes these jar files.</para></step></procedure><para>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. <filename>localhost:8088/xmlrpc/</filename>) from the URI -
                for instance:</para><synopsis format="linespecific">xmldb:exist:///db</synopsis><para>To start an embedded database instance, simply set the system property <property>exist.initdb</property> to <option>true</option>. 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:</para><synopsis format="linespecific">java -Dexist.initdb=true MyApp</synopsis><para>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
                    <filename moreinfo="none">conf.xml</filename>. In fact, the driver looks for
                    <filename moreinfo="none">conf.xml</filename> in the directory specified by the
                    <option>exist.home</option> system property. You should therefore ensure a copy
                of <filename moreinfo="none">conf.xml</filename> is placed in the correct directory.
                For example, to launch your own application, while setting
                    <option>exist.home</option>, you may enter:</para><synopsis format="linespecific">java -Dexist.initdb=true 
				-Dexist.home=/home/exist/eXist MyApp</synopsis><important><para>Please note that the paths to the data and log directories in <filename moreinfo="none">conf.xml</filename> need to point to
                        <emphasis>writable</emphasis> directories.</para></important><para>Instead of using the <option>-Dexist.initdb</option> 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 <property>create-database</property> property on the created
                    <classname>Database</classname> object to <option>true</option> - for
                example:</para><example><title>Initializing a Local Database Instance</title><programlisting format="linespecific" language="java">
Class cl = Class.forName("org.exist.xmldb.DatabaseImpl");
Database database = (Database) cl.newInstance();
database.setProperty("create-database", "true");
DatabaseManager.registerDatabase(database);</programlisting></example><para>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.</para><para>There is a special XML:DB service, <classname>DatabaseInstanceManager</classname>,
                which contains a single method: <methodname>shutdown</methodname>. To properly shut
                down the database instance, retrieve the service from the <filename>/db-collection</filename> and call <methodname>shutdown()</methodname>. For
                example:</para><example><title>Shutting down the Database</title><programlisting format="linespecific" language="java">
DatabaseInstanceManager 
manager = (DatabaseInstanceManager) 
    collection.getService("DatabaseInstanceManager", "1.0"); 
manager.shutdown();</programlisting></example><para>To summarize, a minimal working class with a single static main to start/stop the
                db may look like this:</para><example><title>Minimal Example</title><programlisting language="java">
import org.xmldb.api.DatabaseManager;
import org.xmldb.api.base.Collection;
import org.xmldb.api.base.Database;
import org.exist.xmldb.DatabaseInstanceManager;

public class TestDB {		
	public static void main(String args[]) throws Exception {
		// initialize driver
		Class cl = Class.forName("org.exist.xmldb.DatabaseImpl");
		Database database = (Database)cl.newInstance();
		database.setProperty("create-database", "true");
		DatabaseManager.registerDatabase(database);
		
		// try to read collection
		Collection col = 
			DatabaseManager.getCollection("xmldb:exist:///db", "admin", "");
		String resources[] = col.listResources();
		System.out.println("Resources:");
		for (int i = 0; i &lt; resources.length; i++) {
			System.out.println(resources[i]);
		}
		
		// shut down the database
		DatabaseInstanceManager manager = (DatabaseInstanceManager) 
			col.getService("DatabaseInstanceManager", "1.0"); 
		manager.shutdown();
	}
}</programlisting></example><para>Put this code into a Java file <filename>TestDB.java</filename> and store it into
                the target directory, which we already prepared above. Compile and run it
                with:</para><synopsis>javac TestDB.java
			java -Dexist.initdb=true -Dexist.home=. TestDB</synopsis></section></chapter></book>