Allow EntityManager caching in the JPA container

The use case is to reduce the cost of Hibernate EntityManager creation/initialization, which could be more expensive for certain applications that use Hibernate extensions to perform additional processing at EntityManager creation time.

Details from JPA 2.2 specification:

7.8 Requirements on the Container

7.8.1 Application-managed Persistence Contexts
When application-managed persistence contexts are used, the container must instantiate the entity manager factory and expose it to the application via JNDI. The container might use internal APIs to create the entity manager factory, or it might use the PersistenceProvider.createContainerEntityManagerFactory method. However, the container is required to support third-party persistence providers, and in this case the container must use the PersistenceProvider.createContainerEntityManagerFactory method to create the entity manager factory and the EntityManagerFactory.close method to destroy the entity manager factory prior to shutdown (if it has not been previously closed by the application).

7.8.2 Container Managed Persistence Contexts

The container is responsible for managing the lifecycle of container-managed persistence contexts, for injecting EntityManager references into web components and session bean and message-driven bean components, and for making EntityManager references available to direct lookups in JNDI. When operating with a third-party persistence provider, the container uses the contracts defined in section 7.9 to create and destroy container-managed persistence contexts. It is undefined whether a new entity manager instance is created for every persistence context, or whether entity manager instances are sometimes reused. Exactly how the container maintains the association between persistence context and JTA transaction is not defined. If a persistence context is already associated with a JTA transaction, the container uses that persistence context for subsequent invocations within the scope of that transaction, according to the semantics for persistence context propagation defined in section 7.6.4.

7.9 Runtime Contracts between the Container and Persistence Provider

This section describes contracts between the container and the persistence provider for the pluggability of third-party persistence providers. Containers are required to support these pluggability contracts. [87]

7.9.1 Container Responsibilities
For the management of a transaction-scoped persistence context, if there is no EntityManager already associated with the JTA transaction:

• The container creates a new entity manager by calling EntityManagerFactory.createEntityManager when the first invocation of an entity manager with PersistenceContextType.TRANSACTION occurs within the scope of a business method executing in the JTA transaction.
• After the JTA transaction has completed (either by transaction commit or rollback), the container closes the entity manager by calling EntityManager.close. [88] Note that the JTA transaction may rollback in a background thread (e.g., as a result of transaction timeout), in which case the container should arrange for the entity manager to be closed but the EntityManager.close method should not be concurrently invoked while the application is in an EntityManager invocation.

The container must throw the TransactionRequiredException if a transaction-scoped persistence context is used and the EntityManager persist, remove, merge, or refresh method is invoked when no transaction is active.

For stateful session beans with extended persistence contexts:

• The container creates an entity manager by calling EntityManagerFactory.createEntityManager when a stateful session bean is created that declares a dependency on an entity manager with PersistenceContextType.EXTENDED. (See section 7.6.3).
• The container closes the entity manager by calling EntityManager.close after the stateful session bean and all other stateful session beans that have inherited the same persistence context as the entity manager have been removed.
• When a business method of the stateful session bean is invoked, if the stateful session bean uses container managed transaction demarcation, and the entity manager is not already associated with the current JTA transaction, the container associates the entity manager with the current JTA transaction and, if the persistence context is of type SynchronizationType.SYNCHRONIZED, the container calls EntityManager.joinTransaction. If there is a different persistence context already associated with the JTA transaction, the container throws the EJBException.
• When a business method of the stateful session bean is invoked, if the stateful session bean uses bean managed transaction demarcation and a UserTransaction is begun within the method, the container associates the persistence context with the JTA transaction and, if the persistence context is of type SynchronizationType.SYNCHRONIZED, the container calls EntityManager.joinTransaction.

The container must throw the IllegalStateException if the application calls EntityManager.close on a container-managed entity manager.

[87] It is not required that these contracts be used when a third-party persistence provider is not used: the container might use these same APIs or its might use its own internal APIs.

[88] The container may choose to pool EntityManagers: it instead of creating and closing in each case, it may acquire one from its pool and call clear() on it.

This jira will specifically address transaction-scoped persistence contexts referenced in JTA transactions, as there is a known point of when they are no longer referenced and can be returned to the EntityManager cache. EntityManagers that are SynchronizationType.UNSYNCHRONIZED, will not be cached.

Persistence unit hint "wildfly.jpa.emcache", may be:

• true, per EntityManagerFactory/persistence unit) cache that is shared between multiple threads.
• false (default), no caching is performed.

Persistence unit hint "wildfly.jpa.emcache.size", may be:

• 0 (default), the cache (if enabled) is unbounded. Performance may be better than bounded but will consume more memory.
• N, where N is the bounded cache max size of EntityManager instances. Bounded cache will consume less memory but may incur more performance overhead (e.g. likely to use a contended synchronization lock).