HHH-9468 : Add documentation about enabling NamingStrategyDelegator implementations

(cherry picked from commit f3a8ba6351)

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

@@ -910,45 +910,6 @@
           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>

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

@@ -227,7 +227,7 @@ public class Flight implements Serializable {
 
       <para>The constraint name is optional (generated if left undefined). The
       column names composing the constraint correspond to the column names as
-      defined before the Hibernate <classname>NamingStrategy</classname> is
+      defined before the Hibernate <interfacename>NamingStrategyDelegator</interfacename> is
       applied.</para>
 
       <tip>
@@ -3145,9 +3145,10 @@ public class Country implements Serializable {
       same entity, the column name defaulting will not work as several
       embedded objects would share the same set of columns. In plain JPA, you
       need to override at least one set of columns. Hibernate, however, allows
-      you to enhance the default naming mechanism through the
+      you to enhance the default naming mechanism by configuring a
-      <classname>NamingStrategy</classname> interface. You can write a
+      <interfacename>NamingStrategyDelegator</interfacename> or
-      strategy that prevent name clashing in such a situation.
+      <interfacename>NamingStrategy</interfacename> strategy. You can write a
+      strategy to prevent name clashing in such a situation.
       <classname>DefaultComponentSafeNamingStrategy</classname> is an example
       of this.</para>
 

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

@@ -922,6 +922,44 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
             <entry><para>At the moment, <literal>javassist</literal> is the only supported bytecode provider.</para><para> <emphasis
             role="strong">e.g.</emphasis> <literal>javassist</literal></para></entry>
           </row>
+          <row>
+            <entry><literal>hibernate.ejb.naming_strategy</literal></entry>
+
+            <entry>
+              <para>Chooses the <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> implementation
+              when using Hibernate Entity Manager. <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
+              is deprecated and this property is provided for backward-compatibity.
+              See <xref linkend="configuration-namingstrategy" /> </para>
+
+              <para>This property should not be used at the same time as
+              <literal>hibernate.ejb.naming_strategy_delegator</literal></para>
+            </entry>
+          </row>
+          <row>
+            <entry><literal>hibernate.ejb.naming_strategy_delegator</literal></entry>
+
+            <entry>
+              <para>Chooses the <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
+              implementation when using Hibernate Entity Manager.
+              See <xref linkend="configuration-namingstrategy" /> </para>
+
+              <para>Hibernate provides 2 implementations</para>:
+
+              <para><classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname>:
+              This is the default value. This class is deprecated and is provided for backward compatibility.</para>
+
+              <para><classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>:
+              This is the preferred value and generates default table and column names that comply with the
+              JPA specification.</para>
+
+              <para>A different class that implements
+              <interfacename>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</interfacename>
+              may be specified.</para>
+
+              <para>This property should not be used at the same time as
+              <literal>hibernate.ejb.naming_strategy_delegator</literal>.</para>
+            </entry>
+          </row>
         </tbody>
       </tgroup>
     </table>
@@ -1512,9 +1550,9 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
   <section xml:id="configuration-namingstrategy" revision="1">
     <title>Implementing a Naming Strategy</title>
 
-    <para>The interfaces, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
+    <para><interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
-    and <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
+    and <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
-    allow you to specify a "naming standard" for database objects and schema
+    interfaces allow you to specify a "naming standard" for database objects and schema
     elements.</para>
 
     <para>You can provide rules for automatically generating database
@@ -1534,16 +1572,61 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
     <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> has
     been deprecated.</para>
 
-    <para><interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>,
+    <important>
-    is a temporary replacement intended to provide more flexibility in a more-or-less
+    <para><interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
-    compatible way.</para>
+    is a temporary replacement for <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
+    that addresses limitations and provides more flexibility
+    in a more-or-less compatible way. A more comprehensive solution will be introduced in Hibernate 5.0
+    that will replace both <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> and
+    <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>.</para>
+    </important>
 
-    <para>For backward compatibility, the default implementation,
+    <para>For backward compatibility, the default
-    <classname>org.hibernate.cfg.naming.LegacyNamingStrategyDelegator</classname>
+    <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
-    delegates table and column name generation to an instance
+    simply delegates table and column name generation to the default
-    of <classname>org.hibernate.cfg.EJB3NamingStrategy</classname>.
+    <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.
-    You can specify a different <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
+    This default <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
-    by calling <literal>Configuration.setNamingStrategy()</literal> before adding mappings:</para>
+    has also been deprecated and should be considered "legacy" code because it has the same
+    limitations as <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.</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 Core hbm.xml
+    are unaffected. This implementation must be explicitly configured in order to override the
+    the default.</para>
+
+    <note><para>Hibernate allows an implementation of either
+    <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename> or
+    <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> to be configured.
+    Both should not be configured at the same time.</para></note>
+
+    <para>To configure Hibernate Core to use <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>,
+    call <literal>Configuration.setNamingStrategyDelegator()</literal> before adding mappings:</para>
+
+      <programlisting role="JAVA">SessionFactory sf = new Configuration()
+          .setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE)
+          .addFile("Item.hbm.xml")
+          .addFile("Bid.hbm.xml")
+          .buildSessionFactory();</programlisting>
+
+    <para>You can configure a custom implementation of
+    <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>
+    by replacing <literal>ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE</literal>
+    with the implementation class name.</para>
+
+    <para>To configure Hibernate Entity Manager to use
+    <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname> or a custom
+    implementation, set the Hibernate configuration property <literal>hibernate.ejb.naming_strategy_delegator</literal>
+    to the implementation class name</para>.
+
+    <para>When using the default (legacy) implementation of
+    <interfacename>org.hibernate.cfg.naming.NamingStrategyDelegator</interfacename>, Hibernate
+    allows you to delegate to a different <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>.</para>
+
+    <para>To configure Hibernate Core to delegate to a different
+    <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>,
+    call <literal>Configuration.setNamingStrategy()</literal> before adding mappings:</para>
 
       <programlisting role="JAVA">SessionFactory sf = new Configuration()
           .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
@@ -1555,25 +1638,10 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
           built-in strategy that might be a useful starting point for some
           applications.</para>
 
-    <para>Hibernate provides <classname>org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator</classname>
+    <para>To configure Hibernate Entity Manager to delegate to a different
-    as an alternative that generates default table and column names that comply with the
+    <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>,
-    JPA specification when annotations or JPA XML descriptors are used to map an entity;
+    set the Hibernate configuration property <literal>hibernate.ejb.naming_strategy</literal>
-    table and column names generated for entities mapped using Hibernate-specific hbm.xml
+    to the implementation class name.</para>
-    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()
-        .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>
 
   </section>