Merge pull request #1395 from fredericDelaporte/EvenMoreDocFixes

hazzik · web-flow · commit 0891c13eca93 · 2017-10-31T16:42:09.000+13:00
Documentation fixes
diff --git a/doc/reference/modules/component_mapping.xml b/doc/reference/modules/component_mapping.xml
@@ -225,6 +225,12 @@
                     notion of composite key equality.
                 </para>
             </listitem>
+            <listitem>
+                <para>
+                    It should re-implement <literal>ToString()</literal> if you consider
+                    using the second level cache. See <xref linkend="NHibernate.Caches-howto" />.
+                </para>
+            </listitem>
         </itemizedlist>
 
         <para>
diff --git a/doc/reference/modules/configuration.xml b/doc/reference/modules/configuration.xml
@@ -146,13 +146,6 @@ var session = sessions.OpenSession(conn);
                     <literal>Configuration.SetProperties()</literal>.
                 </para>
             </listitem>
-            <listitem>
-                <para>
-                    Add the properties to a configuration section in the application
-                    configuration file. The section should be named <literal>nhibernate</literal>
-                    and its handler set to <literal>System.Configuration.NameValueSectionHandler</literal>.
-                </para>
-            </listitem>
             <listitem>
                 <para>
                     Include <literal>&lt;property&gt;</literal> elements in a configuration
@@ -449,13 +442,11 @@ var session = sessions.OpenSession(conn);
         </para>
 
         <para>
-            System-level properties can only be set manually by setting static properties of
+            Some properties are system-level properties. They can only be set manually by setting static properties of
             <literal>NHibernate.Cfg.Environment</literal> class or be defined in the
-            <literal>&lt;nhibernate&gt;</literal> section of the application
-            configuration file. These properties cannot be set using
-            <literal>Configuration.SetProperties</literal> or be defined in the
-            <literal>&lt;hibernate-configuration&gt;</literal> section of the application configuration
-            file.
+            <literal>&lt;hibernate-configuration&gt;</literal> section of the application
+            configuration file. These properties cannot be set using <literal>Configuration.SetProperties</literal> or
+            the <literal>hibernate.cfg.xml</literal> configuration file.
         </para>
 
         <table frame="topbot" id="configuration-optional-properties" revision="3">
@@ -529,7 +520,7 @@ var session = sessions.OpenSession(conn);
                         </entry>
                         <entry>
                             Enables use of a runtime-generated class to set or get properties of an entity
-                            or component instead of using runtime reflection (System-level property).
+                            or component instead of using runtime reflection. This is a system-level property.
                             The use of the reflection optimizer inflicts a certain startup cost on the
                             application but should lead to better performance in the long run.
                             Defaults to <literal>true</literal>.
@@ -552,9 +543,17 @@ var session = sessions.OpenSession(conn);
                         </entry>
                         <entry>
                             Specifies the bytecode provider to use to optimize the use of reflection in NHibernate.
+                            This is a system-level property.
                             Use <literal>null</literal> to disable the optimization completely, <literal>lcg</literal>
                             to use built-in lightweight code generation, or the class name of a custom
                             <literal>IBytecodeProvider</literal> implementation. Defaults to <literal>lcg</literal>.
+                            <para>
+                                You can not set this property in <literal>hibernate.cfg.xml</literal>, but only
+                                in <literal>&lt;hibernate-configuration&gt;</literal> section of the application
+                                configuration file or by code by setting
+                                <literal>NHibernate.Cfg.Environment.BytecodeProvider</literal>
+                                before creating any <literal>NHibernate.Cfg.Configuration</literal> instance.
+                            </para>
                             <para>
                                 <emphasis role="strong">eg.</emphasis>
                                 <literal>null</literal> | <literal>lcg</literal> |
@@ -1092,6 +1091,33 @@ in the parameter binding.</programlisting>
                             </para>
                         </entry>
                     </row>
+                    <row>
+                        <entry>
+                            <literal>nhibernate-logger</literal>
+                        </entry>
+                        <entry>
+                            The class name of an <literal>ILoggerFactory</literal> implementation. It allows using another
+                            logger than log4net.
+                            <para>
+                                The default is not defined, which causes NHibernate to search for log4net assembly. If this
+                                search succeeds, NHibernate will log with log4net. Otherwise, its internal logging will
+                                be disabled.
+                            </para>
+                            <para>
+                                This is a very special system-level property. It can only be set through an
+                                <ulink url="https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/appsettings/">appSetting</ulink>
+                                named <literal>nhibernate-logger</literal> in the application configuration file. It cannot
+                                be set neither with <literal>NHibernate.Cfg.Environment</literal> class, nor be defined in the
+                                <literal>&lt;hibernate-configuration&gt;</literal> section of the application
+                                configuration file, nor supplied by using <literal>Configuration.SetProperties</literal>, nor
+                                set in the <literal>hibernate.cfg.xml</literal> configuration file.
+                            </para>
+                            <para>
+                                <emphasis role="strong">eg.</emphasis>
+                                <literal>classname.of.LoggerFactory, assembly</literal>
+                            </para>
+                        </entry>
+                    </row>
                 </tbody>
             </tgroup>
         </table>
@@ -1483,7 +1509,7 @@ in the parameter binding.</programlisting>
         <para>
             An alternative approach is to specify a full configuration in a file named
             <literal>hibernate.cfg.xml</literal>. This file can be used as a replacement
-            for the <literal>&lt;nhibernate;&gt;</literal> or <literal>&lt;hibernate-configuration&gt;</literal>
+            for the <literal>&lt;hibernate-configuration&gt;</literal>
             sections of the application configuration file.
         </para>
 
diff --git a/doc/reference/modules/nhibernate_caches.xml b/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>
@@ -156,15 +165,31 @@
 		<formalpara>
 			<title>Be careful</title>
 			<para>
-				Caches are never aware of changes made to the persistent store by another process (though they may be
-				configured to regularly expire cached data). As the caches are created at the session factory level,
-				they are destroyed with the SessionFactory instance; so you must keep them alive as long as you need
-				them.
-			</para>
-			<para>
-				The second level cache requires the use of transactions, be it through transaction scopes or NHibernate
-				transactions. Interacting with the data store without an explicit transaction is discouraged, and will
-				not allow the second level cache to work as intended.
+				<itemizedlist>
+					<listitem>
+						<para>
+							Most caches are never aware of changes made to the persistent store by another process (though they may be
+							configured to regularly expire cached data). As the caches are created at the session factory level,
+							they are destroyed with the SessionFactory instance; so you must keep them alive as long as you need
+							them.
+						</para>
+					</listitem>
+					<listitem>
+						<para>
+							The second level cache requires the use of transactions, be it through transaction scopes or NHibernate
+							transactions. Interacting with the data store without an explicit transaction is discouraged, and will
+							not allow the second level cache to work as intended.
+						</para>
+					</listitem>
+					<listitem>
+						<para>
+							To avoid issues with composite ids and some cache providers, <literal>ToString()</literal> needs to
+							be overridden on composite id classes. It should yield an unique string representing the id. If the
+							composite id is mapped as a component, overriding the component <literal>ToString()</literal>
+							is enough. See <xref linkend="components-compositeid" />.
+						</para>
+					</listitem>
+				</itemizedlist>
 			</para>
 		</formalpara>
 		<para>
@@ -184,29 +209,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>
@@ -219,7 +254,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>
@@ -235,6 +270,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.
@@ -456,7 +513,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>
@@ -472,6 +529,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>
@@ -498,4 +567,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>
diff --git a/doc/reference/styles/html.css b/doc/reference/styles/html.css
@@ -92,6 +92,9 @@ HR  {
     font-weight:bold;
 }
 
-
-
-    
+.book > DIV, .chapter, .preface {
+    max-width: 50em;
+    margin-left: auto;
+    margin-right: auto;
+    font-size: large;
+}
