Skip to content

Commit c9dd544

Browse files
oskarboskarb
committed
NH-3085 Add reference documentation for enhanced id generators (from Hibernate).
1 parent 47600f1 commit c9dd544

File tree

1 file changed

+203
-0
lines changed

1 file changed

+203
-0
lines changed

‎doc/reference/modules/basic_mapping.xml

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -770,6 +770,209 @@
770770
</para>
771771
</sect3>
772772

773+
<sect3 id="mapping-declaration-id-enhanced">
774+
<title>Enhanced identifier generators</title>
775+
776+
<para>Starting with NHibernate release 3.3.0, there are 2 new generators which
777+
represent a re-thinking of 2 different aspects of identifier
778+
generation. The first aspect is database portability; the second is
779+
optimization Optimization means that you do not have to query the
780+
database for every request for a new identifier value. These two new
781+
generators are intended to take the place of some of the named
782+
generators described above, starting in 3.3.x. However, they are
783+
included in the current releases and can be referenced by FQN.</para>
784+
785+
<para>The first of these new generators is
786+
<literal>NHibernate.Id.Enhanced.SequenceStyleGenerator</literal>
787+
(short name <literal>enhanced-sequence</literal>)
788+
which is intended, firstly, as a replacement for the
789+
<literal>sequence</literal> generator and, secondly, as a better
790+
portability generator than <literal>native</literal>. This is because
791+
<literal>native</literal> generally chooses between
792+
<literal>identity</literal> and <literal>sequence</literal> which have
793+
largely different semantics that can cause subtle issues in
794+
applications eyeing portability.
795+
<literal>NHibernate.Id.Enhanced.SequenceStyleGenerator</literal>,
796+
however, achieves portability in a different manner. It chooses
797+
between a table or a sequence in the database to store its
798+
incrementing values, depending on the capabilities of the dialect
799+
being used. The difference between this and <literal>native</literal>
800+
is that table-based and sequence-based storage have the same exact
801+
semantic. In fact, sequences are exactly what NHibernate tries to
802+
emulate with its table-based generators. This generator has a number
803+
of configuration parameters: <itemizedlist spacing="compact">
804+
<listitem>
805+
<para><literal>sequence_name</literal> (optional, defaults to
806+
<literal>hibernate_sequence</literal>): the name of the sequence
807+
or table to be used.</para>
808+
</listitem>
809+
810+
<listitem>
811+
<para><literal>initial_value</literal> (optional, defaults to
812+
<literal>1</literal>): the initial value to be retrieved from
813+
the sequence/table. In sequence creation terms, this is
814+
analogous to the clause typically named "STARTS WITH".</para>
815+
</listitem>
816+
817+
<listitem>
818+
<para><literal>increment_size</literal> (optional - defaults to
819+
<literal>1</literal>): the value by which subsequent calls to
820+
the sequence/table should differ. In sequence creation terms,
821+
this is analogous to the clause typically named "INCREMENT
822+
BY".</para>
823+
</listitem>
824+
825+
<listitem>
826+
<para><literal>force_table_use</literal> (optional - defaults to
827+
<literal>false</literal>): should we force the use of a table as
828+
the backing structure even though the dialect might support
829+
sequence?</para>
830+
</listitem>
831+
832+
<listitem>
833+
<para><literal>value_column</literal> (optional - defaults to
834+
<literal>next_val</literal>): only relevant for table
835+
structures, it is the name of the column on the table which is
836+
used to hold the value.</para>
837+
</listitem>
838+
839+
<listitem>
840+
<para><literal>prefer_sequence_per_entity</literal> (optional -
841+
defaults to <literal>false</literal>): should we create
842+
separate sequence for each entity that share current generator
843+
based on its name?</para>
844+
</listitem>
845+
846+
<listitem>
847+
<para><literal>sequence_per_entity_suffix</literal> (optional -
848+
defaults to <literal>_SEQ</literal>): suffix added to the name
849+
of a dedicated sequence.</para>
850+
</listitem>
851+
852+
<listitem>
853+
<para><literal>optimizer</literal> (optional - defaults to
854+
<literal>none</literal>): See <xref
855+
linkend="mapping-declaration-id-enhanced-optimizers" /></para>
856+
</listitem>
857+
</itemizedlist></para>
858+
859+
<para>The second of these new generators is
860+
<literal>NHibernate.Id.Enhanced.TableGenerator</literal> (short name <literal>enhanced-table</literal>), which is
861+
intended, firstly, as a replacement for the <literal>table</literal>
862+
generator, even though it actually functions much more like
863+
<literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal> (not available in NHibernate), and
864+
secondly, as a re-implementation of
865+
<literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal> (not available in NHibernate) that
866+
utilizes the notion of pluggable optimizers. Essentially this
867+
generator defines a table capable of holding a number of different
868+
increment values simultaneously by using multiple distinctly keyed
869+
rows. This generator has a number of configuration parameters:
870+
<itemizedlist spacing="compact">
871+
<listitem>
872+
<para><literal>table_name</literal> (optional - defaults to
873+
<literal>hibernate_sequences</literal>): the name of the table
874+
to be used.</para>
875+
</listitem>
876+
877+
<listitem>
878+
<para><literal>value_column_name</literal> (optional - defaults
879+
to <literal>next_val</literal>): the name of the column on the
880+
table that is used to hold the value.</para>
881+
</listitem>
882+
883+
<listitem>
884+
<para><literal>segment_column_name</literal> (optional -
885+
defaults to <literal>sequence_name</literal>): the name of the
886+
column on the table that is used to hold the "segment key". This
887+
is the value which identifies which increment value to
888+
use.</para>
889+
</listitem>
890+
891+
<listitem>
892+
<para><literal>segment_value</literal> (optional - defaults to
893+
<literal>default</literal>): The "segment key" value for the
894+
segment from which we want to pull increment values for this
895+
generator.</para>
896+
</listitem>
897+
898+
<listitem>
899+
<para><literal>segment_value_length</literal> (optional -
900+
defaults to <literal>255</literal>): Used for schema generation;
901+
the column size to create this segment key column.</para>
902+
</listitem>
903+
904+
<listitem>
905+
<para><literal>initial_value</literal> (optional - defaults to
906+
<literal>1</literal>): The initial value to be retrieved from
907+
the table.</para>
908+
</listitem>
909+
910+
<listitem>
911+
<para><literal>increment_size</literal> (optional - defaults to
912+
<literal>1</literal>): The value by which subsequent calls to
913+
the table should differ.</para>
914+
</listitem>
915+
916+
<listitem>
917+
<para><literal>optimizer</literal> (optional - defaults to
918+
<literal>??</literal>): See <xref
919+
linkend="mapping-declaration-id-enhanced-optimizers" />.</para>
920+
</listitem>
921+
</itemizedlist></para>
922+
923+
<sect4 id="mapping-declaration-id-enhanced-optimizers">
924+
<title>Identifier generator optimization</title>
925+
926+
<para>For identifier generators that store values in the database,
927+
it is inefficient for them to hit the database on each and every
928+
call to generate a new identifier value. Instead, you can group a
929+
bunch of them in memory and only hit the database when you have
930+
exhausted your in-memory value group. This is the role of the
931+
pluggable optimizers. Currently only the two enhanced generators
932+
(<xref linkend="mapping-declaration-id-enhanced" /> support this
933+
operation.</para>
934+
935+
<itemizedlist spacing="compact">
936+
<listitem>
937+
<para><literal>none</literal> (generally this is the default if
938+
no optimizer was specified): this will not perform any
939+
optimizations and hit the database for each and every
940+
request.</para>
941+
</listitem>
942+
943+
<listitem>
944+
<para><literal>hilo</literal>: applies a hi/lo algorithm around
945+
the database retrieved values. The values from the database for
946+
this optimizer are expected to be sequential. The values
947+
retrieved from the database structure for this optimizer
948+
indicates the "group number". The
949+
<literal>increment_size</literal> is multiplied by that value in
950+
memory to define a group "hi value".</para>
951+
</listitem>
952+
953+
<listitem>
954+
<para><literal>pooled</literal>: as with the case of
955+
<literal>hilo</literal>, this optimizer attempts to minimize the
956+
number of hits to the database. Here, however, we simply store
957+
the starting value for the "next group" into the database
958+
structure rather than a sequential value in combination with an
959+
in-memory grouping algorithm. Here,
960+
<literal>increment_size</literal> refers to the values coming
961+
from the database.</para>
962+
</listitem>
963+
964+
<listitem>
965+
<para><literal>pooled-lo</literal>: similar to
966+
<literal>pooled</literal>, except that it's the starting value of
967+
the "current group" that is stored into the database structure.
968+
Here,
969+
<literal>increment_size</literal> refers to the values coming
970+
from the database.</para>
971+
</listitem>
972+
</itemizedlist>
973+
</sect4>
974+
</sect3>
975+
773976
</sect2>
774977

775978
<sect2 id="mapping-declaration-compositeid">

0 commit comments

Comments
 (0)