<?xml version="1.0" encoding="UTF-8"?>
<book xmlns:ci="http://apache.org/cocoon/include/1.0">
  <bookinfo>
    <graphic fileref="logo.jpg" />

    <productname>Open Source Native XML Database</productname>

    <title>Database Deployment</title>

    <author>
      <firstname>Wolfgang M.</firstname>

      <surname>Meier</surname>

      <affiliation>
        <address format="linespecific">
					<email>wolfgang at exist-db.org</email>
				</address>
      </affiliation>
    </author>
  </bookinfo>

  <ci:include src="sidebar.xml" />

  <chapter>
    <title>Database Deployment</title>

    <section>
      <title>Overview</title>

      <para>There are <emphasis>three</emphasis> ways to deploy the eXist
      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,
          like e.g. Cocoon. 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 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 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 - a Cocoon-driven application would be one example of this.
      External client applications may still use the supplied network
      interfaces.</para>

      <para>As detailed instructions on how to set up eXist 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 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>-o</option> option on the command line. For example, if
      you start the Admin client using the command:</para>

      <synopsis format="linespecific">bin/client.sh -o uri=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 in a Servlet Container</title>

      <para>The standard distribution does by default launch eXist 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>In this setup, eXist runs together with Cocoon in the same web
      application. 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>

      <important>
        <para>It is currently not possible to run more than one instance of
        the eXist database in one servlet container.</para>
      </important>
    </section>

    <section>
      <title>Running eXist 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
      Cocoon 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.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 server.xml</title>

        <para>The <filename>server.xml</filename> configuration file is only
        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
        element in this file. Currently, the servlet API options are
        "<option>webdav</option>, "<option>xmlrpc</option>", and
        "<option>rest</option>". Any of these servlets can be disabled by
        setting the <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 server.xml document has the following basic
        structure:</para>

        <example>
          <title>Sample Configuration File: server.xml</title>

          <programlisting>&lt;!--
    Configures the stand-alone server: the stand-alone server is a minimal
    webserver with just three services enabled by default:
    webdav, xmlrpc, rest.
--&gt;
&lt;server port="8088"&gt;
    &lt;!--
        Enable the WebDAV, XML-RPC and REST services.
        The context attribute specifies to which context path
        the service will be mapped. Specify an url-pattern as
        for a servlet-mapping. Example: /xmlrpc/* forwards all
        paths beginning with /xmlrpc to the xmlrpc service.
    --&gt;
    &lt;webdav enabled="yes" context="/webdav/*"/&gt;
    &lt;xmlrpc enabled="yes" context="/xmlrpc/*"/&gt;
    &lt;rest enabled="yes" context="/*"&gt;
        &lt;!--
            Special params: set form-encoding and container-encoding. If they
            are set to different encodings, eXist may need to recode form parameters.
        --&gt;
        &lt;param name="form-encoding" value="UTF-8"/&gt;
        &lt;param name="container-encoding" value="UTF-8"/&gt;
    &lt;/rest&gt;
    &lt;servlet enabled="yes"
             context="/atom/*"
             class="org.exist.atom.http.AtomServlet"/&gt;
    &lt;!--
        Define URL forwardings
    --&gt;
    &lt;forwarding&gt;
        &lt;!--
            Other forwardings: all requests to the specified path
            will be forwarded to the destination.
        --&gt;
        &lt;forward path="/admin" destination="/db/admin/admin.xql"/&gt;
    &lt;/forwarding&gt;
&lt;/server&gt;
					</programlisting>
        </example>

        <section>
          <title>Controlling the Binding Address (&lt;indexer&gt;)</title>

          <para>You can control the binding address by using the following
          attributes for the <sgmltag>server</sgmltag> element:</para>

          <variablelist>
            <varlistentry>
              <term>port</term>

              <listitem>
                <para>The port on which the server will listen. The Jetty web
                server will bind to the any address on 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>The REST servlet provides HTTP/REST-style interactions with
          the database. It is configured by the <sgmltag>rest</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 REST services are provided. If
          the "<option>context</option>" attribute is not specified, it
          defaults to <filename>/</filename>.</para>

          <para>The <sgmltag>rest</sgmltag> has a number of other parameters
          that can be set by children <option>param</option> elements:</para>

          <example>
            <title>&lt;rest&gt;-&lt;param&gt; Structure</title>

            <programlisting> &lt;rest enabled="yes" context="/*"&gt;
      &lt;param name="name" value="string-value"  /&gt;
 &lt;/rest&gt;
						</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 the <option>guest</option> user should be used for
                non-authenticated interactions.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>default-user-username</term>

              <listitem>
                <para>The username of the default user.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>default-user-password</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> &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;
</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>&lt;root destination="/db/admin/admin.xql" /&gt;</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>&lt;forward path="/admin" destination="/db/admin/admin.xql"/&gt;
&lt;forward path="/docs" destination="/db/products/docs.xml"/&gt;</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> 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>
        </step>

        <step>
          <para>Create a <filename>lib</filename> directory below the target
          directory and copy the following <filename>.jar</filename> files
          into it:</para>

          <itemizedlist>
            <listitem>
              <filename>exist.jar</filename>
            </listitem>

            <listitem>
              <filename>exist-modules.jar</filename>
            </listitem>

            <listitem>
              <filename>antlr-X.X.X.jar</filename>
            </listitem>

            <listitem>
              <filename>commons-pool-X.X.jar</filename>
            </listitem>

            <listitem>
              <filename>jgroups-all.jar</filename>
            </listitem>

            <listitem>
              <filename>log4j-X.X.X.jar</filename>
            </listitem>

            <listitem>
              <filename>resolver.jar</filename>
            </listitem>

            <listitem>
              <filename>sunxacml.jar</filename>
            </listitem>

            <listitem>
              <filename>xmldb.jar</filename>
            </listitem>

            <listitem>
              <filename>xmlrpc-1.2-patched.jar</filename>
            </listitem>
          </itemizedlist>
        </step>

        <step>Make sure your CLASSPATH includes these jar files.</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-1.0 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">
  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">
  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>
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();
		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>