<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: configuration.xml 18525 2013-06-09 20:20:20Z dizzzz $ --><book><bookinfo><productname>Open Source Native XML Database</productname><title>Server Configuration</title><date>April 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><surname>Milowski</surname><firstname>Alex</firstname><email>alexmilowski@users.sourceforge.net</email></author><author><firstname>Leif-Jöran</firstname><surname>Olsson</surname><affiliation><address format="linespecific"><email>ljo at exist-db.org</email></address></affiliation></author><author><personname><firstname>Loren</firstname><surname>Cahlander</surname></personname><email>loren at syntactica.com</email></author></bookinfo><chapter><title>Application Server Configuration</title><section><title>Overview</title><para>This section deals with the configuration of the eXist-db Application Server. The
                main configuration file for <application>eXist-db</application> is called
                    <filename>conf.xml</filename>, which is loaded from different directories
                depending on the server set-up (see <ulink url="deployment.xml">Server
                    Deployment</ulink> for more information).</para><para>Specifically, if you installed the standalone eXist-db distribution with the
                installer, the <filename>conf.xml</filename> file located in the root directory of
                the distribution (as specified by the system property <option>exist.home</option>)
                will be loaded by default. On the other hand, if eXist-db is installed as a web
                application (packaged in a <filename>.war</filename> file) in a servlet engine like
                tomcat, <filename moreinfo="none"> conf.xml</filename> is read from the <filename moreinfo="none">WEB-INF</filename> directory of the web application.</para><para>Why is the configuration file placed in two separate locations? The reason is that
                eXist-db normally has no access to files outside the context in which it is running
                when it is deployed as part of a web application. Therefore, when eXist is deployed
                in this way, the configuration is read from the <filename>WEB-INF</filename>
                directory.</para></section><section><title>Services</title><para>The following table lists which services and modules ship with eXist; a
                description of each; the resources in the eXist installation where they are
                configured; and whether they are active by default in an out-of-the box
                configuration.</para><note>This is a work in progress. It is being refined, but I want to get it into the
                repository to maintain history.</note><informaltable><thead><tr bgcolor="#0990EE" valign="top"><th width="20%">Service</th><th width="30%">Description</th><th>Resources</th><th>Initial Compilation</th><th width="7%">Initial State</th></tr></thead><tbody><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="debugger.xml">debugger</ulink></td><td><para> This is an XQuery debugger.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-fluent.xml">fluent</ulink></td><td><para>This is an API for embedded access to eXist-db which is tightly integrated with java.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Desktop Application Support</td><td><para> </para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="security.xml#ldap-realm">LDAP</ulink></td><td><para> LDAP is an authentication mechanism by binding.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="security.xml#openid-realm">OpenID</ulink></td><td><para> OpenID is an authentication mechanism where the identity of the
                                user is maintained by trusted external providers.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="security.xml#oauth-realm">OAuth</ulink></td><td><para> OAuth is an authentication mechanism where the identity of the
                                user is maintained by trusted external providers.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="config-versioning.xml">Versioning</ulink></td><td><para> Versioning extension</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-xqdoc.xml">XQDoc</ulink></td><td><para> xqDoc provides a simple vendor neutral solution for documenting
                                XQuery library and main modules that is similar to JavaDoc.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="config-xslt.xml">XSLT</ulink></td><td><para>XSLT extension</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-cache.xml">Cache</ulink></td><td><para> Cache module</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="config-compression.xml">Compression</ulink></td><td><para>Provides functions to manipulate archives, tar/zip/gzip</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-context.xml">Context</ulink></td><td><para> Context module</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="config-counter.xml">Counter</ulink></td><td><para> Persistent counter module</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-datetime.xml">Datetime</ulink></td><td><para> Date/DateTime/Time utility functions module</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td><ulink url="config-example.xml">Example</ulink></td><td><para> This is an example Java based function module.  It is a template
                                for creating other Java based function modules.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td><ulink url="config-file.xml">File</ulink></td><td><para> Provides functions to manipulate files in the local file
                                system.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Http Client</td><td><para> This provides functions to call other web servers as if eXist
                                were a web browser.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>Image</td><td><para> Generate thumbnails of images.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>JFreechart</td><td><para> Provides functions to generate graphs using JFreechart</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>JNDI</td><td><para> Provides functions to query a JNDI Directory</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td/><td><para> </para></td><td/><td/><td align="center"/></tr><tr bgcolor="#FFFFFF" valign="top"><td>Mail</td><td><para> Send emails from XQuery</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Math</td><td><para> Math function module</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>Scheduler</td><td><para> The Quartz scheduler</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>SimpleQL</td><td><para> Implements a simple query language which is translated into
                                XQuery</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>SQL</td><td><para> A set of functions to query a SQL database.</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Subversion</td><td><para> Provides functions to query a subversion repository</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>XMLDiff</td><td><para> Utility module to compare XML fragments</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>XMPP</td><td><para> XMPP client; based on smack</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>XSL FO</td><td><para> XSL FO transformations (Uses Apache FOP)</para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>XML RPC</td><td><para> RpcServlet provides XML-RPC access to eXist</para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>DatabaseAdminServlet</td><td><para>This servlet can be used to ensure that eXist-db is running in the background. Just set the
                                start-parameter to true and load-on-startup to 1 </para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td/></tr><tr bgcolor="#F6F6F6" valign="top"><td>webDAV</td><td><para> Servlet that enables webDAV</para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>XQueryServlet</td><td><para>This generates HTML from an XQuery file</para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>XQueryURLRewrite</td><td><para> </para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem><listitem><para>webapp/WEB-INF/controller-config.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>Axis/SOAP</td><td><para>Axis provides eXist's web-services via SOAP</para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Atom</td><td><para>Atom Publishing Protocol</para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>Webstart (jnlp)</td><td><para> </para></td><td><itemizedlist><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>Security</td><td><para>This defines the security manager that is to be used by eXist-db. The
                                current options are native (where the usernames and hashed passwords
                                are store in the database) or LDAP.</para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td/></tr><tr bgcolor="#F6F6F6" valign="top"><td>Indexing</td><td><para> </para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td/></tr><tr bgcolor="#FFFFFF" valign="top"><td>Scheduler</td><td><para>This module executes scheduled system tasks.</para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>Serializer</td><td><para> </para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>XSLT Transformer</td><td><para>Default settings for the XSLT Transformer. Allow's for a choice of
                                implementation.</para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr><tr bgcolor="#F6F6F6" valign="top"><td>XML Validation</td><td><para> </para></td><td><itemizedlist><listitem><para>conf.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#FF0000">Off</td></tr><tr bgcolor="#FFFFFF" valign="top"><td>XProc</td><td><para> </para></td><td><itemizedlist><listitem><para>extensions/build.properties</para></listitem><listitem><para>webapp/WEB-INF/web.xml</para></listitem></itemizedlist></td><td/><td align="center" bgcolor="#00FF00">On</td></tr></tbody></informaltable></section><section id="conf.xml"><title>eXist-db Configuration: Editing conf.xml</title><para>The configuration file <filename moreinfo="none">conf.xml</filename> can be
                divided into four sections with the following elements:</para><variablelist><varlistentry><term>&lt;db-connection&gt;</term><listitem><para>Configures the storage back-end.</para></listitem></varlistentry><varlistentry><term>&lt;serializer&gt;</term><listitem><para>Default settings for the serializer (external data
                            representation).</para></listitem></varlistentry><varlistentry><term>&lt;indexer&gt;</term><listitem><para>Controls the indexing process.</para></listitem></varlistentry><varlistentry><term>&lt;xupdate&gt;</term><listitem><para>Configuration options related to XUpdate processing.</para></listitem></varlistentry></variablelist><para>The following sections describe the attributes and child elements of the above
                elements.</para><section><title>&lt;db-connection&gt;</title><para>This element contains basic default storage settings for eXist-db, including
                    memory and system limits. Only one <sgmltag>db-connection</sgmltag> should be
                    specified. An example configuration for the native back-end is shown
                    below:</para><example><title>Basic &lt;db-connection&gt; Entry</title><programlisting format="linespecific"><markup>&lt;db-connection cacheSize="48M" collectionCache="24M" database="native"
        files="webapp/WEB-INF/data" pageSize="4096" nodesBuffer="-1"&gt;
      &lt;pool min="1" max="15" sync-period="240000" wait-before-shutdown="60000"/&gt;
      &lt;!--default-permissions collection="0775" resource="0775" /--&gt;
      &lt;recovery enabled="yes" sync-on-commit="no" group-commit="no" size="100M" 
            journal-dir="webapp/WEB-INF/data"/&gt;
      &lt;!-- security class="org.exist.security.LDAPSecurityManager" /--&gt;
      &lt;watchdog query-timeout="-1" output-size-limit="10000"/&gt;
      &lt;default-permissions collection="0775" resource="0775"/&gt;
&lt;/db-connection&gt;</markup></programlisting></example><section><title>&lt;db-connection&gt; Attributes</title><variablelist><varlistentry><term>database</term><listitem><para>This attribute selects a database system type. Since
                                    relational database back-ends are no longer supported by the
                                    current release of eXist, only "<option>native</option>" is available.</para></listitem></varlistentry><varlistentry><term>files</term><listitem><para>This attribute specifies the directory where the native
                                    back-end will keep its database files, and so it is necessary
                                    that this directory exists. If a relative path is specified, it
                                    will be based on the root directory as defined in the
                                        <option>exist.home</option> system property. If this data
                                    directory does not have write permissions (see <ulink url="security.xml"> User Authentication and Access
                                        Control</ulink>), eXist will internally switch to
                                        <emphasis>read-only mode</emphasis> such that any attempt to
                                    change the database will throw an exception.</para></listitem></varlistentry><varlistentry><term>cacheSize</term><listitem><para>This attribute sets the maximum amount of main memory used by
                                    all page buffers (i.e. assuming all page buffers are at full
                                    capacity). The database uses this parameter to calculate the
                                    maximum size of each internal cache. You can increase this value
                                    if your system allows for greater memory use.</para><para>While indexing documents, eXist will reserve the amount of
                                    memory specified in cacheSize - even if not all caches are
                                    filled - and will not use it for temporary data.</para><para>The cacheSize should not be more than half of the size of the
                                    JVM heap size (set by the JVM -Xmx parameter). If the JVM heap
                                    is less than 512 megabyte, the cacheSize should even be smaller,
                                    e.g. 1/3.</para></listitem></varlistentry><varlistentry><term>collectionCache</term><listitem><para>Determines the size of the collection cache, which is a
                                    separate caching space. Usually this setting does not need to be
                                    changed unless you really have more than a few thousand
                                    collections in the db. Increase it carefully, maybe up to
                                    128M.</para></listitem></varlistentry><varlistentry><term>pageSize</term><listitem><para>This specifies the number of bytes used for internal data and
                                    B-tree pages. This should be equal to or a multiple of the page
                                    size used by the filesystem (usually a multiple of 4096).</para></listitem></varlistentry><varlistentry><term>nodesBuffer</term><listitem><para>Size of the temporary buffer used by eXist for caching index
                                    data while indexing a document. If set to -1, eXist will use the
                                    entire free memory to buffer index entries and will flush the
                                    cache once the memory is full.</para><para>If set to a value &gt; 0, the buffer will be fixed to the given
                                    size. The specified number corresponds to the number of nodes
                                    the buffer can hold, in thousands. Usually, a good default could
                                    be nodesBuffer="1000".</para><para>The default setting, nodesBuffer="-1", can be problematic if
                                    you frequently need to store large documents in a multi-user
                                    environment. In this case, the index operation may consume most
                                    of the memory resources, which means that concurrent threads
                                    will be slowed down or may even come to a halt.</para></listitem></varlistentry></variablelist></section><section><title><sgmltag>pool</sgmltag></title><para>These settings control the internal database connection pool.</para><variablelist><title>&lt;pool&gt; Attributes</title><varlistentry><term>min | max</term><listitem><para>These options specify the minimum and maximum size of the
                                    connection pool. This pool restricts the number of parallel
                                    (basic) operations that can be executed by the database.
                                    Settings should be somewhere between 1 and 20. (Please note that
                                    this has nothing to do with the HTTP and XMLRPC server settings
                                    - these servers have their own connection pools.)</para></listitem></varlistentry><varlistentry><term>sync-period</term><listitem><para>This option defines how often the database will flush its
                                    internal buffers to disk (in milliseconds). The sync-thread will
                                    interrupt normal database operation after the specified time and
                                    write all dirty pages to disk. It also writes a checkpoint to
                                    the transaction log. In case of a database crash, only
                                    transactions which started after the last checkpoint have to be
                                    redone or rolled back. The sync-period should thus not be set
                                    too long.</para></listitem></varlistentry><varlistentry><term>wait-before-shutdown</term><listitem><para>This option specifies the maximum amount of time (in
                                    milliseconds) that the database will allow for any running
                                    processes to complete upon database shutdown. After that, eXist
                                    will try to kill the remaining processes.</para><para>If wait-before-shutdown is set to a positive number, eXist
                                    will stop the db after the specified timeout, even if there were
                                    still running database operations. In this case, no checkpoint
                                    will be written to the transaction log. If there were any open
                                    transactions, eXist will trigger a recovery run after
                                    restart.</para><para>If wait-before-shutdown is set to -1, eXist will not shut down
                                    before all active database operations returned. This is a safe
                                    setting, but it may require a manual intervention to stop the
                                    jvm.</para></listitem></varlistentry></variablelist></section><section><title>&lt;recovery&gt;</title><para>This element configures the journaling and recovery of the database. With
                        recovery enabled, the database is able to recover from an unclean database
                        shutdown due to, for example, power failures, OS reboots, and hanging
                        processes. For this to work correctly, all database operations must be
                        logged to a journal file. The location, size and other parameters for this
                        file can be set using the <sgmltag>recovery</sgmltag> element.</para><variablelist><title>&lt;recovery&gt; Attributes</title><varlistentry><term>enabled</term><listitem><para>If this attribute is set to <option>yes</option>, automatic
                                    recovery is enabled.</para></listitem></varlistentry><varlistentry><term>size</term><listitem><para>This attributes sets the maximum allowed size of the journal
                                    file. Once the journal reaches this limit, a checkpoint will be
                                    triggered and the journal will be cleaned. However, the database
                                    waits for running transactions to return before processing this
                                    checkpoint. In the event one of these transactions writes a lot
                                    of data to the journal file, the file will grow until the
                                    transaction has completed. Hence, the size limit is not enforced
                                    in all cases.</para></listitem></varlistentry><varlistentry><term>journal-dir</term><listitem><para>This attribute sets the directory where journal files are to
                                    be written. If no directory is specified, the default path is to
                                    the <filename>data</filename> directory.</para></listitem></varlistentry><varlistentry><term>sync-on-commit</term><listitem><para>This attribute determines whether or not to protect the
                                    journal during operating system failures. That is, it determines
                                    whether the database forces a file-sync on the journal after
                                    every commit. If this attribute is set to
                                    "<option>yes</option>", the journal is protected against
                                    operating system failures. However, this will slow performance -
                                    especially on Windows systems. If set to "<option>no</option>",
                                    eXist will rely on the operating system to flush out the journal
                                    contents to disk. In the worst case scenario, in which there is
                                    a complete system failure, some committed transactions might not
                                    have yet been written to the journal, and so will be rolled
                                    back.</para></listitem></varlistentry><varlistentry><term>group-commit</term><listitem><para>If set to "yes", eXist will not sync the journal file
                                    immediately after every transaction commit. Instead, it will
                                    wait until the current file buffer (32kb) is really full. This
                                    can speed up eXist on some systems where a file sync is an
                                    expensive operation (mainly windows XP; not necessary on
                                    Linux).</para><para>However, <option>group-comit="yes"</option> will increase the
                                    chance that an already committed operation is rolled back after
                                    a database crash.</para></listitem></varlistentry><varlistentry><term>force-restart</term><listitem><para>Try to restart the db even if crash recovery failed. This is
                                    dangerous because there might be corruptions inside the data
                                    files. The transaction log will be cleared, all locks removed
                                    and the db reindexed.</para><para>Set this option to "yes" if you need to make sure that the db
                                    is online, even after a fatal crash. Errors encountered during
                                    recovery are written to the log files. Scan the log files to see
                                    if any problems occurred.</para></listitem></varlistentry><varlistentry><term>consistency-check</term><listitem><para>If set to "yes", a consistency check will be run on the
                                    database if an error was detected during crash recovery. This
                                    option requires force-restart to be set to "yes", otherwise it
                                    has no effect.</para><para>The consistency check outputs a report to the directory
                                    {files}/sanity and if inconsistencies are found in the db, it
                                    writes an emergency backup to the same directory.</para></listitem></varlistentry></variablelist></section><section><title>&lt;watchdog&gt;</title><para>This is the global configuration for the <emphasis>query
                            watchdog</emphasis>. The watchdog monitors all query processes, and can
                        terminate any long-running queries if they exceed one of the predefined
                        limits. These limits are as follows:</para><variablelist><title>&lt;watchdog&gt; Attributes</title><varlistentry><term>query-timeout</term><listitem><para>This attribute sets the maximum amount of time (expressed in
                                    milliseconds) that the query can take before it is killed. The
                                    setting can be overwritten in an XQuery by specifiying the
                                    option <option>exist:timeout</option>:</para><synopsis language="xquery">declare option exist:timeout "time-in-ms";</synopsis><para>Please check the documentation on <ulink url="xquery.xml#xqopts">XQuery options</ulink>.</para></listitem></varlistentry><varlistentry><term>output-size-limit</term><listitem><para>This attribute limits the size of XML fragments constructed
                                    using XQuery, and thus sets the maximum amount of main memory a
                                    query is allowed to use. This limit is expressed as the maximum
                                    number of nodes allowed for an in-memory DOM tree. The purpose
                                    of this option is to avoid memory shortages on the server in
                                    cases where users are allowed to run queries that produce very
                                    large output fragments. The setting can be overwritten in an
                                    XQuery by specifying the option
                                        <option>exist:output-size-limit</option>:</para><synopsis language="xquery">declare option exist:output-size-limit "size-hint";</synopsis></listitem></varlistentry></variablelist></section><section><title>&lt;default-permissions&gt;</title><para>Specifies the default permissions for all resources and collections in
                        eXist (see <ulink url="security.xml"> User Authentication and Access
                            Control</ulink>). When this is not configured, the default
                            "<option>mod</option>" (similar to the Unix "chmod" command) is set to
                            <option>0775</option> in the <option>resources</option> and
                            <option>collections</option> attributes. A different default value may
                        be set for a database instance, and local overrides are also
                        possible.</para></section><section><title>&lt;security&gt;</title><para>The <sgmltag>security</sgmltag> element in the
                            <sgmltag>db-connection</sgmltag> node is used to select the security
                        manager Class and control the database of users and groups.</para><variablelist><title>&lt;security&gt; Attributes</title><varlistentry><term>class</term><listitem><para>This attribute is <emphasis>required</emphasis>, and specifies
                                    a Java class name used to implement the
                                        <code>org.exist.security.SecurityManager</code> interface,
                                    as in the following example:</para><example><title>&lt;security&gt; <emphasis>class</emphasis> Attribute
                                        (LDAP)</title><programlisting><markup>&lt;security class="org.exist.security.LDAPSecurityManager" /&gt;</markup></programlisting></example><para>eXist is distributed with the following built-in security
                                    manager implementations:</para><variablelist><varlistentry><term>org.exist.security.XMLSecurityManager</term><listitem><para>Stores the user information in the database. This
                                                is the default manager if the
                                                  <sgmltag>security</sgmltag> element is not
                                                included in <sgmltag>db-connection</sgmltag>.</para></listitem></varlistentry><varlistentry><term>org.exist.security.LDAPSecurityManager</term><listitem><para>Retrieves the user and groups from the LDAP
                                                database. This requires addition configuration
                                                parameters which are described in the <ulink url="ldap-security.xml">LDAP Security
                                                  Manager</ulink> documentation.</para></listitem></varlistentry></variablelist></listitem></varlistentry><varlistentry><term>password-encoding</term><listitem><para>Password encoding can be set to one of the following
                                    types:</para><orderedlist><listitem><para><option>plain</option> - Applies plain
                                            encryption.</para></listitem><listitem><para><option>md5</option> (default) - Applies the MD5
                                            algorithm to encrypt passwords.</para></listitem><listitem><para><option>simple-md5</option> - Applies a simplified MD5
                                            algorithm to encrypt passwords.</para></listitem></orderedlist></listitem></varlistentry><varlistentry><term>password-realm</term><listitem><para>The realm to use for basic auth or http-digest password
                                    challenges.</para></listitem></varlistentry></variablelist></section></section><section><title>&lt;indexer&gt;</title><para>This element sets parameters on how XML files are to be indexed by eXist. An
                    example configuration is shown below:</para><example><title>Specifying Indexer-Options in conf.xml</title><programlisting format="linespecific"><markup>&lt;indexer caseSensitive="no"
	suppress-whitespace="both" index-depth="1"
	tokenizer="org.exist.storage.analysis.SimpleTokenizer"
	validation="no"&gt;
	
	&lt;modules&gt;
        &lt;module id="ngram-index" class="org.exist.indexing.ngram.NGramIndex"
            file="ngram.dbx" n="3"/&gt;
        &lt;!--
        &lt;module id="spatial-index" class="org.exist.indexing.spatial.GMLHSQLIndex"
            connectionTimeout="10000" flushAfter="300" /&gt;            
        --&gt;
		&lt;!-- The full text index is always required and should
			 not be disabled. We still have some dependencies on
             this index in the database core. These will be removed
             once the redesign has been completed. --&gt;
		&lt;module id="ft-legacy-index" class="org.exist.fulltext.FTIndex"/&gt;
    &lt;/modules&gt;
        
    &lt;stopwords file="stopword"/&gt;
    
	&lt;!-- Default index configuration --&gt;
    &lt;index&gt;
        &lt;fulltext default="all" attributes="false"&gt;
            &lt;exclude path="/auth"/&gt;
        &lt;/fulltext&gt;
    &lt;/index&gt;

    &lt;entity-resolver&gt;
	    &lt;catalog file="samples/xcatalog.xml"/&gt;
    &lt;/entity-resolver&gt;
&lt;/indexer&gt;</markup></programlisting></example><section><title>&lt;indexer&gt; Attributes</title><variablelist><varlistentry><term>caseSensitive</term><listitem><para>Specifies whether string comparisons are to be case-sensitive.
                                    This option applies to XPath equality tests (i.e.
                                        "<option>=</option>" operator), as well as functions such as
                                        <function>contains()</function>,
                                        <function>starts-with()</function> and
                                        <function>ends-with()</function>. This setting does not
                                    apply to operators or functions of the fulltext index (e.g.
                                        "<option>&amp;=</option>", "<option>|=</option>",
                                        "<function>near()</function>") or the n-gram index, which
                                    are <emphasis>never</emphasis> case-sensitive</para><para>Setting <option>caseSensitive="yes"</option> violates the
                                    XQuery specs! The option should be regarded as a dirty
                                    workaround, which will be removed in the future. Please use the
                                    n-gram or full-text indexes for case-insensitive queries or - if
                                    that is impossible - specify a <ulink url="xquery.xml#collations">collation</ulink>.</para></listitem></varlistentry><varlistentry><term>suppress-whitespace</term><listitem><para>Specifies how the &lt;indexer&gt; is to treat whitespace at
                                    the start or end of a character sequence. This option
                                        <emphasis>ONLY</emphasis> applies to newly stored files, and
                                    therefore changing it has no effect on previously stored
                                    documents. Possible values for this attribute are:</para><orderedlist><listitem><para><option>leading</option> - Suppresses leading
                                            whitespace.</para></listitem><listitem><para><option>trailing</option> - Suppresses trailing
                                            whitespace.</para></listitem><listitem><para><option>both</option> - Suppresses leading and
                                            trailing whitespace.</para></listitem><listitem><para><option>none</option> - Preserves all
                                            whitespace.</para></listitem></orderedlist><para>Note that suppressing whitespace at the start or end of
                                    character sequences does effectively change the document!</para></listitem></varlistentry><varlistentry><term>preserve-whitespace-mixed-content</term><listitem><para>controls how ignorable whitespace is handled. If set to
                                        <literal>no</literal>, ignorable whitespace, e.g. between
                                    the end tag of an element and the start tag of another, will not
                                    be stored into the persistent DOM. This leads to a smaller DOM
                                    and usually increases the readability of the XML. Ignorable
                                    whitespace is not considered as a part of the logical document
                                    model, so removing it doesn't change the document.</para></listitem></varlistentry><varlistentry><term>tokenizer</term><listitem><para>This attribute invokes the Java class used to tokenize a
                                    string into a sequence of single words or tokens, which are
                                    stored to the fulltext index. Currently only the
                                        <classname>SimpleTokenizer</classname> is available.</para></listitem></varlistentry><varlistentry><term>index-depth</term><listitem><para>This attribute specifies the depth of the DOM index, or the
                                    tree level up to which elements will be added to the index. For
                                    example, a value of "<option>2</option>" results in the document
                                    root node and all its child elements being indexed; a value of
                                        "<option>1</option>" only indexes the root node.</para><para>The DOM index maps unique node identifiers to the nodes'
                                    storage locations in the DOM file. Generating this index is
                                    time- and memory-consuming. It is furthermore primarily needed
                                    to access nodes by their unique node identifier - for example,
                                    when serializing XML data for query results or XUpdate - which
                                    are operations not normally considered time-critical. Moreover,
                                    most XPath expressions can do without this index since they use
                                    short-cuts to access the node directly.</para><para>Beginning with version 0.9, only top-level elements are added
                                    to the DOM index, whereas attributes and text nodes are always
                                    excluded. This results in much smaller index sizes and,
                                    consequently, a smaller <filename moreinfo="none">dom.dbx</filename> file size. Usually, setting the
                                        <option>index-depth</option> to a value of
                                        "<option>2</option>" offers a reasonable compromise of index
                                    size and performance. However, if your documents are
                                        <emphasis>deeply-structured</emphasis>, you might consider
                                    increasing this setting to a level of 3, 4 or 5. For example, if
                                    the longest path from the document root to an element node has
                                    greater than ten node levels, an <option>index-depth</option>
                                    setting of <option>4</option> or <option>5</option> would
                                    probably help to increase overall query performance for some
                                    types of queries.</para></listitem></varlistentry><varlistentry><term>validation</term><listitem><para>This attribute defines the default setting for the validation
                                    of documents by the XML parser. If it is set to
                                        "<option>no</option>", documents will never be validated
                                    against an existing DTD or schema. A value of
                                        "<option>auto</option>" will leave document validation to
                                    the SAX parser (i.e. the <emphasis>Xerces</emphasis>
                                    parser).</para></listitem></varlistentry></variablelist></section><section><title><sgmltag>modules</sgmltag></title><para>This section configures optional indexing modules. Beginning with version
                        1.2, eXist features a modularized indexing architecture, which allows new
                        indexes to be plugged into the indexing pipeline. The
                            <sgmltag>modules</sgmltag> section lists and configures the indexes that
                        will be available to the database: </para><example><title>Configuring Index Modules</title><programlisting><markup>&lt;modules&gt;
    &lt;module id="ngram-index" class="org.exist.indexing.ngram.NGramIndex"
        file="ngram.dbx" n="3"/&gt;
    &lt;!--
    &lt;module id="spatial-index" class="org.exist.indexing.spatial.GMLHSQLIndex"
        connectionTimeout="10000" flushAfter="300" /&gt;            
    --&gt;
	&lt;!-- The full text index is always required and should
		 not be disabled. We still have some dependencies on
         this index in the database core. These will be removed
         once the redesign has been completed. --&gt;
	&lt;module id="ft-legacy-index" class="org.exist.fulltext.FTIndex"/&gt;
&lt;/modules&gt;</markup></programlisting></example><para>The only common attributes for each <sgmltag>module</sgmltag> element are
                            <option>class</option> and <option>id</option>. The other attributes as
                        well as any nested elements are specific to the index implementation.
                        Detailed information is available in the document on <ulink url="indexing.xml#moduleconf">Configuring Database
                        Indexes</ulink>.</para></section><section><title><sgmltag>stopwords</sgmltag></title><para>The <option>file</option> for this element points to a file containing a
                        list of <emphasis>stopwords</emphasis>. Note that stopwords are
                            <emphasis>NOT</emphasis> added to the fullext index.</para></section><section><title><sgmltag>index</sgmltag></title><para>This configuration element specifies the default index settings. These
                        settings are applied if neither the collection nor any of its ancestors
                        provide a collection configuration. Configuring indexes via the default
                        settings is not recommended. If you need a global collection configuration,
                        store one for the root collection <filename>/db</filename>. For more
                        information, read the <ulink url="indexing.xml"> Configuring Indexes</ulink>
                        documentation.</para></section></section><section><title><sgmltag>scheduler</sgmltag></title><para>This section is used to configure asynchronous jobs with eXist's internal
                    scheduler. Three types of jobs are supported:</para><variablelist><varlistentry><term>startup jobs</term><listitem><para>Startup jobs are executed once during database startup, but before
                                the database becomes available. These jobs are synchronous. The
                                database is blocked to outside requests and no other operations will
                                run at the same time.</para></listitem></varlistentry><varlistentry><term>system jobs</term><listitem><para>System jobs require the database to be in a consistent state. The
                                scheduler will run them in an exclusive environment. Once the job is
                                triggered, the database will block all new requests and wait for
                                running operations to complete. It then executes the job. All other
                                database operations will be stopped until the job returns or throws
                                an exception. Any exception will be caught and a warning written to
                                the log.</para></listitem></varlistentry><varlistentry><term>user jobs</term><listitem><para>User jobs may be scheduled at any time and may be mutually
                                exclusive or non-exclusive</para></listitem></varlistentry></variablelist><para>Below is an example which configures a <ulink url="backup.xml#backuptask">BackupSystemTask</ulink>: </para><example><title>Configuring a BackupSystemTask</title><programlisting><markup>&lt;scheduler&gt;
    &lt;job type="system" class="org.exist.storage.BackupSystemTask" cron-trigger="0 0 */6 * * ?"&gt;
        &lt;parameter name="dir" value="backup"/&gt;
        &lt;parameter name="suffix" value=".zip"/&gt;
        &lt;parameter name="prefix" value="backup-"/&gt;
        &lt;parameter name="collection" value="/db"/&gt;
        &lt;parameter name="user" value="admin"/&gt;
        &lt;parameter name="password" value=""/&gt;
        &lt;parameter name="zip-files-max" value="28"/&gt;
    &lt;/job&gt;
&lt;/scheduler&gt;</markup></programlisting></example><para>Each job is configured in a <sgmltag>job</sgmltag> element which accepts a
                    number of standard attributes:</para><section><title><sgmltag>job</sgmltag> attributes</title><variablelist><varlistentry><term>type</term><listitem><para>The type of the job to schedule. Must be either "startup",
                                    "system" or "user".</para></listitem></varlistentry><varlistentry><term>class</term><listitem><para>If the job is written in Java then this should be the name of
                                    the class that extends either</para><itemizedlist><listitem><para>org.exist.scheduler.StartupJob</para></listitem><listitem><para>org.exist.storage.SystemTask</para></listitem><listitem><para>org.exist.scheduler.UserJavaJob</para></listitem></itemizedlist></listitem></varlistentry><varlistentry><term>xquery</term><listitem><para>If the job is written in XQuery (not suitable for system jobs)
                                    then this should be a path to an XQuery stored in the database.
                                    e.g. <filename>/db/myCollection/myJob.xql</filename> XQuery
                                    job's will be launched under the guest account initially,
                                    although the running XQuery may switch permissions through calls
                                    to <methodname>xmldb:login()</methodname>.</para></listitem></varlistentry><varlistentry><term>cron-trigger</term><listitem><para>To define a firing pattern for the Job using Cron style syntax
                                    use this attribute otherwise for a periodic job use the period
                                    attribute. Not applicable to startup jobs.</para></listitem></varlistentry><varlistentry><term>unschedule-on-exception</term><listitem><para>Boolean: yes/true, no/false. Default: true. If true and an exception is
                                    encountered then the job is unscheduled for further execution until a
                                    restart; otherwise, the exception is ignored.</para></listitem></varlistentry><varlistentry><term>period</term><listitem><para>Can be used to define an explicit period for firing the job
                                    instead of a Cron style syntax. The period should be in
                                    milliseconds. Not applicable to startup jobs.</para></listitem></varlistentry><varlistentry><term>delay</term><listitem><para>Can be used with a period to delay the start of a job. If
                                    unspecified jobs will start as soon as the database and
                                    scheduler are initialised.</para></listitem></varlistentry><varlistentry><term>repeat</term><listitem><para>Can be used with a period to define for how many periods a job
                                    should be executed. If unspecified jobs will repeat for every
                                    period indefinitely.</para></listitem></varlistentry></variablelist><para>Every job can take additional parameters, which are passed as name/value
                        pairs (see example above).</para></section></section><section><title>&lt;serializer&gt;</title><para>The serializer is responsible for serializing XML documents or document
                    fragments back into XML. This configuration element defines default settings for
                    various parameters, which can also be specified programmatically. All settings
                    can be overwritten by XQuery <ulink url="xquery.xml#serialization">serialization
                        options</ulink>.</para><section><title>&lt;serializer&gt; Attributes</title><variablelist><varlistentry><term>enable-xinclude</term><listitem><para>This attribute determines whether <sgmltag>xinclude</sgmltag>
                                    tags are to be expanded during serialization. Setting the value
                                    to "<option>false</option>" will leave
                                        <sgmltag>xinclude</sgmltag> tags unexpanded.</para></listitem></varlistentry><varlistentry><term>enable-xsl</term><listitem><para>This attribute (when set to "<option>true</option>") tells the
                                    serializer to pass its output to an XSL stylesheet when it
                                    encounters an XSL processing-instruction at the start of the
                                    document.</para></listitem></varlistentry><varlistentry><term>add-exist-id</term><listitem><para>This attribute tells the serializer to add debug information
                                    to each element expressed as additional attributes. This
                                    information includes the internal identifier of the node and
                                    source document. These are the accepted values:</para><orderedlist><listitem><para><option>all</option> - Adds debug information to every
                                            node in the output.</para></listitem><listitem><para><option>element</option> - Adds debug information to
                                            top-level elements only.</para></listitem><listitem><para><option>none</option> (default) - Disables debugging
                                            feature.</para></listitem></orderedlist></listitem></varlistentry><varlistentry><term>indent</term><listitem><para>The serializer defaults to pretty-print the resulting XML
                                    source code. Set this option to "<option>no</option>" to disable
                                    pretty-printing.</para></listitem></varlistentry><varlistentry><term>match-tagging-elements</term><listitem><para>The database can highlight matches in the text content of a
                                    node by tagging the matching text string with
                                        <sgmltag>exist:match</sgmltag>. Clearly, this only works for
                                    XPath expressions using the fulltext index. Set the parameter to
                                        "<option>yes</option>" to <emphasis>disable</emphasis> this
                                    feature.</para></listitem></varlistentry></variablelist></section></section><section><title><sgmltag>transformer</sgmltag></title><para>This section determines which XSLT processor will be used by eXist. By
                    default, eXist relies on Xalan, which is an XSLT 1.0 engine. Please refer to
                        <ulink url="http://atomic.exist-db.org/wiki/HowTo/XSLT2/">this howto</ulink>
                    to switch to an XSLT 2.0 processor like saxon.</para></section><section><title><sgmltag>validation</sgmltag></title><para>Defines the default validation settings that will be active when parsing XML
                    and links to catalog files. Catalog files are used to locate DTDs, schemas and
                    resolve external entities in general.</para><para>Please refer to the corresponding documentation on <ulink url="validation.xml">XML Validation</ulink>.</para></section><section><title>&lt;xupdate&gt;</title><para>Inserting new nodes into a document can lead to fragmentation in the DOM
                    storage file. eXist will thus trigger a defragmentation run if the fragmentation
                    exceeds a certain limit. The frequency of such defragmentation runs can be
                    configured in the <sgmltag>xupdate</sgmltag> section. The main parameter is
                    called <option>allowed-fragmentation</option>:</para><example><title>XUpdate-Options in conf.xml</title><programlisting format="linespecific"><markup>&lt;xupdate allowed-fragmentation="20" enable-consistency-checks="no" /&gt;</markup></programlisting></example><section><title>&lt;xupdate&gt; Attributes</title><variablelist><varlistentry><term>allowed-fragmentation</term><listitem><para>This attribute defines the maximum number of page splits
                                    allowed within a document before a defragmentation run is
                                    triggered.</para></listitem></varlistentry><varlistentry><term>enable-consistency-checks</term><listitem><para>This attribute is for or debugging purposes only. If the
                                    parameter is set to "<option>yes</option>", a
                                        <emphasis>consistency check</emphasis> will be run on
                                    modified documents after every XUpdate request. This checks
                                    whether the persistent DOM is complete, and all pointers in the
                                    structural index point to valid storage addresses that contain
                                    valid nodes.</para></listitem></varlistentry></variablelist></section></section><section><title><sgmltag>xquery</sgmltag></title><example><title>XQuery Engine Configuration</title><programlisting><markup>&lt;xquery enable-java-binding="no" enable-query-rewriting="no" enforce-index-use="always" disable-deprecated-functions="no" raise-error-on-failed-retrieval="no" backwardCompatible="no"&gt;
    &lt;builtin-modules&gt;
        &lt;!-- Default Modules --&gt;
        &lt;module class="org.exist.xquery.functions.util.UtilModule"
            uri="http://exist-db.org/xquery/util" /&gt;
        &lt;!-- ... more modules ... --&gt;
    &lt;/builtin-modules&gt;
&lt;/xquery&gt;</markup></programlisting></example><para>The <sgmltag>xquery</sgmltag> section is used to enable/disable certain core
                    features of the XQuery engine. It also lists the XQuery modules that will be
                    known to the query engine by default.</para><section><title><sgmltag>xquery</sgmltag> attributes</title><variablelist><varlistentry><term>enable-java-binding=yes|no</term><listitem><para>enables or disables the <ulink url="xquery.xml#javamods">java
                                        binding</ulink>. Giving users full access to all Java
                                    classes should be considered a security risk and the feature is
                                    thus disabled by default. If you enable it, you should think
                                    about configuring <ulink url="xacml.xml">XACML</ulink> to
                                    restrict Java access from XQuery.</para></listitem></varlistentry><varlistentry><term>disable-deprecated-functions=yes|no</term><listitem><para>enables or disables XQuery functions marked as
                                    deprecated.</para></listitem></varlistentry><varlistentry><term>enforce-index-use=strict|always</term><listitem><para>controls if available range indexes should be used if only
                                    some collections in the context set define a matching index.
                                    Available settings are: "always" to always use an index, even if
                                    it does not apply to the entire set of collections being
                                    queried; "strict" to only use indexes if they are defined for
                                    the entire collection set.</para><para>For example, if you have two collections: /db/one and /db/two,
                                    and you define a range index on a certain element
                                        <sgmltag>node</sgmltag> in /db/one, but not in /db/two, the
                                    query engine would not use the index with setting "strict" if
                                    you query both collections. At compile time, eXist doesn't know
                                    if <sgmltag>node</sgmltag> exists in both collections and will
                                    not use the index if it determines that an index definition does
                                    only apply to a part of the collection set being queried. To use
                                    the index, you would need to start your XPath expression with a
                                    call to collection(), selecting the correct collection with the
                                    index defined.</para><para>On the other hand, if enforce-index-use is set to "always",
                                    the query engine only checks if one collection in the collection
                                    set has a matching index defined on it. This may lead to an
                                    incomplete query result if one forgets certain
                                    collections.</para><para>In other words, when enforce-index-use is set to "always", it
                                    is the query writers responsibility to make sure indexes are
                                    defined properly. But experience has shown it is easier for
                                    users to understand that a certain result is incomplete because
                                    an index is missing, whereas they have problems to see that a
                                    performance issue is caused by inconsistent indexing. </para></listitem></varlistentry><varlistentry><term>raise-error-on-failed-retrieval=yes|no</term><listitem><para>set to <literal>"yes"</literal> if a call to
                                        <command>doc()</command>,
                                        <command>xmldb:document()</command>,
                                        <command>collection()</command> or
                                        <command>xmldb:xcollection()</command> should raise an error
                                    (FODC0002) when an XML resource can not be retrieved.</para><para>set to <literal>"no"</literal> if a call to
                                        <command>doc()</command>,
                                        <command>xmldb:document()</command>,
                                        <command>collection()</command> or
                                        <command>xmldb:xcollection()</command> should return an
                                    empty sequence when an XML resource can not be retrieved.</para></listitem></varlistentry><varlistentry><term>enable-query-rewriting=yes|no</term><listitem><para>the query engine can often achieve considerable performance
                                    improvements by rewriting an XQuery expression into a more
                                    efficient form (see the documentation about <ulink url="indexing.xml#pathvsqname">indexing</ulink>). However,
                                    these features are relatively new. If you have doubts about the
                                    correctness of a query result, you may temporarily set
                                        <option>enable-query-rewriting</option> to
                                        <literal>"no"</literal> and see if the result changes in any
                                    way. If it does, you have hit a bug which should be reported.
                                </para></listitem></varlistentry><varlistentry><term>backwardCompatible=yes|no</term><listitem><para>enables or disables XPath 1.0 backwards compatibility. The
                                    setting mainly effects automatic type conversions, which were
                                    less strict in XPath 1.0 than in XQuery/XPath 2.0.</para></listitem></varlistentry></variablelist></section><section><title><sgmltag>builtin-modules</sgmltag></title><para>This section lists the XQuery modules which will be known to the query
                        engine. The modules in this list can be imported into a query without
                        specifying a location. For example, the following entry:</para><synopsis language="xml">&lt;module class="org.exist.xquery.modules.file.FileModule"
uri="http://exist-db.org/xquery/file" /&gt;</synopsis><para>establishes a static mapping between the module URI for the file module
                        and the Java class which implements it. When using that module, it is
                        sufficient to provide the correct URI in the import. Specifying a location
                        is not needed:</para><synopsis language="xquery">import module namespace file="http://exist-db.org/xquery/file";</synopsis><para>Instead of providing a Java class, one can also specify a src URI which
                        must point to the XQuery source code of the module, e.g.:</para><synopsis language="xml">&lt;module src="resource:org/exist/xquery/lib/json.xq" 
uri="http://www.json.org"/&gt;</synopsis><para>For the src attribute, eXist understands the <ulink url="http://localhost:8080/exist/xquery.xml#N10195">same types of
                            URIs</ulink> as in an ordinary XQuery import statement.</para></section></section></section></chapter></book>