Skip to content

Documentation fixes #1395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 31, 2017
Merged

Documentation fixes #1395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0240b73
Remove reference to <nhibernate> configuration section
fredericDelaporte Oct 20, 2017
1b9d44e
Document nhibernate-logger configuration property
fredericDelaporte Oct 20, 2017
5e4520f
Improve second level cache documentation
fredericDelaporte Oct 22, 2017
14c989f
Backport CSS updates
fredericDelaporte Oct 26, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/reference/modules/component_mapping.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
56 changes: 41 additions & 15 deletions doc/reference/modules/configuration.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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">
Expand Down Expand Up @@ -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>.
Expand All @@ -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> |
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down
148 changes: 132 additions & 16 deletions doc/reference/modules/nhibernate_caches.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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.
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
9 changes: 6 additions & 3 deletions doc/reference/styles/html.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,9 @@ HR {
font-weight:bold;
}




.book > DIV, .chapter, .preface {
max-width: 50em;
margin-left: auto;
margin-right: auto;
font-size: large;
}