Document caches settings.

Author: fredericDelaporte

doc/reference/modules/nhibernate_caches.xml

@@ -125,6 +125,7 @@
 						<programlisting>
 &lt;property name="cache.provider_class"&gt;<literal>XXX</literal>&lt;/property&gt;<co id="hibernate.cache.provider_class-co" linkends="hibernate.cache.provider_class"/>
 &lt;property name="cache.default_expiration"&gt;<literal>120</literal>&lt;/property&gt;<co id="nhcaches-expiration-co" linkends="nhcaches-expiration"/>
+&lt;property name="cache.use_sliding_expiration"&gt;<literal>true</literal>&lt;/property&gt;<co id="nhcaches-sliding-co" linkends="nhcaches-sliding"/>
 						</programlisting>
 						<calloutlist>
 							<callout arearefs="hibernate.cache.provider_class-co" id="hibernate.cache.provider_class">
@@ -138,7 +139,15 @@
 							<callout arearefs="nhcaches-expiration-co" id="nhcaches-expiration">
 								<para>
 									The <literal>expiration</literal> value is the number of seconds you wish
-									to cache each entry (here two minutes). This example applies to SysCache only.
+									to cache each entry (here two minutes). Not all providers support this setting, it may
+									be ignored. Check their respective documentation.
+								</para>
+							</callout>
+							<callout arearefs="nhcaches-sliding-co" id="nhcaches-sliding">
+								<para>
+									The <literal>use_sliding_expiration</literal> value is whether you wish to use a
+									sliding expiration or not. Defaults to <literal>false</literal>.
+									Not all providers support this setting, it may be ignored. Check their respective documentation.
 								</para>
 							</callout>
 						</calloutlist>
@@ -190,29 +199,39 @@
 	<section id="NHibernate.Caches.SysCache">
 		<title>SysCache Configuration</title>
 		<para>
-			As SysCache relies on <classname>System.Web.Caching.Cache</classname> for the underlying implementation,
-			the configuration is based on the available options that make sense for NHibernate to utilize.
+			As SysCache relies on <classname>System.Web.Caching.Cache</classname> for the underlying implementation.
+			Following NHibernate configuration settings are available:
 		</para>
 
 		<variablelist>
 			<varlistentry>
 				<term><literal>expiration</literal></term>
 				<listitem>
 					Number of seconds to wait before expiring each item.
+					Takes precedence over <literal>cache.default_expiration</literal>.
+					If none of them are defined, defaults to <literal>300</literal>.
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term><literal>cache.use_sliding_expiration</literal></term>
+				<listitem>
+					Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+					Defaults to <literal>false</literal>.
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><literal>priority</literal></term>
 				<listitem>
 					A numeric cost of expiring each item, where 1 is a low cost, 5 is the highest, and 3 is normal.
-					Only values 1 through 5 are valid.
+					Only values 1 through 5 are valid. 6 is a special value corresponding to
+					<literal>NotRemovable</literal>, it should not be used.
 				</listitem>
 			</varlistentry>
 		</variablelist>
 
 		<para>
 			SysCache has a config file section handler to allow configuring different expirations and priorities for
-			different regions. Here's an example:
+			different regions. Here is an example:
 		</para>
 
 		<example>
@@ -225,7 +244,7 @@
 
   <syscache>
     <cache region="foo" expiration="500" priority="4" />
-    <cache region="bar" expiration="300" priority="3" />
+    <cache region="bar" expiration="300" priority="3" sliding="true" />
   </syscache>
 </configuration>]]></programlisting>
 		</example>
@@ -241,6 +260,28 @@
 			MSDN documentation.
 		</para>
 
+		<para>
+			Following NHibernate configuration settings are available:
+		</para>
+
+		<variablelist>
+			<varlistentry>
+				<term><literal>expiration</literal></term>
+				<listitem>
+					Number of seconds to wait before expiring each item.
+					Takes precedence over <literal>cache.default_expiration</literal>.
+					If none of them are defined, defaults to <literal>300</literal>.
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term><literal>cache.use_sliding_expiration</literal></term>
+				<listitem>
+					Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+					Defaults to <literal>false</literal>.
+				</listitem>
+			</varlistentry>
+		</variablelist>
+
 		<para>
 			To configure cache regions with SqlCacheDependencies a <literal>syscache2</literal> config section must be
 			defined in the application's configuration file. See the sample below.
@@ -462,7 +503,7 @@
 			<example>
 				<title>Relative Expiration</title>
 
-				<programlisting><![CDATA[<cacheRegion name="Product" relativeExpiration="300" priority="High" />]]></programlisting>
+				<programlisting><![CDATA[<cacheRegion name="Product" relativeExpiration="300" priority="High" useSlidingExpiration="true" />]]></programlisting>
 			</example>
 
 			<example>
@@ -478,6 +519,18 @@
 					<listitem>
 						<para>
 							Number of seconds that an individual item will exist in the cache before being removed.
+							Defaults to <literal>300</literal> if neither <literal>relativeExpiration</literal> nor
+							<literal>timeOfDayExpiration</literal> are defined, and if no expiration settings are
+							defined in NHibernate configuration.
+						</para>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><literal>useSlidingExpiration</literal></term>
+					<listitem>
+						<para>
+							Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+							Defaults to <literal>false</literal> if not defined in NHibernate configuration.
 						</para>
 					</listitem>
 				</varlistentry>
@@ -504,4 +557,51 @@
 
 	</section>
 
+	<section id="NHibernate.Caches.RtMemoryCache">
+		<title>Runtime Memory Configuration</title>
+		<para>
+			As runtime memory relies on <classname>System.Runtime.Caching.MemoryCache</classname> for the
+			underlying implementation.
+			Following NHibernate configuration settings are available:
+		</para>
+
+		<variablelist>
+			<varlistentry>
+				<term><literal>expiration</literal></term>
+				<listitem>
+					Number of seconds to wait before expiring each item.
+					Takes precedence over <literal>cache.default_expiration</literal>.
+					If none of them are defined, defaults to <literal>300</literal>.
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term><literal>cache.use_sliding_expiration</literal></term>
+				<listitem>
+					Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+					Defaults to <literal>false</literal>.
+				</listitem>
+			</varlistentry>
+		</variablelist>
+
+		<para>
+			RtMemoryCache has a config file section handler to allow configuring different expirations for
+			different regions. Here is an example:
+		</para>
+
+		<example>
+			<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
+<configuration>
+  <configSections>
+    <section name="syscache"
+      type="NHibernate.Caches.SysCache.SysCacheSectionHandler,NHibernate.Caches.SysCache" />
+  </configSections>
+
+  <syscache>
+    <cache region="foo" expiration="500" />
+    <cache region="bar" expiration="300" sliding="true" />
+  </syscache>
+</configuration>]]></programlisting>
+		</example>
+	</section>
+
 </chapter>