Skip to content

Commit f3a8ba6

Browse files
gbadnergbadner
committed
HHH-9468 : Add documentation about enabling NamingStrategyDelegator implementations
1 parent f07181e commit f3a8ba6

File tree

3 files changed

+104
-74
lines changed

3 files changed

+104
-74
lines changed

‎documentation/src/main/docbook/devguide/en-US/Database_Access.xml

Lines changed: 0 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -910,45 +910,6 @@
910910
The options, <option>--naming</option> and <option>--namingdelegator</option>, should not be used together.
911911
</para>
912912
</note>
913-
<para>
914-
When annotations or JPA XML descriptors are used to map an entity, the
915-
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> API may not be
916-
flexible enough to properly generate default collection table or join column names that comply with the
917-
JPA specification. This is because the API does not provide all the necessary information
918-
(e.g., an entity's class name, along with its mapped name and primary table name) to compute the names
919-
properly. Due to this limitation, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> has
920-
been deprecated.
921-
</para>
922-
<para>
923-
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
924-
is a temporary replacement intended to provide more flexibility in a more-or-less compatible way.
925-
</para>
926-
<para>
927-
For backward compatibility, the default implementation,
928-
<classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname> delegates table and
929-
column name generation to an instance of the class specified by the <option>--naming</option>, if provided;
930-
otherwise, it delegates to an instance of <classname>org.hibernate.cfg.EJB3NamingStrategy</classname>.
931-
</para>
932-
<para>
933-
Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> as
934-
an alternative that generates default table and column names that comply with the JPA specification when
935-
annotations or JPA XML descriptors are used to map an entity; table and column names generated for entities
936-
mapped using Hibernate-specific hbm.xml are unaffected.
937-
</para>
938-
<para>
939-
The option, <option>--namingdelegator</option>, can be set to
940-
<classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> or the name of a
941-
custom implementation of <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.
942-
</para>
943-
<para>
944-
See source code or JavaDoc for <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
945-
and its implementations for details.
946-
</para>
947-
<para>
948-
A more comprehensive solution will be introduced in 5.0 that will replace both
949-
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
950-
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.
951-
</para>
952913
<example>
953914
<title>Embedding SchemaExport into your application</title>
954915
<programlisting language="Java" role="JAVA"><xi:include href="extras/embedding_SchemaExport.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>

‎documentation/src/main/docbook/manual/en-US/content/basic_mapping.xml

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -227,7 +227,7 @@ public class Flight implements Serializable {
227227

228228
<para>The constraint name is optional (generated if left undefined). The
229229
column names composing the constraint correspond to the column names as
230-
defined before the Hibernate <classname>NamingStrategy</classname> is
230+
defined before the Hibernate <interfacename>NamingStrategyDelegator</interfacename> is
231231
applied.</para>
232232

233233
<tip>
@@ -3145,9 +3145,10 @@ public class Country implements Serializable {
31453145
same entity, the column name defaulting will not work as several
31463146
embedded objects would share the same set of columns. In plain JPA, you
31473147
need to override at least one set of columns. Hibernate, however, allows
3148-
you to enhance the default naming mechanism through the
3149-
<classname>NamingStrategy</classname> interface. You can write a
3150-
strategy that prevent name clashing in such a situation.
3148+
you to enhance the default naming mechanism by configuring a
3149+
<interfacename>NamingStrategyDelegator</interfacename> or
3150+
<interfacename>NamingStrategy</interfacename> strategy. You can write a
3151+
strategy to prevent name clashing in such a situation.
31513152
<classname>DefaultComponentSafeNamingStrategy</classname> is an example
31523153
of this.</para>
31533154

‎documentation/src/main/docbook/manual/en-US/content/configuration.xml

Lines changed: 99 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -932,6 +932,44 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
932932
<entry><para>At the moment, <literal>javassist</literal> is the only supported bytecode provider.</para><para> <emphasis
933933
role="strong">e.g.</emphasis> <literal>javassist</literal></para></entry>
934934
</row>
935+
<row>
936+
<entry><literal>hibernate.ejb.naming_strategy</literal></entry>
937+
938+
<entry>
939+
<para>Chooses the <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> implementation
940+
when using Hibernate Entity Manager. <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
941+
is deprecated and this property is provided for backward-compatibity.
942+
See <xref linkend="configuration-namingstrategy" /> </para>
943+
944+
<para>This property should not be used at the same time as
945+
<literal>hibernate.ejb.naming_strategy_delegator</literal></para>
946+
</entry>
947+
</row>
948+
<row>
949+
<entry><literal>hibernate.ejb.naming_strategy_delegator</literal></entry>
950+
951+
<entry>
952+
<para>Chooses the <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
953+
implementation when using Hibernate Entity Manager.
954+
See <xref linkend="configuration-namingstrategy" /> </para>
955+
956+
<para>Hibernate provides 2 implementations</para>:
957+
958+
<para><classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname>:
959+
This is the default value. This class is deprecated and is provided for backward compatibility.</para>
960+
961+
<para><classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>:
962+
This is the preferred value and generates default table and column names that comply with the
963+
JPA specification.</para>
964+
965+
<para>A different class that implements
966+
<interfacename>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</interfacename>
967+
may be specified.</para>
968+
969+
<para>This property should not be used at the same time as
970+
<literal>hibernate.ejb.naming_strategy_delegator</literal>.</para>
971+
</entry>
972+
</row>
935973
</tbody>
936974
</tgroup>
937975
</table>
@@ -1522,9 +1560,9 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
15221560
<section xml:id="configuration-namingstrategy" revision="1">
15231561
<title>Implementing a Naming Strategy</title>
15241562

1525-
<para>The interfaces, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
1526-
and <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
1527-
allow you to specify a "naming standard" for database objects and schema
1563+
<para><interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
1564+
and <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1565+
interfaces allow you to specify a "naming standard" for database objects and schema
15281566
elements.</para>
15291567

15301568
<para>You can provide rules for automatically generating database
@@ -1544,16 +1582,61 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
15441582
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> has
15451583
been deprecated.</para>
15461584

1547-
<para><interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
1548-
is a temporary replacement intended to provide more flexibility in a more-or-less
1549-
compatible way.</para>
1585+
<important>
1586+
<para><interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1587+
is a temporary replacement for <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
1588+
that addresses limitations and provides more flexibility
1589+
in a more-or-less compatible way. A more comprehensive solution will be introduced in Hibernate 5.0
1590+
that will replace both <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
1591+
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.</para>
1592+
</important>
1593+
1594+
<para>For backward compatibility, the default
1595+
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1596+
simply delegates table and column name generation to the default
1597+
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.
1598+
This default <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1599+
has also been deprecated and should be considered "legacy" code because it has the same
1600+
limitations as <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.</para>
1601+
1602+
<para>Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>
1603+
as an alternative that generates default table and column names that comply with the
1604+
JPA specification when annotations or JPA XML descriptors are used to map an entity.
1605+
Table and column names generated for entities mapped using Hibernate Core hbm.xml
1606+
are unaffected. This implementation must be explicitly configured in order to override the
1607+
the default.</para>
1608+
1609+
<note><para>Hibernate allows an implementation of either
1610+
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename> or
1611+
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> to be configured.
1612+
Both should not be configured at the same time.</para></note>
15501613

1551-
<para>For backward compatibility, the default implementation,
1552-
<classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname>
1553-
delegates table and column name generation to an instance
1554-
of <classname>org.hibernate.cfg.EJB3NamingStrategy</classname>.
1555-
You can specify a different <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
1556-
by calling <literal>Configuration.setNamingStrategy()</literal> before adding mappings:</para>
1614+
<para>To configure Hibernate Core to use <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>,
1615+
call <literal>Configuration.setNamingStrategyDelegator()</literal> before adding mappings:</para>
1616+
1617+
<programlisting role="JAVA">SessionFactory sf = new Configuration()
1618+
.setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE)
1619+
.addFile("Item.hbm.xml")
1620+
.addFile("Bid.hbm.xml")
1621+
.buildSessionFactory();</programlisting>
1622+
1623+
<para>You can configure a custom implementation of
1624+
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1625+
by replacing <literal>ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE</literal>
1626+
with the implementation class name.</para>
1627+
1628+
<para>To configure Hibernate Entity Manager to use
1629+
<classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> or a custom
1630+
implementation, set the Hibernate configuration property <literal>hibernate.ejb.naming_strategy_delegator</literal>
1631+
to the implementation class name</para>.
1632+
1633+
<para>When using the default (legacy) implementation of
1634+
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>, Hibernate
1635+
allows you to delegate to a different <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.</para>
1636+
1637+
<para>To configure Hibernate Core to delegate to a different
1638+
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename>,
1639+
call <literal>Configuration.setNamingStrategy()</literal> before adding mappings:</para>
15571640

15581641
<programlisting role="JAVA">SessionFactory sf = new Configuration()
15591642
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
@@ -1565,25 +1648,10 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
15651648
built-in strategy that might be a useful starting point for some
15661649
applications.</para>
15671650

1568-
<para>Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>
1569-
as an alternative that generates default table and column names that comply with the
1570-
JPA specification when annotations or JPA XML descriptors are used to map an entity;
1571-
table and column names generated for entities mapped using Hibernate-specific hbm.xml
1572-
are unaffected. You can specify <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
1573-
by calling <literal>Configuration.setNamingStrategyDelegator()</literal> before adding mappings:</para>
1574-
1575-
<programlisting role="JAVA">SessionFactory sf = new Configuration()
1576-
.setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE)
1577-
.addFile("Item.hbm.xml")
1578-
.addFile("Bid.hbm.xml")
1579-
.buildSessionFactory();</programlisting>
1580-
1581-
<note><literal>Configuration.setNamingStrategy()</literal> and
1582-
<literal>setNamingStrategyDelegator()</literal> should not be used together.</note>
1583-
1584-
<para>A more comprehensive solution will be introduced in 5.0 that will replace both
1585-
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
1586-
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.</para>
1651+
<para>To configure Hibernate Entity Manager to delegate to a different
1652+
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename>,
1653+
set the Hibernate configuration property <literal>hibernate.ejb.naming_strategy</literal>
1654+
to the implementation class name.</para>
15871655

15881656
</section>
15891657

0 commit comments

Comments
 (0)