HHH-9668 - Document new SessionFactory approach and APIs

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

@@ -1,5 +1,28 @@
 = Bootstrapping Hibernate JPA
 :toc:
 
-* Spec compliant bootstrapping
-* EntityManagerFactoryBuilder
+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
+we will get into below.  But aside from those limitations, it is *highly* recommended that you use JPA-standardized
+boostrapping.
+
+NOTE: Under the covers, all of Hibernate's JPA bootstrapping makes use of its core bootstrapping.  See the
+_Native Bootstrapping_ guide for information.
+
+== JPA-compliant bootstrapping
+
+JPA actually defines 2 different ways to bootstrap a JPA provider.  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 managed and non-managed in this guide.
+
+=== Managed bootstrapping
+
+=== Non-managed bootstrapping
+
+
+== Proprietary 2-phase bootstrapping
+
+
+* times when the spec defined bootstrapping is not enough (wildfly)
+* runtime enhancement

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

@@ -9,7 +9,12 @@ we eventually get a `SessionFactory`.
 
 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.
+still available for use, in a limited form that eliminates these draw backs.  "Under the covers", Configuration
+uses the new bootstrapping code, so the things available there as also available here in terms of
+auto-discovery.
+
+
+== Usage
 
 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
@@ -48,10 +53,74 @@ Configuration cfg = new Configuration()
 ----
 ====
 
-This is not the only way to pass configuration properties to Hibernate. Some alternative options include:
+There are other ways to specify configuration properties, including:
 
-* 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 <property> elements in hibernate.cfg.xml (this is discussed later).
-* If you want to get started quicklyhibernate.properties is the easiest approach.
+* Place a file named hibernate.properties in a root directory of the classpath.
+* Pass an instance of java.util.Properties to `Configuration#setProperties`.
+* Set System properties using java `-Dproperty=value`.
+* Include `<property/>` elements in `hibernate.cfg.xml`
+
+
+== Migration
+
+Mapping Configuration methods to the corresponding methods in the new API..
+
+=== Mapping metadata
+
+`Configuration#addFile`::
+        `MetadataSources#addFile`
+`Configuration#add(XmlDocument)`::
+        No replacement.
+`Configuration#addXML`::
+        No replacement.
+`Configuration#addCacheableFile`::
+        `MetadataSources#addCacheableFile`
+`Configuration#addURL`::
+        `MetadataSources#addURL`
+`Configuration#addInputStream`::
+        `MetadataSources#addInputStream`
+`Configuration#addResource`::
+        `MetadataSources#addResource`
+`Configuration#addClass`::
+        `MetadataSources#addClass`
+`Configuration#addAnnotatedClass`::
+        `MetadataSources#addAnnotatedClass`
+`Configuration#addPackage`::
+        `MetadataSources#addPackage`
+`Configuration#addJar`::
+        `MetadataSources#addJar`
+`Configuration#addDirectory`::
+        `MetadataSources#addDirectory`
+
+`Configuration#registerTypeContributor`::
+        `MetadataBuilder#applyTypes`
+`Configuration#registerTypeOverride`::
+        `MetadataBuilder#applyBasicType`
+
+=== Settings
+
+`Configuration#setProperty`::
+        `StandardServiceRegistryBuilder#applySetting`
+`Configuration#setProperties`::
+        No replacement.
+`Configuration#addProperties`::
+        `StandardServiceRegistryBuilder#applySettings`
+`Configuration#setNamingStrategy`::
+        No replacement.  NamingStrategy split into implicit/physical strategies
+`Configuration#setImplicitNamingStrategy`::
+        `MetadataBuilder#setImplicitNamingStrategy`
+`Configuration#setPhysicalNamingStrategy`::
+        `MetadataBuilder#setPhysicalNamingStrategy`
+`Configuration#configure`::
+        `StandardServiceRegistryBuilder#configure`
+
+`Configuration#setInterceptor`::
+        `SessionFactoryBuilder#applyInterceptor`
+`Configuration#setEntityNotFoundDelegate`::
+        `SessionFactoryBuilder#applyEntityNotFoundDelegate`
+`Configuration#setSessionFactoryObserver`::
+        `SessionFactoryBuilder#addSessionFactoryObservers`
+`Configuration#setCurrentTenantIdentifierResolver`::
+        `SessionFactoryBuilder#applyCurrentTenantIdentifierResolver`
+

working-5.0-migration-guide.md

@@ -37,6 +37,23 @@ TODOs
    * etc
 
 
+Blog items
+==========
+* New bootstrapping API - better determinism, better integration
+* Java 8 Support (though still compatible with Java 6).
+* Ability to handle additional Java types for id attributes marked as `GenerationType#AUTO`.  Built-in support
+    for Number and UUID.  Expandable via new `org.hibernate.boot.model.IdGeneratorStrategyInterpreter` extension
+* Expanded support for AttributeConverters.
+    * fully supported for non-`@Enumerated` enum values
+    * applicable in conjunction with `@Nationalized` support
+    * called to handle null values
+    * settable in hbm.xml by using `type="converter:fully.qualified.AttributeConverterName"`
+    * integrated with hibernate-envers
+    * collection values, map keys
+* scanning support for non-JPA usage
+* naming strategy
+
+
 Proposals for discussion
 ========================
 * Currently there is a "post-binding" hook to allow validation of the bound model (PersistentClass,