HHH-9697 - Complete documentation of new approach and APIs for SessionFactory building

documentation/src/main/asciidoc/topical/bootstrap/JpaBootstrapping.adoc

@@ -2,27 +2,61 @@
 :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, which
+bootstrapping approach.  The standardized approach has some limitations in certain environments.  But aside from
-we will get into below.  But aside from those limitations, it is *highly* recommended that you use JPA-standardized
+those limitations, it is *highly* recommended that you use JPA-standardized boostrapping.
-boostrapping.
 
-NOTE: Under the covers, all of Hibernate's JPA bootstrapping makes use of its core bootstrapping.  See the
+NOTE: Under the covers, all of Hibernate's JPA bootstrapping makes use of its core bootstrapping.  Be sure to see
-_Native Bootstrapping_ guide for information.
+the _Native Bootstrapping_ guide as well.
 
 == JPA-compliant bootstrapping
 
-JPA actually defines 2 different ways to bootstrap a JPA provider.  It uses the terms "EE" and "SE" for these 2
+In JPA we are ultimately interested in bootstrapping an `javax.persistence.EntityManagerFactory` instance.  The
-approaches, but those terms are very misleading in this context.  What the JPA spec calls EE bootstrapping is cases
+JPA specification defines 2 primary standardized bootstrap approaches depending on how the application intends to
-where a container (EE, OSGi, etc) will manage and inject the persistence context on behalf of the application.  What
+access the `javax.persistence.EntityManager` instances from an `EntityManagerFactory`. It uses the terms "EE" and
-it calls SE bootstrapping is everything else.  We will use the terms managed and non-managed in this guide.
+"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.
 
-=== Managed bootstrapping
+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.
 
-=== Non-managed bootstrapping
+
+=== 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...
-* times when the spec defined bootstrapping is not enough (wildfly)
-* runtime enhancement