HHH-9468 : Add documentation about enabling NamingStrategyDelegator implementations

This commit is contained in:
Gail Badner 2015-01-28 02:23:47 -08:00
parent b6861d1fe8
commit f07181e079
3 changed files with 134 additions and 17 deletions

View File

@ -882,6 +882,10 @@
<entry><para>--naming=<replaceable>eg.MyNamingStrategy</replaceable></para></entry>
<entry>select a NamingStrategy</entry>
</row>
<row>
<entry><para>--namingdelegator=<replaceable>eg.MyNamingStrategyDelegator</replaceable></para></entry>
<entry>select a NamingStrategyDelegator</entry>
</row>
<row>
<entry><para>--config=<replaceable>hibernate.cfg.xml</replaceable></para></entry>
<entry>read Hibernate configuration from an XML file</entry>
@ -901,6 +905,50 @@
</tbody>
</tgroup>
</table>
<note>
<para>
The options, <option>--naming</option> and <option>--namingdelegator</option>, should not be used together.
</para>
</note>
<para>
When annotations or JPA XML descriptors are used to map an entity, the
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> API may not be
flexible enough to properly generate default collection table or join column names that comply with the
JPA specification. This is because the API does not provide all the necessary information
(e.g., an entity's class name, along with its mapped name and primary table name) to compute the names
properly. Due to this limitation, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> has
been deprecated.
</para>
<para>
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
is a temporary replacement intended to provide more flexibility in a more-or-less compatible way.
</para>
<para>
For backward compatibility, the default implementation,
<classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname> delegates table and
column name generation to an instance of the class specified by the <option>--naming</option>, if provided;
otherwise, it delegates to an instance of <classname>org.hibernate.cfg.EJB3NamingStrategy</classname>.
</para>
<para>
Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> as
an alternative that generates default table and column names that comply with the JPA specification when
annotations or JPA XML descriptors are used to map an entity; table and column names generated for entities
mapped using Hibernate-specific hbm.xml are unaffected.
</para>
<para>
The option, <option>--namingdelegator</option>, can be set to
<classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> or the name of a
custom implementation of <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.
</para>
<para>
See source code or JavaDoc for <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
and its implementations for details.
</para>
<para>
A more comprehensive solution will be introduced in 5.0 that will replace both
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.
</para>
<example>
<title>Embedding SchemaExport into your application</title>
<programlisting language="Java" role="JAVA"><xi:include href="extras/embedding_SchemaExport.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>

View File

@ -1519,11 +1519,12 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
<literal>hibernate.show_sql</literal> enabled.</para>
</section>
<section xml:id="configuration-namingstrategy">
<title>Implementing a <literal>NamingStrategy</literal></title>
<section xml:id="configuration-namingstrategy" revision="1">
<title>Implementing a Naming Strategy</title>
<para>The interface <literal>org.hibernate.cfg.NamingStrategy</literal>
allows you to specify a "naming standard" for database objects and schema
<para>The interfaces, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
and <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
allow you to specify a "naming standard" for database objects and schema
elements.</para>
<para>You can provide rules for automatically generating database
@ -1533,19 +1534,57 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
eliminating repetitive noise (<literal>TBL_</literal> prefixes, for
example). The default strategy used by Hibernate is quite minimal.</para>
<para>You can specify a different strategy by calling
<literal>Configuration.setNamingStrategy()</literal> before adding
mappings:</para>
<para>When annotations or JPA XML descriptors are used to map an entity, the
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> API may
not be flexible enough to properly generate default collection table or
join column names that comply with the JPA specification. This is because
the API does not provide all the necessary information (e.g., an entity's
class name, along with its mapped name and primary table name) to compute
the names properly. Due to this limitation,
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> has
been deprecated.</para>
<para><interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
is a temporary replacement intended to provide more flexibility in a more-or-less
compatible way.</para>
<para>For backward compatibility, the default implementation,
<classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname>
delegates table and column name generation to an instance
of <classname>org.hibernate.cfg.EJB3NamingStrategy</classname>.
You can specify a different <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
by calling <literal>Configuration.setNamingStrategy()</literal> before adding mappings:</para>
<programlisting role="JAVA">SessionFactory sf = new Configuration()
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
.buildSessionFactory();</programlisting>
<para><literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a
built-in strategy that might be a useful starting point for some
applications.</para>
<para>Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>
as an alternative that generates default table and column names that comply with the
JPA specification when annotations or JPA XML descriptors are used to map an entity;
table and column names generated for entities mapped using Hibernate-specific hbm.xml
are unaffected. You can specify <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
by calling <literal>Configuration.setNamingStrategyDelegator()</literal> before adding mappings:</para>
<programlisting role="JAVA">SessionFactory sf = new Configuration()
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
.buildSessionFactory();</programlisting>
.setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
.buildSessionFactory();</programlisting>
<note><literal>Configuration.setNamingStrategy()</literal> and
<literal>setNamingStrategyDelegator()</literal> should not be used together.</note>
<para>A more comprehensive solution will be introduced in 5.0 that will replace both
<interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
<interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.</para>
<para><literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a
built-in strategy that might be a useful starting point for some
applications.</para>
</section>
<section>

View File

@ -279,7 +279,7 @@
</section>
<section xml:id="toolsetguide-s1-3" revision="2">
<section xml:id="toolsetguide-s1-3" revision="3">
<title>Running the tool</title>
<para>
@ -329,6 +329,10 @@
<row>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>select a <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--namingdelegator=eg.MyNamingStrategyDelegator</literal></entry>
<entry>select a <literal>NamingStrategyDelegator</literal></entry>
</row>
<row>
<entry><literal>--config=hibernate.cfg.xml</literal></entry>
@ -350,6 +354,12 @@
</tgroup>
</table>
<note>
<para>
The options, <option>--naming</option> and <option>--namingdelegator</option>, should not be used together.
</para>
</note>
<para>
You can even embed <literal>SchemaExport</literal> in your application:
</para>
@ -447,7 +457,7 @@ new SchemaExport(cfg).create(false, true);]]></programlisting>
</section>
<section xml:id="toolsetguide-s1-6" revision="2">
<section xml:id="toolsetguide-s1-6" revision="3">
<title>Incremental schema updates</title>
<para>
@ -485,6 +495,10 @@ new SchemaExport(cfg).create(false, true);]]></programlisting>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>select a <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--namingdelegator=eg.MyNamingStrategyDelegator</literal></entry>
<entry>select a <literal>NamingStrategyDelegator</literal></entry>
</row>
<row>
<entry><literal>--properties=hibernate.properties</literal></entry>
<entry>read database properties from a file</entry>
@ -497,6 +511,12 @@ new SchemaExport(cfg).create(false, true);]]></programlisting>
</tgroup>
</table>
<note>
<para>
The options, <option>--naming</option> and <option>--namingdelegator</option>, should not be used together.
</para>
</note>
<para>
You can embed <literal>SchemaUpdate</literal> in your application:
</para>
@ -529,7 +549,7 @@ new SchemaUpdate(cfg).execute(false);]]></programlisting>
</section>
<section xml:id="toolsetguide-s1-8" revision="1">
<section xml:id="toolsetguide-s1-8" revision="2">
<title>Schema validation</title>
<para>
@ -560,6 +580,10 @@ new SchemaUpdate(cfg).execute(false);]]></programlisting>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>select a <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--namingdelegator=eg.MyNamingStrategyDelegator</literal></entry>
<entry>select a <literal>NamingStrategyDelegator</literal></entry>
</row>
<row>
<entry><literal>--properties=hibernate.properties</literal></entry>
<entry>read database properties from a file</entry>
@ -572,6 +596,12 @@ new SchemaUpdate(cfg).execute(false);]]></programlisting>
</tgroup>
</table>
<note>
<para>
The options, <option>--naming</option> and <option>--namingdelegator</option>, should not be used together.
</para>
</note>
<para>
You can embed <literal>SchemaValidator</literal> in your application:
</para>