HHH-11116 - Improve the JPA bootstrapping section in the User Guide

(cherry picked from commit 2b30cab)
hibernate · Sep 24, 2016 · d58f6d4 · d58f6d4
1 parent 45ea61b
commit d58f6d4
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 65 deletions.
diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc
@@ -1,6 +1,7 @@
 [[bootstrap]]
 == Bootstrap
 :sourcedir: ../../../../../test/java/org/hibernate/userguide/bootstrap
+:extrasdir: extras
 
 The term bootstrapping refers to initializing and starting a software component.
 In Hibernate, we are specifically talking about the process of building a fully functional `SessionFactory` instance or `EntityManagerFactory` instance, for JPA.
@@ -18,6 +19,69 @@ Instead, we focus here on the API calls needed to perform the bootstrapping.
 During the bootstrap process, you might want to customize Hibernate behavior so make sure you check the <<appendices/Configurations.adoc#configurations,Configurations>> section as well.
 ====
 
+[[bootstrap-jpa]]
+=== JPA Bootstrapping
+
+Bootstrapping Hibernate as a JPA provider can be done in a JPA-spec compliant manner or using a proprietary bootstrapping approach.
+The standardized approach has some limitations in certain environments, but aside from those, it is *highly* recommended that you use JPA-standardized bootstrapping.
+
+[[bootstrap-jpa-compliant]]
+==== JPA-compliant bootstrapping
+
+In JPA, we are ultimately interested in bootstrapping a `javax.persistence.EntityManagerFactory` instance.
+The JPA specification defines two primary standardized bootstrap approaches depending on how the application intends to access the `javax.persistence.EntityManager` instances from an `EntityManagerFactory`.
+
+It uses the terms _EE_ and _SE_ for these two approaches, but those terms are very misleading in this context.
+What the JPA spec calls EE bootstrapping implies the existence of a container (EE, OSGi, etc), who'll manage and inject the persistence context on behalf of the application.
+What it calls SE bootstrapping is everything else. We will use the terms container-bootstrapping and application-bootstrapping in this guide.
+
+[NOTE]
+====
+If you would like additional details on accessing and using `EntityManager` instances, sections 7.6 and 7.7 of the JPA 2.1 specification cover container-managed and application-managed `EntityManagers`, respectively.
+====
+
+For compliant container-bootstrapping, the container will build an `EntityManagerFactory` for each persistent-unit defined in the `META-INF/persistence.xml` configuration file
+and make that available to the application for injection via the `javax.persistence.PersistenceUnit` annotation or via JNDI lookup.
+
+[[bootstrap-jpa-compliant-PersistenceUnit-example]]
+.Injecting a EntityManagerFactory
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-example]
+----
+====
+
+The `META-INF/persistence.xml` file looks as follows:
+
+[[bootstrap-jpa-compliant-persistence-xml-example]]
+.META-INF/persistence.xml configuration file
+====
+[source, JAVA, indent=0]
+----
+include::{extrasdir}/persistence.xml[]
+----
+====
+
+For compliant application-bootstrapping, rather than the container building the `EntityManagerFactory` for the application, the application builds the `EntityManagerFactory` itself using the `javax.persistence.Persistence` bootstrap class.
+The application creates an `EntityManagerFactory` by calling the `createEntityManagerFactory` method:
+
+[[bootstrap-jpa-compliant-EntityManagerFactory-example]]
+.Application bootstrapped EntityManagerFactory
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManagerFactory-example]
+----
+====
+
+[NOTE]
+====
+If you don't want to provide a `persistence.xml` configuration file, JPA allows you to provide all the configuration options in a
+http://docs.oracle.com/javaee/7/api/javax/persistence/spi/PersistenceUnitInfo.html[PersistenceUnitInfo] implementation and call
+https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/HibernatePersistenceProvider.html#createContainerEntityManagerFactory-javax.persistence.spi.PersistenceUnitInfo-java.util.Map-[HibernatePersistenceProvider.html#createContainerEntityManagerFactory].
+====
+
 [[bootstrap-native]]
 === Native Bootstrapping
 
@@ -176,68 +240,4 @@ The bootstrapping API is quite flexible, but in most cases it makes the most sen
 ----
 include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-SessionFactoryBuilder-example]
 ----
-====
-
-[[bootstrap-jpa]]
-=== JPA Bootstrapping
-
-Bootstrapping Hibernate as a JPA provider can be done in a JPA-spec compliant manner or using a proprietary bootstrapping approach.
-The standardized approach has some limitations in certain environments, but aside from those, it is *highly* recommended that you use JPA-standardized bootstrapping.
-
-[[bootstrap-jpa-compliant]]
-==== JPA-compliant bootstrapping
-
-In JPA, we are ultimately interested in bootstrapping a `javax.persistence.EntityManagerFactory` instance.
-The JPA specification defines 2 primary standardized bootstrap approaches depending on how the application intends to access the `javax.persistence.EntityManager` instances from an `EntityManagerFactory`.
-It uses the terms _EE_ and _SE_ for these two approaches, but those terms are very misleading in this context.
-What the JPA spec calls EE bootstrapping implies the existence of a container (EE, OSGi, etc), who'll manage and inject the persistence context on behalf of the application.
-What it calls SE bootstrapping is everything else. We will use the terms container-bootstrapping and application-bootstrapping in this guide.
-
-If you would like additional details on accessing and using `EntityManager` instances, sections 7.6 and 7.7 of the JPA 2.1 specification cover container-managed and application-managed `EntityManagers`, respectively.
-
-For compliant container-bootstrapping, the container will build an `EntityManagerFactory` for each persistent-unit defined in the `META-INF/persistence.xml` configuration file
-and make that available to the application for injection via the `javax.persistence.PersistenceUnit` annotation or via JNDI lookup.
-
-[[bootstrap-jpa-compliant-PersistenceUnit-example]]
-.Injecting a EntityManagerFactory
-====
-[source, JAVA, indent=0]
-----
-include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-example]
-----
-====
-
-For compliant application-bootstrapping, rather than the container building the `EntityManagerFactory` for the application, the application builds the `EntityManagerFactory` itself using the `javax.persistence.Persistence` bootstrap class.
-The application creates an `EntityManagerFactory` by calling the `createEntityManagerFactory` method:
-
-[[bootstrap-jpa-compliant-EntityManagerFactory-example]]
-.Application bootstrapped EntityManagerFactory
-====
-[source, JAVA, indent=0]
-----
-include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManagerFactory-example]
-----
-====
-
-[[bootstrap-jpa-hibernate]]
-==== Proprietary JPA bootstrapping
-
-Hibernate defines a proprietary https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.html[`EntityManagerFactoryBuilderImpl`]
-utility, which allows bootstrapping the JPA environment without even in the absence of the `persistence.xml` configuration file.
-To substitute the `persistence.xml` file, Hibernate offers the `PersistenceUnitInfoDescriptor` utility, which can take configuration that's available in the standard XML configuration file.
-
-[[bootstrap-native-EntityManagerFactory-example]]
-.Proprietary bootstrapped `EntityManagerFactory`
-====
-[source, JAVA, indent=0]
-----
-include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-PersistenceUnitInfoImpl-example]
-----
-
-[source, JAVA, indent=0]
-----
-include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-EntityManagerFactory-example]
-----
-====
-
-The `integrationSettings` allows the application developer to customize the bootstrapping process by specifying different `hibernate.integrator_provider` or `hibernate.strategy_registration_provider` integration providers.
+====
diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence.xml b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence.xml
@@ -0,0 +1,38 @@
+<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
+             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
+             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
+             version="2.1">
+
+    <persistence-unit name="CRM">
+        <description>
+            Persistence unit for Hibernate User Guide
+        </description>
+
+        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
+
+        <class>org.hibernate.documentation.userguide.Document</class>
+
+        <properties>
+            <property name="javax.persistence.jdbc.driver"
+                      value="org.h2.Driver" />
+
+            <property name="javax.persistence.jdbc.url"
+                      value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE" />
+
+            <property name="javax.persistence.jdbc.user"
+                      value="sa" />
+
+            <property name="javax.persistence.jdbc.password"
+                      value="" />
+
+            <property name="hibernate.show_sql"
+                      value="true" />
+
+            <property name="hibernate.hbm2ddl.auto"
+                      value="update" />
+        </properties>
+
+    </persistence-unit>
+
+</persistence>