Add some information about bounding the Cache module

Author: adamretter

src/main/xar-resources/data/extensions/extensions.xml

@@ -54,6 +54,42 @@
         <para>Whilst most extension modules work without any further configuration than that
             described above, some modules have additional configuration options. Those additional
             options are described in this section.</para>
+        <sect2 xml:id="module_cache">
+            <title>Cache Module</title>
+            <para>This module provides a Global Mutable cache which can be used for manually
+                caching data. This is often used for caching the results of expensive queries.</para>
+            <itemizedlist>
+                <listitem>
+                    <para>Creator: Adam Retter</para>
+                </listitem>
+                <listitem>
+                    <para>Licence: LGPL v2</para>
+                </listitem>
+                <listitem>
+                    <para>Used: <link xlink:href="https://github.com/ben-manes/caffeine">Caffeine</link></para>
+                </listitem>
+                <listitem>
+                    <para>Status: production</para>
+                </listitem>
+                <listitem>
+                    <para>Class: <code>org.exist.xquery.modules.cache.CacheModule</code>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>Namespace: <code>http://exist-db.org/xquery/cache</code></para>
+                </listitem>
+            </itemizedlist>
+            <para>
+                The Cache module can be configured for with a bounded size, or time, or both. eXist-db cannot
+                know how much memory the data you will put in the cache will take, so it is up to you to
+                manage your own memory needs here.
+            </para>
+            <para>A named cache can either be explicitly created by calling the <code>cache:create</code> XQuery
+                function, or it can be implicitly created lazing on the first operation performed on the cache.
+                Configuration of the Cache module is specified within the module definition of eXist-db's
+                <code>conf.xml</code> file:</para>
+            <programlisting language="xml" xlink:href="listings/listing-2.xml"/>
+        </sect2>
         <sect2 xml:id="module_sql">
             <title>SQL Module</title>
             <para>This module provides facilities for performing SQL operations against traditional
@@ -66,7 +102,7 @@
                     <para>Licence: LGPL v2</para>
                 </listitem>
                 <listitem>
-                    <para>Used: JDBC</para>
+                    <para>Used: <link xlink:href="https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/">JDBC</link></para>
                 </listitem>
                 <listitem>
                     <para>Status: production</para>

src/main/xar-resources/data/extensions/listings/listing-2.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module class="org.exist.xquery.modules.sql.CacheModule" uri="http://exist-db.org/xquery/cache">
+    <parameter name="enableLazyCreation" value="true"/>         <!-- allow the cache to be created implicitly -->
+    <parameter name="lazy.maximumSize" value="128"/>            <!-- size bound - 128 entries max -->
+    <parameter name="lazy.expireAfterAccess" value="60000"/>    <!-- time bound - 60 seconds -->
+</module>

src/main/xar-resources/data/production_good_practice/production_good_practice.xml

@@ -336,6 +336,9 @@
                             You should modify the <tag>builtin-modules</tag> section of
                             <literal>etc/conf.xml</literal> and <emphasis>only</emphasis> load what
                             you need for your application.</para>
+                            <para>If you make use of the Cache Module, you should make sure that it has either
+                                a <code>maximumSize</code> or <code>expireAfterAccess</code> bound configured,
+                            this ensures that the Cache can consume all memory.</para>
                     </listitem>
                 </varlistentry>
             </variablelist>