From 50b6f9da1dec8b4402490b91114e3e007e75162c Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Thu, 16 Aug 2018 17:30:44 +0200 Subject: [PATCH] Reference documentation covers async Hibernate/JPA bootstrap options Issue: SPR-17189 --- src/docs/asciidoc/data-access.adoc | 66 ++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 904c2bf052..27f8a9c286 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -311,8 +311,8 @@ The above definition of the `dataSource` bean uses the `` tag from ==== You can also use Hibernate local transactions easily, as shown in the following -examples. In this case, you need to define a Hibernate `LocalSessionFactoryBean`, which -your application code will use to obtain Hibernate `Session` instances. +examples. In this case, you need to define a Hibernate `LocalSessionFactoryBean`, +which your application code will use to obtain Hibernate `Session` instances. The `DataSource` bean definition will be similar to the local JDBC example shown previously and thus is not shown in the following example. @@ -5116,8 +5116,8 @@ chapter will then cover the other ORM technologies, showing briefer examples the ==== As of Spring Framework 5.0, Spring requires Hibernate ORM 4.3 or later for JPA support and even Hibernate ORM 5.0+ for programming against the native Hibernate Session API. -Note that the Hibernate team does not maintain any versions prior to 5.0 anymore and -is likely to focus on 5.2+ exclusively soon. +Note that the Hibernate team does not maintain any versions prior to 5.1 anymore and +is likely to focus on 5.3+ exclusively soon. ==== @@ -5175,8 +5175,25 @@ configuration: ---- You can also access a JNDI-located `SessionFactory`, using Spring's -`JndiObjectFactoryBean` / `` to retrieve and expose it. However, that -is typically not common outside of an EJB context. +`JndiObjectFactoryBean` / `` to retrieve and expose it. +However, that is typically not common outside of an EJB context. + +[NOTE] +==== +Spring also provides a `LocalSessionFactoryBuilder` variant, seamlessly integrating +with `@Bean` style configuration and programmatic setup (no `FactoryBean` involved). + +Both `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background +bootstrapping, with Hibernate initialization running in parallel to the application +bootstrap thread on a given bootstrap executor (e.g. a `SimpleAsyncTaskExecutor`). +On `LocalSessionFactoryBean`, this is available through the "bootstrapExecutor" +property; on the programmatic `LocalSessionFactoryBuilder`, there is an overloaded +`buildSessionFactory` method which takes a bootstrap executor argument. + +As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA +`EntityManagerFactory` for standard JPA interaction next to native Hibernate access. +See <> for details. +==== [[orm-hibernate-straight]] @@ -5781,7 +5798,7 @@ This is important especially when the hosting applications rely on different JPA implementations because the JPA transformers are applied only at class loader level and thus are isolated from each other. -[[orm-jpa-multiple]] +[[orm-jpa-setup-multiple]] ===== Dealing with multiple persistence units For applications that rely on multiple persistence units locations, stored in various @@ -5825,6 +5842,30 @@ affect __all__ hosted units, or programmatically, through the `PersistenceUnitManager` is specified, one is created and used internally by `LocalContainerEntityManagerFactoryBean`. +[[orm-jpa-setup-background]] +===== Background bootstrapping + +`LocalContainerEntityManagerFactoryBean` supports background bootstrapping through +the `bootstrapExecutor` property: + +[source,xml,indent=0] +[subs="verbatim,quotes"] +---- + + + + + +---- + +The actual JPA provider bootstrapping will be handed off to the specified executor then, +running in parallel to the application bootstrap thread. The exposed `EntityManagerFactory` +proxy can be injected into other application components and is even able to respond +`EntityManagerFactoryInfo` configuration inspection. However, once the actual JPA provider +is being accessed by other components, e.g. calling `createEntityManager`, those calls +will block until the background bootstrapping has completed. In particular, when using +Spring Data JPA, make sure to set up deferred bootstrapping for its repositories as well. + [[orm-jpa-dao]] ==== Implementing DAOs based on JPA: EntityManagerFactory and EntityManager @@ -6087,6 +6128,17 @@ as well as stronger optimizations for read-only transactions. Last but not least native Hibernate setup can also be expressed through `LocalSessionFactoryBuilder`, seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involved). +[NOTE] +==== +`LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background +bootstrapping, just like the JPA `LocalContainerEntityManagerFactoryBean`. +See <> for an introduction. + +On `LocalSessionFactoryBean`, this is available through the "bootstrapExecutor" +property; on the programmatic `LocalSessionFactoryBuilder`, there is an overloaded +`buildSessionFactory` method which takes a bootstrap executor argument. +==== +