From 4f129fb9ec53a9bc3f698e2847e2011d048a6c68 Mon Sep 17 00:00:00 2001 From: Gail Badner Date: Wed, 28 Jan 2015 02:23:47 -0800 Subject: [PATCH] HHH-9468 : Add documentation about enabling NamingStrategyDelegator implementations (cherry picked from commit f07181e079629042ae42a6ffa7e40b4f060a2920) --- .../devguide/en-US/Database_Access.xml | 48 +++++++++++++ .../manual/en-US/content/configuration.xml | 67 +++++++++++++++---- .../manual/en-US/content/toolset_guide.xml | 36 +++++++++- 3 files changed, 134 insertions(+), 17 deletions(-) diff --git a/documentation/src/main/docbook/devguide/en-US/Database_Access.xml b/documentation/src/main/docbook/devguide/en-US/Database_Access.xml index 3cf41c064d..036c827403 100644 --- a/documentation/src/main/docbook/devguide/en-US/Database_Access.xml +++ b/documentation/src/main/docbook/devguide/en-US/Database_Access.xml @@ -882,6 +882,10 @@ --naming=eg.MyNamingStrategy select a NamingStrategy + + --namingdelegator=eg.MyNamingStrategyDelegator + select a NamingStrategyDelegator + --config=hibernate.cfg.xml read Hibernate configuration from an XML file @@ -901,6 +905,50 @@ + + + The options, and , should not be used together. + + + + When annotations or JPA XML descriptors are used to map an entity, the + org.hibernate.cfg.NamingStrategy 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, org.hibernate.cfg.NamingStrategy has + been deprecated. + + + org.hibernate.cfg.naming.NamingStrategyDelegator, + is a temporary replacement intended to provide more flexibility in a more-or-less compatible way. + + + For backward compatibility, the default implementation, + org.hibernate.cfg.naming.LegacyNamingStrategyDelegator delegates table and + column name generation to an instance of the class specified by the , if provided; + otherwise, it delegates to an instance of org.hibernate.cfg.EJB3NamingStrategy. + + + Hibernate provides org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator 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. + + + The option, , can be set to + org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator or the name of a + custom implementation of org.hibernate.cfg.naming.NamingStrategyDelegator. + + + See source code or JavaDoc for org.hibernate.cfg.naming.NamingStrategyDelegator + and its implementations for details. + + + A more comprehensive solution will be introduced in 5.0 that will replace both + org.hibernate.cfg.NamingStrategy and + org.hibernate.cfg.naming.NamingStrategyDelegator. + Embedding SchemaExport into your application diff --git a/documentation/src/main/docbook/manual/en-US/content/configuration.xml b/documentation/src/main/docbook/manual/en-US/content/configuration.xml index 681235d400..7be664059f 100644 --- a/documentation/src/main/docbook/manual/en-US/content/configuration.xml +++ b/documentation/src/main/docbook/manual/en-US/content/configuration.xml @@ -1509,11 +1509,12 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect hibernate.show_sql enabled. -
- Implementing a <literal>NamingStrategy</literal> +
+ Implementing a Naming Strategy - The interface org.hibernate.cfg.NamingStrategy - allows you to specify a "naming standard" for database objects and schema + The interfaces, org.hibernate.cfg.NamingStrategy + and org.hibernate.cfg.naming.NamingStrategyDelegator, + allow you to specify a "naming standard" for database objects and schema elements. You can provide rules for automatically generating database @@ -1523,19 +1524,57 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect eliminating repetitive noise (TBL_ prefixes, for example). The default strategy used by Hibernate is quite minimal. - You can specify a different strategy by calling - Configuration.setNamingStrategy() before adding - mappings: + When annotations or JPA XML descriptors are used to map an entity, the + org.hibernate.cfg.NamingStrategy 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, + org.hibernate.cfg.NamingStrategy has + been deprecated. + + org.hibernate.cfg.naming.NamingStrategyDelegator, + is a temporary replacement intended to provide more flexibility in a more-or-less + compatible way. + + For backward compatibility, the default implementation, + org.hibernate.cfg.naming.LegacyNamingStrategyDelegator + delegates table and column name generation to an instance + of org.hibernate.cfg.EJB3NamingStrategy. + You can specify a different org.hibernate.cfg.NamingStrategy + by calling Configuration.setNamingStrategy() before adding mappings: + + SessionFactory sf = new Configuration() + .setNamingStrategy(ImprovedNamingStrategy.INSTANCE) + .addFile("Item.hbm.xml") + .addFile("Bid.hbm.xml") + .buildSessionFactory(); + + org.hibernate.cfg.ImprovedNamingStrategy is a + built-in strategy that might be a useful starting point for some + applications. + + Hibernate provides org.hibernate.cfg.naming.ImprovedNamingStrategyDelegator + 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 org.hibernate.cfg.naming.NamingStrategyDelegator + by calling Configuration.setNamingStrategyDelegator() before adding mappings: SessionFactory sf = new Configuration() - .setNamingStrategy(ImprovedNamingStrategy.INSTANCE) - .addFile("Item.hbm.xml") - .addFile("Bid.hbm.xml") - .buildSessionFactory(); + .setNamingStrategyDelegator(ImprovedNamingStrategyDelegator.DEFAULT_INSTANCE) + .addFile("Item.hbm.xml") + .addFile("Bid.hbm.xml") + .buildSessionFactory(); + + Configuration.setNamingStrategy() and + setNamingStrategyDelegator() should not be used together. + + A more comprehensive solution will be introduced in 5.0 that will replace both + org.hibernate.cfg.NamingStrategy and + org.hibernate.cfg.naming.NamingStrategyDelegator. - org.hibernate.cfg.ImprovedNamingStrategy is a - built-in strategy that might be a useful starting point for some - applications.
diff --git a/documentation/src/main/docbook/manual/en-US/content/toolset_guide.xml b/documentation/src/main/docbook/manual/en-US/content/toolset_guide.xml index dad90530dc..e4e97ea7e8 100644 --- a/documentation/src/main/docbook/manual/en-US/content/toolset_guide.xml +++ b/documentation/src/main/docbook/manual/en-US/content/toolset_guide.xml @@ -279,7 +279,7 @@
-
+
Running the tool @@ -329,6 +329,10 @@ --naming=eg.MyNamingStrategy select a NamingStrategy + + + --namingdelegator=eg.MyNamingStrategyDelegator + select a NamingStrategyDelegator --config=hibernate.cfg.xml @@ -350,6 +354,12 @@ + + + The options, and , should not be used together. + + + You can even embed SchemaExport in your application: @@ -447,7 +457,7 @@ new SchemaExport(cfg).create(false, true);]]>
-
+
Incremental schema updates @@ -485,6 +495,10 @@ new SchemaExport(cfg).create(false, true);]]> --naming=eg.MyNamingStrategy select a NamingStrategy + + --namingdelegator=eg.MyNamingStrategyDelegator + select a NamingStrategyDelegator + --properties=hibernate.properties read database properties from a file @@ -497,6 +511,12 @@ new SchemaExport(cfg).create(false, true);]]> + + + The options, and , should not be used together. + + + You can embed SchemaUpdate in your application: @@ -529,7 +549,7 @@ new SchemaUpdate(cfg).execute(false);]]>
-
+
Schema validation @@ -560,6 +580,10 @@ new SchemaUpdate(cfg).execute(false);]]> --naming=eg.MyNamingStrategy select a NamingStrategy + + --namingdelegator=eg.MyNamingStrategyDelegator + select a NamingStrategyDelegator + --properties=hibernate.properties read database properties from a file @@ -572,6 +596,12 @@ new SchemaUpdate(cfg).execute(false);]]> + + + The options, and , should not be used together. + + + You can embed SchemaValidator in your application: