Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

This commit was manufactured by cvs2svn to create tag 'beta_0-7-0-0'.

SVN: tags/beta_0-7-0-0@1292
  • Loading branch information...
commit 57516ee0554c488b7495ffb36bf6db3b8a087f01 1 parent f021a5b
(no author) authored
Showing with 4 additions and 480 deletions.
  1. +4 −480 doc/reference/en/modules/basic_mapping.xml
484 doc/reference/en/modules/basic_mapping.xml
View
@@ -249,9 +249,9 @@
<para>
The optional <literal>proxy</literal> attribute enables lazy initialization of persistent
- instances of the class. NHibernate will initially return proxies generated by Castle.DynamicProxy
- which implement the named interface or extend the class. The actual persistent object will be
- loaded when a method of the proxy is invoked. See "Proxies for Lazy Initialization" below.
+ instances of the class. NHibernate will initially return Aspect# proxies which implement
+ the named interface. The actual persistent object will be loaded when a method of the
+ proxy is invoked. See "Proxies for Lazy Initialization" below.
</para>
<para><emphasis>Implicit</emphasis> polymorphism means that instances of the class will be returned
@@ -358,480 +358,9 @@
There is an alternative <literal>&lt;composite-id&gt;</literal> declaration to allow access to
legacy data with composite keys. We strongly discourage its use for anything else.
</para>
-
- <sect3 id="mapping-declaration-id-generator">
- <title>generator</title>
-
- <para>
- The required <literal>&lt;generator&gt;</literal> child element names a .NET type used
- to generate unique identifiers for instances of the persistent class. If any parameters
- are required to configure or initialize the generator instance, they are passed using the
- <literal>&lt;param&gt;</literal> element.
- </para>
-
- <programlisting><![CDATA[<id name="Id" type="Int64" column="uid" unsaved-value="0">
- <generator class="NHibernate.Id.TableHiLoGenerator">
- <param name="table">uid_table</param>
- <param name="column">next_hi_value_column</param>
- </generator>
-</id>]]></programlisting>
-
- <para>
- All generators implement the interface <literal>NHibernate.Id.IdentifierGenerator</literal>.
- This is a very simple interface; some applications may choose to provide their own specialized
- implementations. However, NHibernate provides a range of built-in implementations. There are shortcut
- names for the built-in generators:
-
- <variablelist>
- <varlistentry>
- <term><literal>identity</literal></term>
- <listitem>
- <para>
- supports identity columns in DB2, MySQL, MS SQL Server, Sybase and
- HypersonicSQL. The returned identifier is of type <literal>Int64</literal>,
- <literal>Int32</literal> or <literal>Int16</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>sequence</literal></term>
- <listitem>
- <para>
- uses a sequence in DB2, PostgreSQL, Oracle. The returned identifier
- is of type <literal>Int64</literal>,
- <literal>Int32</literal> or <literal>Int16</literal>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>hilo</literal></term>
- <listitem>
- <para>
- uses a hi/lo algorithm to efficiently generate identifiers of
- type <literal>Int64</literal>, <literal>Int32</literal> or <literal>Int16</literal>,
- given a table and column (by default <literal>hibernate_unique_key</literal> and
- <literal>next</literal> respectively) as a source of hi values. The hi/lo algorithm
- generates identifiers that are unique only for a particular database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>seqhilo</literal></term>
- <listitem>
- <para>
- uses a hi/lo algorithm to efficiently generate identifiers of type
- <literal>Int64</literal>, <literal>Int32</literal> or <literal>Int16</literal>,
- given a named database sequence.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>uuid.hex</literal></term>
- <listitem>
- <para>
- uses <literal>System.Guid</literal> and its <literal>ToString(string format)</literal> method
- to generate identifiers of type string. The length of the string returned depends on the
- configured <literal>format</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>uuid.string</literal></term>
- <listitem>
- <para>
- uses a new <literal>System.Guid</literal> to create a <literal>byte[]</literal> that is
- converted to a string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>guid</literal></term>
- <listitem>
- <para>
- uses a new <literal>System.Guid</literal> as the identifier.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>guid.comb</literal></term>
- <listitem>
- <para>
- uses the algorithm to generate a new <literal>System.Guid</literal>
- described by Jimmy Nilsson in the article
- http://www.informit.com/articles/article.asp?p=25862.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>native</literal></term>
- <listitem>
- <para>
- picks <literal>identity</literal>, <literal>sequence</literal> or
- <literal>hilo</literal> depending upon the capabilities of the
- underlying database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>assigned</literal></term>
- <listitem>
- <para>
- lets the application to assign an identifier to the object before
- <literal>save()</literal> is called.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>foreign</literal></term>
- <listitem>
- <para>
- uses the identifier of another associated object. Usually used in conjunction
- with a <literal>&lt;one-to-one&gt;</literal> primary key association.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </para>
- </sect3>
-
-
- <sect3 id="mapping-declaration-id-hilo">
- <title>Hi/Lo Algorithm</title>
- <para>
- The <literal>hilo</literal> and <literal>seqhilo</literal> generators provide two alternate
- implementations of the hi/lo algorithm, a favorite approach to identifier generation. The
- first implementation requires a "special" database table to hold the next available "hi" value.
- The second uses an Oracle-style sequence (where supported).
- </para>
-
- <programlisting><![CDATA[<id name="Id" type="Int64" column="cat_id">
- <generator class="hilo">
- <param name="table">hi_value</param>
- <param name="column">next_value</param>
- <param name="max_lo">100</param>
- </generator>
-</id>]]></programlisting>
-
- <programlisting><![CDATA[<id name="Id" type="Int64" column="cat_id">
- <generator class="seqhilo">
- <param name="sequence">hi_value</param>
- <param name="max_lo">100</param>
- </generator>
-</id>]]></programlisting>
-
- <para>
- Unfortunately, you can't use <literal>hilo</literal> when supplying your own
- <literal>Connection</literal> to NHibernate. NHibernate must be able to
- fetch the "hi" value in a new transaction.
- </para>
- </sect3>
-
- <sect3 id="mapping-declaration-id-uuid-hex">
- <title>UUID Hex Algorithm</title>
-
- <programlisting><![CDATA[<id name="Id" type="String" column="cat_id">
- <generator class="uuid.hex">
- <param name="format">format_value</param>
- <param name="seperator">seperator_value</param>
- </generator>
-</id>]]></programlisting>
-
- <para>
- The UUID is generated by calling <literal>Guid.NewGuid().ToString(format)</literal>. The
- valid values for format are described in the MSDN documentation. The default
- <literal>seperator</literal> is <literal>-</literal> and should rarely be modified. The
- <literal>format</literal> determines if the configured <literal>seperator</literal> can
- replace the default seperator used by the <literal>format</literal>.
- </para>
- </sect3>
-
- <sect3 id="mapping-declaration-id-uuid-string">
- <title>UUID String Algorithm</title>
- <para>
- The UUID is generated by calling <literal>Guid.NewGuid().ToByteArray()</literal> and
- then converting the <literal>byte[]</literal> into a <literal>char[]</literal>. The
- <literal>char[]</literal> is returned as a <literal>String</literal> consisting of
- 16 characters.
- </para>
- </sect3>
-
- <sect3 id="mapping-declaration-id-guid">
- <title>GUID Algorithms</title>
- <para>
- The <literal>guid</literal> identifier is generated by calling <literal>Guid.NewGuid()</literal>.
- To address some of the performance concerns with using Guids as primary keys, foreign keys, and
- as part of indexes with MS SQL the <literal>guid.comb</literal> can be used. The benefit of using
- the <literal>guid.comb</literal> with other databases that support GUIDs has not been measured.
- </para>
- </sect3>
-
- <sect3 id="mapping-declaration-id-sequences">
- <title>Identity columns and Sequences</title>
- <para>
- For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you
- may use <literal>identity</literal> key generation. For databases that support
- sequences (DB2, Oracle, PostgreSQL) you may use
- <literal>sequence</literal> style key generation. Both these strategies usually require
- two SQL queries to insert a new object. When working with MS SQL and the
- <literal>identity</literal> key generator then <literal>select SCOPE_IDENTITY()</literal>
- will be appended to the <literal>insert</literal> sql thus avoiding the executions
- of a two distinct <literal>IDbCommand</literal>s.
- </para>
-
- <programlisting><![CDATA[<id name="Id" type="Int64" column="uid">
- <generator class="sequence">
- <param name="sequence">uid_sequence</param>
- </generator>
-</id>]]></programlisting>
-
- <programlisting><![CDATA[<id name="Id" type="Int64" column="uid" unsaved-value="0">
- <generator class="identity"/>
-</id>]]></programlisting>
-
- <para>
- For cross-platform development, the <literal>native</literal> strategy will
- choose from the <literal>identity</literal>, <literal>sequence</literal> and
- <literal>hilo</literal> strategies, dependant upon the capabilities of the
- underlying database.
- </para>
- </sect3>
-
- <sect3 id="mapping-declaration-id-assigned">
- <title>Assigned Identifiers</title>
- <para>
- If you want the application to assign identifiers (as opposed to having
- NHibernate generate them), you may use the <literal>assigned</literal> generator.
- This special generator will use the identifier value already assigned to the
- object's identifier property. Be very careful when using this feature to not assign
- keys with business meaning (almost always a terrible design decision).
- </para>
- <para>
- Due to its inherent nature, entities that use this generator cannot be saved
- via the ISession's <literal>SaveOrUpdate()</literal> method. Instead you have to
- explicitly specify to NHibernate if the object should be saved or updated
- by calling either the <literal>Save()</literal> or <literal>Update()</literal>
- method of the ISession.
- </para>
- </sect3>
+
</sect2>
- <sect2 id="mapping-declaration-compositeid">
- <title>composite-id</title>
-
- <programlisting>&lt;composite-id
- name="propertyName"<co id="composite-id1-co" linkends="composite-id1" />
- class="ClassName"<co id="composite-id2-co" linkends="composite-id2" />
- unsaved-value="any|none"<co id="composite-id3-co" linkends="composite-id3" />
- access="field|property|nosetter|ClassName"&gt;
-
- &lt;key-property name="propertyName" type="typename" column="column_name"/&gt;
- &lt;key-many-to-one name="propertyName class="ClassName" column="column_name"/&gt;
- ......
-&lt;/composite-id&gt;</programlisting>
-
- <para>
- For a table with a composite key, you may map multiple properties of the class
- as identifier properties. The <literal>&lt;composite-id&gt;</literal> element
- accepts <literal>&lt;key-property&gt;</literal> property mappings and
- <literal>&lt;key-many-to-one&gt;</literal> mappings as child elements.
- </para>
-
- <programlisting><![CDATA[<composite-id>
- <key-property name="medicareNumber"/>
- <key-property name="dependent"/>
-</composite-id>]]></programlisting>
-
- <para>
- Your persistent class <emphasis>must</emphasis> override <literal>Equals()</literal>
- and <literal>GetHashCode()</literal> to implement composite identifier equality. It must
- also be <literal>Serializable</literal>.
- </para>
-
- <para>
- Unfortunately, this approach to composite identifiers means that a persistent object
- is its own identifier. There is no convenient "handle" other than the object itself.
- You must instantiate an instance of the persistent class itself and populate its
- identifier properties before you can <literal>Load()</literal> the persistent state
- associated with a composite key. We will describe a much more
- convenient approach where the composite identifier is implemented as a seperate class
- in TODO:LINKTOCOMPENENTS<!--<xref linkend="components-compositeid"/>-->. The attributes described below apply only
- to this alternative approach:
- </para>
-
- <calloutlist>
- <callout arearefs="composite-id1-co" id="composite-id1">
- <para>
- <literal>name</literal> (optional): A property of component type that holds the
- composite identifier (see next section).
- </para>
- </callout>
- <callout arearefs="composite-id2-co" id="composite-id2">
- <para>
- <literal>class</literal> (optional - defaults to the property type determined by
- reflection): The component class used as a composite identifier (see next section).
- </para>
- </callout>
- <callout arearefs="composite-id3-co" id="composite-id3">
- <para>
- <literal>unsaved-value</literal> (optional - defaults to <literal>none</literal>):
- Indicates that transient instances should be considered newly instantiated, if set
- to <literal>any</literal>.
- </para>
- </callout>
- </calloutlist>
-
- </sect2>
-
- <sect2 id="mapping-declaration-discriminator">
- <title>discriminator</title>
-
- <para>
- The <literal>&lt;discriminator&gt;</literal> element is required for polymorphic persistence
- using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the
- table. The discriminator column contains marker values that tell the persistence layer what
- subclass to instantiate for a particular row. A restricted set of types may be used:
- <literal>String</literal>, <literal>Char</literal>, <literal>Int32</literal>,
- <literal>Byte</literal>, <literal>Int16</literal>, <literal>Boolean</literal>,
- <literal>YesNo</literal>, <literal>TrueFalse</literal>.
- </para>
-
- <programlistingco>
- <programlisting>&lt;discriminator
- column="discriminator_column"<co id="discriminator1-co" linkends="discriminator1" />
- type="discriminator_type"<co id="discriminator2-co" linkends="discriminator2" />
- force="true|false"<co id="discriminator3-co" linkends="discriminator3" />
-/&gt;</programlisting>
- <calloutlist>
- <callout arearefs="discriminator1-co" id="discriminator1">
- <para>
- <literal>column</literal> (optional - defaults to <literal>class</literal>) the
- name of the discriminator column.
- </para>
- </callout>
- <callout arearefs="discriminator2-co" id="discriminator2">
- <para>
- <literal>type</literal> (optional - defaults to <literal>String</literal>) a
- name that indicates the Hibernate type
- </para>
- </callout>
- <callout arearefs="discriminator3-co" id="discriminator3">
- <para>
- <literal>force</literal> (optional - defaults to <literal>false</literal>)
- "force" NHibernate to specify allowed discriminator values even when retrieving
- all instances of the root class.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- Actual values of the discriminator column are specified by the
- <literal>discriminator-value</literal> attribute of the <literal>&lt;class&gt;</literal> and
- <literal>&lt;subclass&gt;</literal> elements.
- </para>
-
- <para>
- The <literal>force</literal> attribute is (only) useful if the table contains rows with
- "extra" discriminator values that are not mapped to a persistent class. This will not
- usually be the case.
- </para>
- </sect2>
-
- <sect2 id="mapping-declaration-version">
- <title>version (optional)</title>
-
- <para>
- The <literal>&lt;version&gt;</literal> element is optional and indicates that
- the table contains versioned data. This is particularly useful if you plan to
- use <emphasis>long transactions</emphasis> (see below).
- </para>
-
- <programlistingco>
- <programlisting>&lt;version
- column="version_column"<co id="version1-co" linkends="version1" />
- name="propertyName"<co id="version2-co" linkends="version2" />
- type="typename"<co id="version3-co" linkends="version3" />
- access="field|property|nosetter|ClassName"<co id="version4-co" linkends="version4" />
-/&gt;</programlisting>
- <calloutlist>
- <callout arearefs="version1-co" id="version1">
- <para>
- <literal>column</literal> (optional - defaults to the property name): The name
- of the column holding the version number.
- </para>
- </callout>
- <callout arearefs="version2-co" id="version2">
- <para>
- <literal>name</literal>: The name of a property of the persistent class.
- </para>
- </callout>
- <callout arearefs="version3-co" id="version3">
- <para>
- <literal>type</literal> (optional - defaults to <literal>Int32</literal>):
- The type of the version number.
- </para>
- </callout>
- <callout arearefs="version4-co" id="version4">
- <para>
- <literal>access</literal> (optional - defaults to <literal>property</literal>): The
- strategy NHibernate should use for accessing the property value.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- Version numbers may be of type <literal>Int64</literal>, <literal>Int32</literal>,
- <literal>Int16</literal>, <literal>Ticks</literal>, <literal>Timestamp</literal>,
- or <literal>TimeSpan</literal>.
- </para>
-
- </sect2>
-
- <sect2 id="mapping-declaration-timestamp">
- <title>timestamp (optional)</title>
-
- <para>
- The optional <literal>&lt;timestamp&gt;</literal> element indicates that the table contains
- timestamped data. This is intended as an alternative to versioning. Timestamps are by nature
- a less safe implementation of optimistic locking. However, sometimes the application might
- use the timestamps in other ways.
- </para>
-
- <programlistingco>
- <programlisting>&lt;timestamp
- column="timestamp_column"<co id="timestamp1-co" linkends="timestamp1" />
- name="propertyName"<co id="timestamp2-co" linkends="timestamp2" />
- access="field|property|nosetter|ClassName"<co id="timestamp3-co" linkends="timestamp3" />
-/&gt;</programlisting>
- <calloutlist>
- <callout arearefs="timestamp1-co" id="timestamp1">
- <para>
- <literal>column</literal> (optional - defaults to the property name): The name
- of a column holding the timestamp.
- </para>
- </callout>
- <callout arearefs="timestamp2-co" id="timestamp2">
- <para>
- <literal>name</literal>: The name of a property of .NET type <literal>DateTime</literal>.
- </para>
- </callout>
- <callout arearefs="timestamp3-co" id="timestamp3">
- <para>
- <literal>access</literal> (optional - defaults to <literal>property</literal>): The
- strategy NHibernate should use for accessing the property value.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- Note that <literal>&lt;timestamp&gt;</literal> is equivalent to
- <literal>&lt;version type="timestamp"&gt;</literal>.
- </para>
- </sect2>
-
<sect2 id="mapping-declaration-property">
<title>property</title>
@@ -1062,10 +591,6 @@
</table>
</para>
</sect2>
- <!--
- TODO: resume here
- <sect2 id="mapping-declaration-manytoone">
- -->
</sect1>
<sect1 id="mapping-types">
<title>NHibernate Types</title>
@@ -1109,7 +634,6 @@
<emphasis>component</emphasis> is a user defined class with value semantics.
</para>
</sect2>
-
<sect2 id="mapping-types-basictypes">
<title>Basic value types</title>
Please sign in to comment.
Something went wrong with that request. Please try again.