HHH-11116 - Improve the JPA bootstrapping section in the User Guide
(cherry picked from commit 2b30cabf2f)
This commit is contained in:
Vlad Mihalcea
Gail Badner
parent
779331a9a5
commit
a2c5025382
|
|
@ -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.
|
||||
====
|
||||
|
|
@ -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>
|
||||
Loading…
Reference in New Issue