Hibernate.orgCommunity Documentation

Chapter 1. Architecture

1.1. Definitions
1.2. In container environment (eg. EJB 3)
1.2.1. Container-managed entity manager
1.2.2. Application-managed entity manager
1.2.3. Persistence context scope
1.2.4. Persistence context propagation
1.3. Java SE environments

JPA 2 is part of the Java EE 6.0 platform. Persistence in JPA is available in containers like EJB 3 or the more modern CDI (Java Context and Dependency Injection), as well as in standalone Java SE applications that execute outside of a particular container. The following programming interfaces and artifacts are available in both environments.

EntityManagerFactory

An entity manager factory provides entity manager instances, all instances are configured to connect to the same database, to use the same default settings as defined by the particular implementation, etc. You can prepare several entity manager factories to access several data stores. This interface is similar to the SessionFactory in native Hibernate.

EntityManager

The EntityManager API is used to access a database in a particular unit of work. It is used to create and remove persistent entity instances, to find entities by their primary key identity, and to query over all entities. This interface is similar to the Session in Hibernate.

Persistence context

A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle is managed by a particular entity manager. The scope of this context can either be the transaction, or an extended unit of work.

Persistence unit

The set of entity types that can be managed by a given entity manager is defined by a persistence unit. A persistence unit defines the set of all classes that are related or grouped by the application, and which must be collocated in their mapping to a single data store.

Container-managed entity manager

An Entity Manager whose lifecycle is managed by the container

Application-managed entity manager

An Entity Manager whose lifecycle is managed by the application.

JTA entity manager

Entity manager involved in a JTA transaction

Resource-local entity manager

Entity manager using a resource transaction (not a JTA transaction).

An entity manager is the API to interact with the persistence context. Two common strategies can be used: binding the persistence context to the transaction boundaries, or keeping the persistence context available across several transactions.

The most common case is to bind the persistence context scope to the current transaction scope. This is only doable when JTA transactions are used: the persistence context is associated with the JTA transaction life cycle. When an entity manager is invoked, the persistence context is also opened, if there is no persistence context associated with the current JTA transaction. Otherwise, the associated persistence context is used. The persistence context ends when the JTA transaction completes. This means that during the JTA transaction, an application will be able to work on managed entities of the same persistence context. In other words, you don't have to pass the entity manager's persistence context across your managed beans (CDI) or EJBs method calls, but simply use dependency injection or lookup whenever you need an entity manager.

You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed entity manager: the persistence context is created when an entity manager is retrieved from dependency injection or JNDI lookup , and is kept until the container closes it after the completion of the Remove stateful session bean method. This is a perfect mechanism for implementing a "long" unit of work pattern. For example, if you have to deal with multiple user interaction cycles as a single unit of work (e.g. a wizard dialog that has to be fully completed), you usually model this as a unit of work from the point of view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern.

JBoss Seam 3 is built on top of CDI and has at it's core concept the notion of conversation and unit of work. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to be committed or rollbacked. For application-managed entity manager only support the extended persistence context.

A resource-local entity manager or an entity manager created with EntityManagerFactory.createEntityManager() (application-managed) has a one-to-one relationship with a persistence context. In other situations persistence context propagation occurs.

Persistence context propagation occurs for container-managed entity managers.

In a transaction-scoped container managed entity manager (common case in a Java EE environment), the JTA transaction propagation is the same as the persistence context resource propagation. In other words, container-managed transaction-scoped entity managers retrieved within a given JTA transaction all share the same persistence context. In Hibernate terms, this means all managers share the same session.

Important: persistence context are never shared between different JTA transactions or between entity manager that do not came from the same entity manager factory. There are some noteworthy exceptions for context propagation when using extended persistence contexts:

In a Java SE environment only extended context application-managed entity managers are available. You can retrieve an entity manger using the EntityManagerFactory API. Only resource-local entity managers are available. In other words, JTA transactions and persistence context propagation are not supported in Java SE (you will have to propagate the persistence context yourself, e.g. using the thread local session pattern popular in the Hibernate community).

Extended context means that a persistence context is created when the entity manager is retrieved (using EntityManagerFactory.createEntityManager(...) ) and closed when the entity manager is closed. Many resource-local transaction share the same persistence context, in this case.