Skip to content

Documentation fixes #1379

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 5 commits into from
Oct 14, 2017
Merged

Documentation fixes #1379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fa81f63
Fix #1179 - Wrong documentation of cascade
fredericDelaporte Oct 13, 2017
4cf8cda
Fix #1165 - Bidirectional, indexed collections documentation
fredericDelaporte Oct 13, 2017
2922e40
Fix #824 - Document all possible settings in hibernate.cfg
fredericDelaporte Oct 14, 2017
babbdb6
Fix #823 - OnDelete should set IsSaved to false
fredericDelaporte Oct 14, 2017
c3534d1
Fix #788 - Undocumented attributes on sql-query
fredericDelaporte Oct 14, 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
1 change: 1 addition & 0 deletions doc/reference/modules/basic_mapping.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1763,6 +1763,7 @@
<para>
The <literal>cascade</literal> attribute permits the following values:
<literal>all</literal>, <literal>save-update</literal>, <literal>delete</literal>,
<literal>delete-orphan</literal>, <literal>all-delete-orphan</literal> and
<literal>none</literal>. Setting a value other than <literal>none</literal>
will propagate certain operations to the associated (child) object.
See "Lifecycle Objects" below.
Expand Down
75 changes: 69 additions & 6 deletions doc/reference/modules/collection_mapping.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -852,12 +852,6 @@ int accessLevel = permissions["accounts"]; // Error!]]></programlisting>

</para>

<para>
Please note that NHibernate does not support bidirectional one-to-many associations
with an indexed collection (list, map or array) as the "many" end, you have to
use a set or bag mapping.
</para>

<para>
You may specify a bidirectional many-to-many association simply by mapping two
many-to-many associations to the same database table and declaring one end as
Expand Down Expand Up @@ -937,6 +931,75 @@ session.Update(category); // The relationship will be saved]]></

</sect1>

<sect1 id="collections-indexedbidirectional">
<title>Bidirectional associations with indexed collections</title>

<para>
There are some additional considerations for bidirectional mappings with indexed collections
(where one end is represented as a <literal>&lt;list&gt;</literal> or <literal>&lt;map&gt;</literal>)
when using NHibernate mapping files. If there is a property of the child class that maps to the
index column you can use <literal>inverse="true"</literal> on the collection mapping:
</para>

<programlisting><![CDATA[<class name="Parent">
<id name="Id" column="parent_id"/>
....
<map name="Children" inverse="true">
<key column="parent_id"/>
<map-key column="name"
type="string"/>
<one-to-many class="Child"/>
</map>
</class>

<class name="Child">
<id name="Id" column="child_id"/>
....
<property name="Name" column="name"
not-null="true"/>
<many-to-one name="Parent"
class="Parent"
column="parent_id"
not-null="true"/>
</class>]]></programlisting>

<para>
If there is no such property on the child class, the association cannot be considered truly
bidirectional. That is, there is information available at one end of the association that is not
available at the other end. In this case, you cannot map the collection
<literal>inverse="true"</literal>. Instead, you could use the following mapping:
</para>

<programlisting><![CDATA[<class name="Parent">
<id name="Id" column="parent_id"/>
....
<map name="Children">
<key column="parent_id"
not-null="true"/>
<map-key column="name"
type="string"/>
<one-to-many class="Child"/>
</map>
</class>

<class name="Child">
<id name="Id" column="child_id"/>
....
<many-to-one name="Parent"
class="Parent"
column="parent_id"
insert="false"
update="false"
not-null="true"/>
</class>]]></programlisting>

<para>
Note that in this mapping, the collection-valued end of the association is responsible for
updates to the foreign key.
</para>

</sect1>

<sect1 id="collections-ternary">
<title>Ternary Associations</title>

Expand Down
561 changes: 515 additions & 46 deletions doc/reference/modules/configuration.xml
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 24 additions & 10 deletions doc/reference/modules/example_parentchild.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,19 +317,24 @@ session.Flush();]]></programlisting>
<programlisting><![CDATA[public class Persistent
{
private bool _saved = false;

public void OnSave()
{
_saved=true;
_saved = true;
}

public void OnLoad()
{
_saved=true;
_saved = true;
}


public void OnDelete()
{
_saved = false;
}

......

public bool IsSaved
{
get { return _saved; }
Expand All @@ -338,8 +343,8 @@ session.Flush();]]></programlisting>

<para>
(The <literal>saved</literal> property is non-persistent.)
Now implement <literal>IsTransient()</literal>, along with <literal>OnLoad()</literal>
and <literal>OnSave()</literal> as follows.
Now implement <literal>IsTransient()</literal>, along with <literal>OnLoad()</literal>,
<literal>OnSave()</literal> and <literal>OnDelete()</literal> as follows.
</para>

<programlisting><![CDATA[public object IsTransient(object entity)
Expand All @@ -354,7 +359,7 @@ session.Flush();]]></programlisting>
}
}

public bool OnLoad(object entity,
public bool OnLoad(object entity,
object id,
object[] state,
string[] propertyNames,
Expand All @@ -372,8 +377,17 @@ public boolean OnSave(object entity,
{
if (entity is Persistent) ( (Persistent) entity ).OnSave();
return false;
}

public virtual void OnDelete(object entity,
object id,
object[] state,
string[] propertyNames,
IType[] types)
{
if (entity is Persistent) ( (Persistent) entity ).OnDelete();
}]]></programlisting>

</sect1>

<sect1 id="example-parentchild-conclusion">
Expand Down
57 changes: 57 additions & 0 deletions doc/reference/modules/manipulating_data.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,63 @@ q.SetString(0, name);
q.SetInt32(1, minWeight);
var cats = q.List<Cat>();]]></programlisting>

<para>
Named queries are by default validated at startup time, allowing to catch errors
more easily than having to test all the application features using HQL queries. In
case of validation errors, the details of failing queries are logged and a
validation error is raised.
</para>

<para>
Named queries accepts a number of attributes matching settings available on the
<literal>IQuery</literal> interface.
</para>

<itemizedlist spacing="compact">
<listitem>
<para>
<literal>flush-mode</literal> - override the session flush mode just for this query.
</para>
</listitem>
<listitem>
<para>
<literal>cacheable</literal> - allow the query results to be cached by the second level cache.
See <xref linkend="caches"/>.
</para>
</listitem>
<listitem>
<para>
<literal>cache-region</literal> - specify the cache region of the query.
</para>
</listitem>
<listitem>
<para>
<literal>cache-mode</literal> - specify the cache mode of the query.
</para>
</listitem>
<listitem>
<para>
<literal>fetch-size</literal> - set a fetch size for the underlying ADO query.
</para>
</listitem>
<listitem>
<para>
<literal>timeout</literal> - set the query timeout in seconds.
</para>
</listitem>
<listitem>
<para>
<literal>read-only</literal> - <literal>true</literal> switches yielded entities to read-only.
See <xref linkend="readonly"/>.
</para>
</listitem>
<listitem>
<para>
<literal>comment</literal> - add a custom comment to the generated SQL.
</para>
</listitem>
</itemizedlist>

<para>
The query interface supports the use of named parameters. Named parameters
are identifiers of the form <literal>:name</literal> in the query string.
Expand Down
8 changes: 8 additions & 0 deletions doc/reference/modules/nhibernate_caches.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,14 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><classname>NHibernate.Caches.RtMemoryCache</classname></term>
<listitem>
<para>
Uses <classname>System.Runtime.Caching.MemoryCache.Default</classname> as the cache provider.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</abstract>
Expand Down
2 changes: 1 addition & 1 deletion doc/reference/modules/performance.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -516,7 +516,7 @@ using(var iter = session

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

Expand Down
50 changes: 50 additions & 0 deletions doc/reference/modules/query_sql.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -463,6 +463,56 @@ var pusList = query.SetString("name", "Pus%").List<Cat>();]]></programlisting>
.SetResultSetMapping("catAndKitten")
.List<Cat>();]]></programlisting>

<para>
Like HQL named queries, SQL named queries accepts a number of attributes matching settings
available on the <literal>ISQLQuery</literal> interface.
</para>

<itemizedlist spacing="compact">
<listitem>
<para>
<literal>flush-mode</literal> - override the session flush mode just for this query.
</para>
</listitem>
<listitem>
<para>
<literal>cacheable</literal> - allow the query results to be cached by the second level cache.
See <xref linkend="caches"/>.
</para>
</listitem>
<listitem>
<para>
<literal>cache-region</literal> - specify the cache region of the query.
</para>
</listitem>
<listitem>
<para>
<literal>cache-mode</literal> - specify the cache mode of the query.
</para>
</listitem>
<listitem>
<para>
<literal>fetch-size</literal> - set a fetch size for the underlying ADO query.
</para>
</listitem>
<listitem>
<para>
<literal>timeout</literal> - set the query timeout in seconds.
</para>
</listitem>
<listitem>
<para>
<literal>read-only</literal> - <literal>true</literal> switches yielded entities to read-only.
See <xref linkend="readonly"/>.
</para>
</listitem>
<listitem>
<para>
<literal>comment</literal> - add a custom comment to the SQL.
</para>
</listitem>
</itemizedlist>

<sect2 id="propertyresults">
<title>Using return-property to explicitly specify column/alias
names</title>
Expand Down
30 changes: 21 additions & 9 deletions src/NHibernate/Cfg/Environment.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
using NHibernate.Bytecode;
using NHibernate.Cfg.ConfigurationSchema;
using NHibernate.Engine;
using NHibernate.Linq;
using NHibernate.Util;

namespace NHibernate.Cfg
Expand Down Expand Up @@ -78,6 +79,7 @@ public static string Version
public const string ConnectionStringName = "connection.connection_string_name";

// Unused, Java-specific
// But has many code usage though.
public const string SessionFactoryName = "session_factory_name";
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not switched to obsolete because its many code usages imply a lot of changes, and so I am not sure it has really not any use. (And I do not intend to investigate further the subject.)


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

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

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

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

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

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

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

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

// The classname of the HQL query parser factory
/// <summary>
/// The classname of the HQL query parser factory.
/// </summary>
public const string QueryTranslator = "query.factory_class";

// The class name of the LINQ query provider class, implementing from <see cref="INhQueryProvider"/>
/// <summary>
/// The class name of the LINQ query provider class, implementing <see cref="INhQueryProvider"/>.
/// </summary>
public const string QueryLinqProvider = "query.linq_provider_class";

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

// Unused, not implemented
public const string SqlExceptionConverter = "sql_exception_converter";

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

public const string LinqToHqlGeneratorsRegistry = "linqtohql.generatorsregistry";

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

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

public const string QueryModelRewriterFactory = "query.query_model_rewriter_factory";
Expand Down
Loading