HHH-9468 : Add documentation about enabling NamingStrategyDelegator implementations

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

@@ -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>

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

@@ -1519,11 +1519,12 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
     <literal>hibernate.show_sql</literal> enabled.</para>
   </section>
 
-  <section xml:id="configuration-namingstrategy">
+  <section xml:id="configuration-namingstrategy" revision="1">
-    <title>Implementing a <literal>NamingStrategy</literal></title>
+    <title>Implementing a Naming Strategy</title>
 
-    <para>The interface <literal>org.hibernate.cfg.NamingStrategy</literal>
+    <para>The interfaces, <interfacename>org.hibernate.cfg.NamingStrategy</interfacename>
-    allows you to specify a "naming standard" for database objects and schema
+    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
+    <para>When annotations or JPA XML descriptors are used to map an entity, the
-    <literal>Configuration.setNamingStrategy()</literal> before adding
+    <interfacename>org.hibernate.cfg.NamingStrategy</interfacename> API may
-    mappings:</para>
+    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)
+        .setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE)
-    .addFile("Item.hbm.xml")
+        .addFile("Item.hbm.xml")
-    .addFile("Bid.hbm.xml")
+        .addFile("Bid.hbm.xml")
-    .buildSessionFactory();</programlisting>
+        .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>

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

@@ -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>