From 3b9b2eaa913394bee02e446c086353b9cd613846 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Thu, 26 Mar 2015 12:28:29 -0500 Subject: [PATCH] HHH-9668 - Document new SessionFactory approach and APIs --- .../bootstrap/LegacyBootstrapping.adoc | 54 +++++++++++++++++-- .../bootstrap/NativeBootstrapping.adoc | 2 +- .../org/hibernate/boot/MetadataSources.java | 15 ++++++ 3 files changed, 66 insertions(+), 5 deletions(-) diff --git a/documentation/src/main/asciidoc/topical/bootstrap/LegacyBootstrapping.adoc b/documentation/src/main/asciidoc/topical/bootstrap/LegacyBootstrapping.adoc index 76c890e7a2..8102820bb2 100644 --- a/documentation/src/main/asciidoc/topical/bootstrap/LegacyBootstrapping.adoc +++ b/documentation/src/main/asciidoc/topical/bootstrap/LegacyBootstrapping.adoc @@ -3,9 +3,55 @@ The legacy way to bootstrap a `SessionFactory` is via the `org.hibernate.cfg.Configuration` object. `Configuration` represents, essentially, a single point for specifying all aspects of building -the `SessionFactory`: everything from settings, to mappings, to strategies, etc. +the `SessionFactory`: everything from settings, to mappings, to strategies, etc. I like to think of +`Configuration` as a big pot to which we add a bunch of stuff (mappings, settings, etc) and from which +we eventually get a `SessionFactory`. -However there is a huge draw back to this approach which led to the development of the new -approach discussed below. +NOTE: There are some significant draw backs to this approach which led to its deprecation and the development +of the new approach, which is discussed in the _Native Bootstrapping_ guide. `Configuration` is deprecated but +still available for use, in a limited form that eliminates these draw backs. -todo : discuss the timing issues \ No newline at end of file +You can obtain the `Configuration` by instantiating it directly. You then specify mapping metadata (XML +mapping documents, annotated classes) that describe your applications object model and its mapping to a +SQL database. + +If XML mapping files are in the classpath, use addResource(). For example: + +==== +[source, JAVA] +---- +Configuration cfg = new Configuration() + // addResource does a classpath resource lookup + .addResource("Item.hbm.xml") + .addResource("Bid.hbm.xml") + + // calls addResource using "/org/hibernate/auction/User.hbm.xml" + .addClass(org.hibernate.auction.User.class) + + // parses Address class for mapping annotations + .addAnnotatedClass( Address.class ) + + // reads package-level (package-info.class) annotations in the named package + .addPackage( "org.hibernate.auction" ) +---- +==== + +`Configuration` also allows you to specify configuration properties. For example: + +==== +[source, JAVA] +---- +Configuration cfg = new Configuration() + .setProperty("hibernate.dialect", "org.hibernate.dialect.H2Dialect") + .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test") + .setProperty("hibernate.order_updates", "true"); +---- +==== + +This is not the only way to pass configuration properties to Hibernate. Some alternative options include: + +* Pass an instance of java.util.Properties to Configuration.setProperties(). +* Place a file named hibernate.properties in a root directory of the classpath. +* Set System properties using java -Dproperty=value. +* Include elements in hibernate.cfg.xml (this is discussed later). +* If you want to get started quicklyhibernate.properties is the easiest approach. \ No newline at end of file diff --git a/documentation/src/main/asciidoc/topical/bootstrap/NativeBootstrapping.adoc b/documentation/src/main/asciidoc/topical/bootstrap/NativeBootstrapping.adoc index c2d127ac3b..1d20620c61 100644 --- a/documentation/src/main/asciidoc/topical/bootstrap/NativeBootstrapping.adoc +++ b/documentation/src/main/asciidoc/topical/bootstrap/NativeBootstrapping.adoc @@ -8,7 +8,7 @@ holding the services Hibernate will need at bootstrap- and run-time. The second a Metadata object representing the mapping information for the application's model and its mapping to the database. -NOTE : Prior to version 5.0 applications bootstrapped a `SessionFactory` is via the +NOTE: Prior to version 5.0 applications bootstrapped a `SessionFactory` is via the `org.hibernate.cfg.Configuration` object. That approach is still supported in a slightly limited manner. See the _Legacy Bootstrapping_ guide for details. diff --git a/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java b/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java index d775d8e7b1..82e3abe205 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java @@ -200,10 +200,25 @@ public class MetadataSources implements Serializable { if ( packageName == null ) { throw new IllegalArgumentException( "The specified package name cannot be null" ); } + if ( packageName.endsWith( "." ) ) { packageName = packageName.substring( 0, packageName.length() - 1 ); } + annotatedPackages.add( packageName ); + + return this; + } + + /** + * Read package-level metadata. + * + * @param packageRef Java Package reference + * + * @return this (for method chaining) + */ + public MetadataSources addPackage(Package packageRef) { + annotatedPackages.add( packageRef.getName() ); return this; }