= Bootstrapping Hibernate JPA
:toc:

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 limitations, it is *highly* recommended that you use JPA-standardized bootstrapping.

NOTE: Under the covers, all of Hibernate's JPA bootstrapping makes use of its core bootstrapping.  Be sure to see
the _Native Bootstrapping_ guide as well.

== JPA-compliant bootstrapping

In JPA we are ultimately interested in bootstrapping an `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 2 approaches, but those terms are very misleading in this context.  What the JPA spec calls EE
bootstrapping is cases where a container (EE, OSGi, etc) will 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.


=== Container-bootstrapping

The container will build an `EntityManagerFactory` for each persistent-unit defined in the deployment's
`META-INF/persistence.xml` and make that available to the application for injection via the
`javax.persistence.PersistenceUnit` annotation or via JNDI lookup.

[[container-bootstrap-injection-example]]
.Injecting a EntityManagerFactory
====
[source, JAVA]
----
@PersistenceUnit
EntityManagerFactory emf;
----
====


=== Application-bootstrapping

Rather than something a container building the `EntityManagerFactory` for the application, the application
can build the `EntityManagerFactory` using the `javax.persistence.Persistence` bootstrap class.  The application
creates an entity manager factory by calling the createEntityManagerFactory method:

[[application-bootstrap-example]]
.Application bootstrapped EntityManagerFactory
====
[source, JAVA]
----
// Create an EMF for our CRM persistence-unit.
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CRM");
----
====


== Proprietary 2-phase bootstrapping

todo: document EntityManagerFactoryBuilder...