Skip to content

Commit 903494f

Browse files
hazzikhazzik
authored
Merge pull request #1379 from fredericDelaporte/DocFixes
Doc fixes
2 parents 63a288e + c3534d1 commit 903494f

File tree

10 files changed

+746
-78
lines changed

10 files changed

+746
-78
lines changed

‎doc/reference/modules/basic_mapping.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1763,6 +1763,7 @@
17631763
<para>
17641764
The <literal>cascade</literal> attribute permits the following values:
17651765
<literal>all</literal>, <literal>save-update</literal>, <literal>delete</literal>,
1766+
<literal>delete-orphan</literal>, <literal>all-delete-orphan</literal> and
17661767
<literal>none</literal>. Setting a value other than <literal>none</literal>
17671768
will propagate certain operations to the associated (child) object.
17681769
See "Lifecycle Objects" below.

‎doc/reference/modules/collection_mapping.xml

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -852,12 +852,6 @@ int accessLevel = permissions["accounts"]; // Error!]]></programlisting>
852852

853853
</para>
854854

855-
<para>
856-
Please note that NHibernate does not support bidirectional one-to-many associations
857-
with an indexed collection (list, map or array) as the "many" end, you have to
858-
use a set or bag mapping.
859-
</para>
860-
861855
<para>
862856
You may specify a bidirectional many-to-many association simply by mapping two
863857
many-to-many associations to the same database table and declaring one end as
@@ -937,6 +931,75 @@ session.Update(category); // The relationship will be saved]]></
937931

938932
</sect1>
939933

934+
<sect1 id="collections-indexedbidirectional">
935+
<title>Bidirectional associations with indexed collections</title>
936+
937+
<para>
938+
There are some additional considerations for bidirectional mappings with indexed collections
939+
(where one end is represented as a <literal>&lt;list&gt;</literal> or <literal>&lt;map&gt;</literal>)
940+
when using NHibernate mapping files. If there is a property of the child class that maps to the
941+
index column you can use <literal>inverse="true"</literal> on the collection mapping:
942+
</para>
943+
944+
<programlisting><![CDATA[<class name="Parent">
945+
<id name="Id" column="parent_id"/>
946+
....
947+
<map name="Children" inverse="true">
948+
<key column="parent_id"/>
949+
<map-key column="name"
950+
type="string"/>
951+
<one-to-many class="Child"/>
952+
</map>
953+
</class>
954+
955+
<class name="Child">
956+
<id name="Id" column="child_id"/>
957+
....
958+
<property name="Name" column="name"
959+
not-null="true"/>
960+
<many-to-one name="Parent"
961+
class="Parent"
962+
column="parent_id"
963+
not-null="true"/>
964+
</class>]]></programlisting>
965+
966+
<para>
967+
If there is no such property on the child class, the association cannot be considered truly
968+
bidirectional. That is, there is information available at one end of the association that is not
969+
available at the other end. In this case, you cannot map the collection
970+
<literal>inverse="true"</literal>. Instead, you could use the following mapping:
971+
</para>
972+
973+
<programlisting><![CDATA[<class name="Parent">
974+
<id name="Id" column="parent_id"/>
975+
....
976+
<map name="Children">
977+
<key column="parent_id"
978+
not-null="true"/>
979+
<map-key column="name"
980+
type="string"/>
981+
<one-to-many class="Child"/>
982+
</map>
983+
</class>
984+
985+
<class name="Child">
986+
<id name="Id" column="child_id"/>
987+
....
988+
<many-to-one name="Parent"
989+
class="Parent"
990+
column="parent_id"
991+
insert="false"
992+
update="false"
993+
not-null="true"/>
994+
</class>]]></programlisting>
995+
996+
<para>
997+
Note that in this mapping, the collection-valued end of the association is responsible for
998+
updates to the foreign key.
999+
</para>
1000+
1001+
</sect1>
1002+
9401003
<sect1 id="collections-ternary">
9411004
<title>Ternary Associations</title>
9421005

‎doc/reference/modules/configuration.xml

Lines changed: 515 additions & 46 deletions
Large diffs are not rendered by default.

‎doc/reference/modules/example_parentchild.xml

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -317,19 +317,24 @@ session.Flush();]]></programlisting>
317317
<programlisting><![CDATA[public class Persistent
318318
{
319319
private bool _saved = false;
320-
320+
321321
public void OnSave()
322322
{
323-
_saved=true;
323+
_saved = true;
324324
}
325-
325+
326326
public void OnLoad()
327327
{
328-
_saved=true;
328+
_saved = true;
329329
}
330-
330+
331+
public void OnDelete()
332+
{
333+
_saved = false;
334+
}
335+
331336
......
332-
337+
333338
public bool IsSaved
334339
{
335340
get { return _saved; }
@@ -338,8 +343,8 @@ session.Flush();]]></programlisting>
338343

339344
<para>
340345
(The <literal>saved</literal> property is non-persistent.)
341-
Now implement <literal>IsTransient()</literal>, along with <literal>OnLoad()</literal>
342-
and <literal>OnSave()</literal> as follows.
346+
Now implement <literal>IsTransient()</literal>, along with <literal>OnLoad()</literal>,
347+
<literal>OnSave()</literal> and <literal>OnDelete()</literal> as follows.
343348
</para>
344349

345350
<programlisting><![CDATA[public object IsTransient(object entity)
@@ -354,7 +359,7 @@ session.Flush();]]></programlisting>
354359
}
355360
}
356361
357-
public bool OnLoad(object entity,
362+
public bool OnLoad(object entity,
358363
object id,
359364
object[] state,
360365
string[] propertyNames,
@@ -372,8 +377,17 @@ public boolean OnSave(object entity,
372377
{
373378
if (entity is Persistent) ( (Persistent) entity ).OnSave();
374379
return false;
380+
}
381+
382+
public virtual void OnDelete(object entity,
383+
object id,
384+
object[] state,
385+
string[] propertyNames,
386+
IType[] types)
387+
{
388+
if (entity is Persistent) ( (Persistent) entity ).OnDelete();
375389
}]]></programlisting>
376-
390+
377391
</sect1>
378392

379393
<sect1 id="example-parentchild-conclusion">

‎doc/reference/modules/manipulating_data.xml

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,63 @@ q.SetString(0, name);
297297
q.SetInt32(1, minWeight);
298298
var cats = q.List<Cat>();]]></programlisting>
299299

300+
<para>
301+
Named queries are by default validated at startup time, allowing to catch errors
302+
more easily than having to test all the application features using HQL queries. In
303+
case of validation errors, the details of failing queries are logged and a
304+
validation error is raised.
305+
</para>
306+
307+
<para>
308+
Named queries accepts a number of attributes matching settings available on the
309+
<literal>IQuery</literal> interface.
310+
</para>
311+
312+
<itemizedlist spacing="compact">
313+
<listitem>
314+
<para>
315+
<literal>flush-mode</literal> - override the session flush mode just for this query.
316+
</para>
317+
</listitem>
318+
<listitem>
319+
<para>
320+
<literal>cacheable</literal> - allow the query results to be cached by the second level cache.
321+
See <xref linkend="caches"/>.
322+
</para>
323+
</listitem>
324+
<listitem>
325+
<para>
326+
<literal>cache-region</literal> - specify the cache region of the query.
327+
</para>
328+
</listitem>
329+
<listitem>
330+
<para>
331+
<literal>cache-mode</literal> - specify the cache mode of the query.
332+
</para>
333+
</listitem>
334+
<listitem>
335+
<para>
336+
<literal>fetch-size</literal> - set a fetch size for the underlying ADO query.
337+
</para>
338+
</listitem>
339+
<listitem>
340+
<para>
341+
<literal>timeout</literal> - set the query timeout in seconds.
342+
</para>
343+
</listitem>
344+
<listitem>
345+
<para>
346+
<literal>read-only</literal> - <literal>true</literal> switches yielded entities to read-only.
347+
See <xref linkend="readonly"/>.
348+
</para>
349+
</listitem>
350+
<listitem>
351+
<para>
352+
<literal>comment</literal> - add a custom comment to the generated SQL.
353+
</para>
354+
</listitem>
355+
</itemizedlist>
356+
300357
<para>
301358
The query interface supports the use of named parameters. Named parameters
302359
are identifiers of the form <literal>:name</literal> in the query string.

‎doc/reference/modules/nhibernate_caches.xml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,14 @@
9191
</para>
9292
</listitem>
9393
</varlistentry>
94+
<varlistentry>
95+
<term><classname>NHibernate.Caches.RtMemoryCache</classname></term>
96+
<listitem>
97+
<para>
98+
Uses <classname>System.Runtime.Caching.MemoryCache.Default</classname> as the cache provider.
99+
</para>
100+
</listitem>
101+
</varlistentry>
94102
</variablelist>
95103
</para>
96104
</abstract>

‎doc/reference/modules/performance.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -516,7 +516,7 @@ using(var iter = session
516516

517517
<para>
518518
NHibernate can make efficient use of batch fetching, that is, NHibernate can load several uninitialized
519-
proxies if one proxy is accessed (or collections. Batch fetching is an optimization of the lazy select
519+
proxies if one proxy is accessed (or collections). Batch fetching is an optimization of the lazy select
520520
fetching strategy. There are two ways you can tune batch fetching: on the class and the collection level.
521521
</para>
522522

‎doc/reference/modules/query_sql.xml

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -463,6 +463,56 @@ var pusList = query.SetString("name", "Pus%").List<Cat>();]]></programlisting>
463463
.SetResultSetMapping("catAndKitten")
464464
.List<Cat>();]]></programlisting>
465465

466+
<para>
467+
Like HQL named queries, SQL named queries accepts a number of attributes matching settings
468+
available on the <literal>ISQLQuery</literal> interface.
469+
</para>
470+
471+
<itemizedlist spacing="compact">
472+
<listitem>
473+
<para>
474+
<literal>flush-mode</literal> - override the session flush mode just for this query.
475+
</para>
476+
</listitem>
477+
<listitem>
478+
<para>
479+
<literal>cacheable</literal> - allow the query results to be cached by the second level cache.
480+
See <xref linkend="caches"/>.
481+
</para>
482+
</listitem>
483+
<listitem>
484+
<para>
485+
<literal>cache-region</literal> - specify the cache region of the query.
486+
</para>
487+
</listitem>
488+
<listitem>
489+
<para>
490+
<literal>cache-mode</literal> - specify the cache mode of the query.
491+
</para>
492+
</listitem>
493+
<listitem>
494+
<para>
495+
<literal>fetch-size</literal> - set a fetch size for the underlying ADO query.
496+
</para>
497+
</listitem>
498+
<listitem>
499+
<para>
500+
<literal>timeout</literal> - set the query timeout in seconds.
501+
</para>
502+
</listitem>
503+
<listitem>
504+
<para>
505+
<literal>read-only</literal> - <literal>true</literal> switches yielded entities to read-only.
506+
See <xref linkend="readonly"/>.
507+
</para>
508+
</listitem>
509+
<listitem>
510+
<para>
511+
<literal>comment</literal> - add a custom comment to the SQL.
512+
</para>
513+
</listitem>
514+
</itemizedlist>
515+
466516
<sect2 id="propertyresults">
467517
<title>Using return-property to explicitly specify column/alias
468518
names</title>

‎src/NHibernate/Cfg/Environment.cs

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
using NHibernate.Bytecode;
77
using NHibernate.Cfg.ConfigurationSchema;
88
using NHibernate.Engine;
9+
using NHibernate.Linq;
910
using NHibernate.Util;
1011

1112
namespace NHibernate.Cfg
@@ -78,6 +79,7 @@ public static string Version
7879
public const string ConnectionStringName = "connection.connection_string_name";
7980

8081
// Unused, Java-specific
82+
// But has many code usage though.
8183
public const string SessionFactoryName = "session_factory_name";
8284

8385
public const string Dialect = "dialect";
@@ -109,13 +111,16 @@ public static string Version
109111
/// <summary> Enable formatting of SQL logged to the console</summary>
110112
public const string FormatSql = "format_sql";
111113

112-
// Unused, Java-specific
114+
// Since v5.0.1
115+
[Obsolete("This setting has no usages and will be removed in a future version")]
113116
public const string UseGetGeneratedKeys = "jdbc.use_get_generated_keys";
114117

115-
// Unused, not implemented
118+
// Since v5.0.1
119+
[Obsolete("This setting has no usages and will be removed in a future version")]
116120
public const string StatementFetchSize = "jdbc.fetch_size";
117121

118-
// Unused, not implemented
122+
// Since v5.0.1
123+
[Obsolete("This setting has no usages and will be removed in a future version")]
119124
public const string OutputStylesheet = "xml.output_stylesheet";
120125

121126
public const string TransactionStrategy = "transaction.factory_class";
@@ -140,7 +145,8 @@ public static string Version
140145
/// </summary>
141146
public const string UseConnectionOnSystemTransactionPrepare = "transaction.use_connection_on_system_prepare";
142147

143-
// Unused, not implemented (and somewhat Java-specific)
148+
// Since v5.0.1
149+
[Obsolete("This setting has no usages and will be removed in a future version")]
144150
public const string TransactionManagerStrategy = "transaction.manager_lookup_class";
145151

146152
public const string CacheProvider = "cache.provider_class";
@@ -159,19 +165,25 @@ public static string Version
159165
/// <summary> Enable statistics collection</summary>
160166
public const string GenerateStatistics = "generate_statistics";
161167

168+
// Its test is ignored with reason "Not supported yet".
162169
public const string UseIdentifierRollBack = "use_identifier_rollback";
163170

164-
// The classname of the HQL query parser factory
171+
/// <summary>
172+
/// The classname of the HQL query parser factory.
173+
/// </summary>
165174
public const string QueryTranslator = "query.factory_class";
166175

167-
// The class name of the LINQ query provider class, implementing from <see cref="INhQueryProvider"/>
176+
/// <summary>
177+
/// The class name of the LINQ query provider class, implementing <see cref="INhQueryProvider"/>.
178+
/// </summary>
168179
public const string QueryLinqProvider = "query.linq_provider_class";
169180

181+
// Since v5.0.1
182+
[Obsolete("This setting has no usages and will be removed in a future version")]
170183
public const string QueryImports = "query.imports";
171184
public const string Hbm2ddlAuto = "hbm2ddl.auto";
172185
public const string Hbm2ddlKeyWords = "hbm2ddl.keywords";
173186

174-
// Unused, not implemented
175187
public const string SqlExceptionConverter = "sql_exception_converter";
176188

177189
public const string BatchVersionedData = "adonet.batch_versioned_data";
@@ -195,10 +207,10 @@ public static string Version
195207

196208
public const string LinqToHqlGeneratorsRegistry = "linqtohql.generatorsregistry";
197209

198-
/// <summary> Enable ordering of insert statements for the purpose of more effecient batching.</summary>
210+
/// <summary> Enable ordering of insert statements for the purpose of more efficient batching.</summary>
199211
public const string OrderInserts = "order_inserts";
200212

201-
/// <summary> Enable ordering of update statements for the purpose of more effecient batching.</summary>
213+
/// <summary> Enable ordering of update statements for the purpose of more efficient batching.</summary>
202214
public const string OrderUpdates = "order_updates";
203215

204216
public const string QueryModelRewriterFactory = "query.query_model_rewriter_factory";

0 commit comments

Comments
 (0)