Jakarta EE 11.0.0 · jakarta.persistence.EntityManagerFactory

Interface used to interact with the persistence unit, and to create new instances of EntityManager.

A persistence unit defines the set of all classes that are related or grouped by the application, and which must be colocated in their mapping to a single database. If two entity types participate in an association, then they must belong to the same persistence unit.

A persistence unit may be defined by a persistence.xml file, or it may be defined at runtime via the PersistenceConfiguration API.

Every persistence unit has a transaction type, either JTA, or RESOURCE_LOCAL. Resource-local transactions are managed programmatically via the EntityTransaction interface.

An EntityManagerFactory with a lifecycle managed by the application may be created using the static operations of the Persistence class:

if the persistence unit is defined in persistence.xml, an entity manager factory may be created by calling Persistence#createEntityManagerFactory(String) or Persistence#createEntityManagerFactory(String, Map), or
if the persistence unit was defined using PersistenceConfiguration, an entity manager factory may be created by calling Persistence#createEntityManagerFactory(PersistenceConfiguration).

Usually, there is exactly one EntityManagerFactory for each persistence unit:

// create a factory at initialization time
static final EntityManagerFactory entityManagerFactory =
        Persistence.createEntityManagerFactory("orderMgt");

Alternatively, in the Jakarta EE environment, a container-managed EntityManagerFactory may be obtained by dependency injection, using PersistenceUnit.

// inject the container-managed factory
@PersistenceUnit(unitName="orderMgt")
EntityManagerFactory entityManagerFactory;

An application-managed EntityManager may be created via a call to createEntityManager(). However, this approach places complete responsibility for cleanup and exception management on the client, and is thus considered error-prone. It is much safer to use the methods runInTransaction and callInTransaction to obtain EntityManagers. Alternatively, in the Jakarta EE environment, a container-managed EntityManager may be obtained by dependency injection, using PersistenceContext, and the application need not interact with the EntityManagerFactory directly.

The EntityManagerFactory provides access to certain other useful APIs:

an instance of Metamodel exposing a model of the managed types associated with the persistence unit may be obtained by calling getMetamodel(),
an instance of SchemaManager, allowing programmatic control over schema generation and validation, may be obtained by calling getSchemaManager(),
an instance of Cache, allowing direct programmatic control over the second-level cache, may be obtained by calling getCache(),
the CriteriaBuilder, used to define criteria queries, may be obtained by calling getCriteriaBuilder(), and
the PersistenceUnitUtil may be obtained by calling getPersistenceUnitUtil().

When the application has finished using the entity manager factory, or when the application terminates, the application should close the entity manager factory. If necessary, a java.lang.ref.Cleaner may be used:

// factory should be destroyed before program terminates
Cleaner.create().register(entityManagerFactory, entityManagerFactory::close);

Once an EntityManagerFactory has been closed, all its entity managers are considered to be in the closed state.

Method Summary

Modifier and Type	Method and Description
public <T> void	addNamedEntityGraph(String name for the entity graph graphName, EntityGraph<T> entity graph entityGraph) Add a named copy of the given `EntityGraph` to this `EntityManagerFactory`.
public void	addNamedQuery(String name for the query name, Query a `Query`, `TypedQuery`, or `StoredProcedureQuery` query) Define the query, typed query, or stored procedure query as a named query such that future query objects can be created from it using the `EntityManager#createNamedQuery` or `EntityManager#createNamedStoredProcedureQuery` methods.
public <R> R	Returns: the value returned by the given function callInTransaction(Function<EntityManager, R> a function to be called in the scope of the transaction work) Create a new application-managed `EntityManager` with an active transaction, and call the given function, passing the `EntityManager` to the function.
public void	close() Redeclares java.lang.AutoCloseable.close. Close the factory, releasing any resources that it holds.
public EntityManager	Returns: entity manager instance createEntityManager() Create a new application-managed `EntityManager`.
public EntityManager	Returns: entity manager instance createEntityManager(Map<?, ?> properties for entity manager map) Create a new application-managed `EntityManager` with the given `Map` specifying property settings.
public EntityManager	Returns: entity manager instance createEntityManager(SynchronizationType how and when the entity manager should be synchronized with the current JTA transaction synchronizationType) Create a new JTA application-managed `EntityManager` with the specified synchronization type.
public EntityManager	Returns: entity manager instance createEntityManager(SynchronizationType how and when the entity manager should be synchronized with the current JTA transaction synchronizationType, Map<?, ?> properties for entity manager map) Create a new JTA application-managed `EntityManager` with the specified synchronization type and map of properties.
public Cache	Returns: an instance of `Cache`, or null if there is no second-level cache in use getCache() Access the cache that is associated with the entity manager factory (the "second level cache").
public CriteriaBuilder	Returns: an instance of `CriteriaBuilder` getCriteriaBuilder() Return an instance of `CriteriaBuilder` which may be used to construct `jakarta.persistence.criteria.CriteriaQuery` objects.
public Metamodel	Returns: an instance of `Metamodel` getMetamodel() Return an instance of the `Metamodel` interface for access to the metamodel of the persistence unit.
public String	getName() The name of the persistence unit.
public < the specified upper bound on the entity graph types E> Map<String, EntityGraph<? extends E>>	Returns: a map keyed by graph name getNamedEntityGraphs(Class<E> any Java type, including `Object.class` meaning all entity graphs entityType) A map keyed by graph name, containing every named entity graph whose entity type is assignable to the given Java type.
public < the specified upper bound on the query result types R> Map<String, TypedQueryReference<R>>	Returns: a map keyed by query name getNamedQueries(Class<R> any Java type, including `Object.class` meaning all queries resultType) A map keyed by query name, containing references to every named query whose result type is assignable to the given Java type.
public PersistenceUnitUtil	Returns: an instance of `PersistenceUnitUtil` getPersistenceUnitUtil() Return interface providing access to utility methods for the persistence unit.
public Map<String, Object>	Returns: properties getProperties() Get the properties and associated values that are in effect for the entity manager factory.
public SchemaManager	Returns: an instance of `SchemaManager` getSchemaManager() Return interface providing access to schema management operations for the persistence unit.
public PersistenceUnitTransactionType	getTransactionType() The type of transaction management used by this persistence unit, either resource-local transaction management, or JTA.
public boolean	Returns: boolean indicating whether the factory is open isOpen() Indicates whether the factory is open.
public void	runInTransaction(Consumer<EntityManager> a function to be executed in the scope of the transaction work) Create a new application-managed `EntityManager` with an active transaction, and execute the given function, passing the `EntityManager` to the function.
public <T> T	Returns: an instance of the specified class unwrap(Class<T> the class of the object to be returned. This is usually either the underlying class implementing `EntityManagerFactory` or an interface it implements. cls) Return an object of the specified type to allow access to a provider-specific API.

Method Detail

addNamedEntityGraph back to summary

addNamedEntityGraph	back to summary
public <T> void addNamedEntityGraph(String graphName, EntityGraph<T> entityGraph) Add a named copy of the given `EntityGraph` to this `EntityManagerFactory`. If an entity graph with the given name already exists, it is replaced. Parameters graphName:String name for the entity graph entityGraph:EntityGraph<T> entity graph Since 2.1

public <T> void addNamedEntityGraph(String graphName, EntityGraph<T> entityGraph)

Add a named copy of the given EntityGraph to this EntityManagerFactory. If an entity graph with the given name already exists, it is replaced.

Parameters

graphName:String: name for the entity graph
entityGraph:EntityGraph<T>: entity graph

Since

2.1

addNamedQuery back to summary

addNamedQuery	back to summary
public void addNamedQuery(String name, Query query) Define the query, typed query, or stored procedure query as a named query such that future query objects can be created from it using the `EntityManager#createNamedQuery` or `EntityManager#createNamedStoredProcedureQuery` methods. Any configuration of the query object (except for actual parameter binding) in effect when the named query is added is retained as part of the named query definition. This includes configuration information such as max results, hints, flush mode, lock mode, result set mapping information, and information about stored procedure parameters. When the query is executed, information that can be set by means of the query APIs can be overridden. Information that is overridden does not affect the named query as registered with the entity manager factory, and thus does not affect subsequent query objects created from it by calling `createNamedQuery` or `createNamedStoredProcedureQuery`. If a named query of the same name has been previously defined, either statically via metadata or via this method, that query definition is replaced. Parameters name:String name for the query query:Query a `Query`, `TypedQuery`, or `StoredProcedureQuery` Since 2.1

public void addNamedQuery(String name, Query query)

Define the query, typed query, or stored procedure query as a named query such that future query objects can be created from it using the EntityManager#createNamedQuery or EntityManager#createNamedStoredProcedureQuery methods.

Any configuration of the query object (except for actual parameter binding) in effect when the named query is added is retained as part of the named query definition. This includes configuration information such as max results, hints, flush mode, lock mode, result set mapping information, and information about stored procedure parameters.

When the query is executed, information that can be set by means of the query APIs can be overridden. Information that is overridden does not affect the named query as registered with the entity manager factory, and thus does not affect subsequent query objects created from it by calling createNamedQuery or createNamedStoredProcedureQuery.

If a named query of the same name has been previously defined, either statically via metadata or via this method, that query definition is replaced.

Parameters

name:String: name for the query
query:Query: a Query, TypedQuery, or StoredProcedureQuery

Since

2.1

callInTransaction back to summary

callInTransaction	back to summary
public <R> R callInTransaction(Function<EntityManager, R> work) Create a new application-managed `EntityManager` with an active transaction, and call the given function, passing the `EntityManager` to the function. If the transaction type of the persistence unit is JTA, and there is a JTA transaction already associated with the caller, then the `EntityManager` is associated with this current transaction. If the given function returns without throwing an exception, the result of the function is returned. If the given function throws an exception, the JTA transaction is marked for rollback, and the exception is rethrown. Otherwise, if the transaction type of the persistence unit is resource-local, or if there is no JTA transaction already associated with the caller, then the `EntityManager` is associated with a new transaction. If the given function returns without throwing an exception, this transaction is committed and the result of the function is returned. If the function does throw an exception, the transaction is rolled back, and the exception is rethrown. Finally, the `EntityManager` is closed before this method returns control to the client. Parameters work:Function<EntityManager, R> a function to be called in the scope of the transaction Returns:R the value returned by the given function Since 3.2

public <R> R callInTransaction(Function<EntityManager, R> work)

Create a new application-managed EntityManager with an active transaction, and call the given function, passing the EntityManager to the function.

If the transaction type of the persistence unit is JTA, and there is a JTA transaction already associated with the caller, then the EntityManager is associated with this current transaction. If the given function returns without throwing an exception, the result of the function is returned. If the given function throws an exception, the JTA transaction is marked for rollback, and the exception is rethrown.

Otherwise, if the transaction type of the persistence unit is resource-local, or if there is no JTA transaction already associated with the caller, then the EntityManager is associated with a new transaction. If the given function returns without throwing an exception, this transaction is committed and the result of the function is returned. If the function does throw an exception, the transaction is rolled back, and the exception is rethrown.

Finally, the EntityManager is closed before this method returns control to the client.

Parameters

work:Function<EntityManager, R>: a function to be called in the scope of the transaction

Returns:R

the value returned by the given function

Since

3.2

close back to summary

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.close. Close the factory, releasing any resources that it holds. After a factory instance has been closed, all methods invoked on it will throw the `IllegalStateException`, except for `isOpen`, which will return false. Once an `EntityManagerFactory` has been closed, all its entity managers are considered to be in the closed state. Exceptions IllegalStateException: if the entity manager factory has been closed

public void close()

Redeclares java.lang.AutoCloseable.close.

Close the factory, releasing any resources that it holds. After a factory instance has been closed, all methods invoked on it will throw the IllegalStateException, except for isOpen, which will return false. Once an EntityManagerFactory has been closed, all its entity managers are considered to be in the closed state.

Exceptions

IllegalStateException:: if the entity manager factory has been closed

createEntityManager back to summary

createEntityManager	back to summary
public EntityManager createEntityManager() Create a new application-managed `EntityManager`. This method returns a new `EntityManager` instance each time it is invoked. The `EntityManager#isOpen` method will return true on the returned instance. Returns:EntityManager entity manager instance Exceptions IllegalStateException: if the entity manager factory has been closed

public EntityManager createEntityManager()

Create a new application-managed EntityManager. This method returns a new EntityManager instance each time it is invoked.

The EntityManager#isOpen method will return true on the returned instance.

Returns:EntityManager

entity manager instance

Exceptions

IllegalStateException:: if the entity manager factory has been closed

createEntityManager back to summary

createEntityManager	back to summary
public EntityManager createEntityManager(Map<?, ?> map) Create a new application-managed `EntityManager` with the given `Map` specifying property settings. This method returns a new `EntityManager` instance each time it is invoked. The `EntityManager#isOpen` method will return true on the returned instance. Parameters map:Map<?, ?> properties for entity manager Returns:EntityManager entity manager instance Exceptions IllegalStateException: if the entity manager factory has been closed

public EntityManager createEntityManager(Map<?, ?> map)

Create a new application-managed EntityManager with the given Map specifying property settings. This method returns a new EntityManager instance each time it is invoked.

The EntityManager#isOpen method will return true on the returned instance.

Parameters

map:Map<?, ?>: properties for entity manager

Returns:EntityManager

entity manager instance

Exceptions

IllegalStateException:: if the entity manager factory has been closed

createEntityManager back to summary

createEntityManager	back to summary
public EntityManager createEntityManager(SynchronizationType synchronizationType) Create a new JTA application-managed `EntityManager` with the specified synchronization type. This method returns a new `EntityManager` instance each time it is invoked. The `EntityManager#isOpen` method will return true on the returned instance. Parameters synchronizationType:SynchronizationType how and when the entity manager should be synchronized with the current JTA transaction Returns:EntityManager entity manager instance Exceptions IllegalStateException: if the entity manager factory has been configured for resource-local entity managers or is closed Since 2.1

public EntityManager createEntityManager(SynchronizationType synchronizationType)

Create a new JTA application-managed EntityManager with the specified synchronization type. This method returns a new EntityManager instance each time it is invoked.

The EntityManager#isOpen method will return true on the returned instance.

Parameters

synchronizationType:SynchronizationType: how and when the entity manager should be synchronized with the current JTA transaction

Returns:EntityManager

entity manager instance

Exceptions

IllegalStateException:: if the entity manager factory has been configured for resource-local entity managers or is closed

Since

2.1

createEntityManager back to summary

createEntityManager	back to summary
public EntityManager createEntityManager(SynchronizationType synchronizationType, Map<?, ?> map) Create a new JTA application-managed `EntityManager` with the specified synchronization type and map of properties. This method returns a new `EntityManager` instance each time it is invoked. The `EntityManager#isOpen` method will return true on the returned instance. Parameters synchronizationType:SynchronizationType how and when the entity manager should be synchronized with the current JTA transaction map:Map<?, ?> properties for entity manager Returns:EntityManager entity manager instance Exceptions IllegalStateException: if the entity manager factory has been configured for resource-local entity managers or is closed Since 2.1

public EntityManager createEntityManager(SynchronizationType synchronizationType, Map<?, ?> map)

Create a new JTA application-managed EntityManager with the specified synchronization type and map of properties. This method returns a new EntityManager instance each time it is invoked.

The EntityManager#isOpen method will return true on the returned instance.

Parameters

synchronizationType:SynchronizationType: how and when the entity manager should be synchronized with the current JTA transaction
map:Map<?, ?>: properties for entity manager

Returns:EntityManager

entity manager instance

Exceptions

IllegalStateException:: if the entity manager factory has been configured for resource-local entity managers or is closed

Since

2.1

getCache back to summary

getCache	back to summary
public Cache getCache() Access the cache that is associated with the entity manager factory (the "second level cache"). Returns:Cache an instance of `Cache`, or null if there is no second-level cache in use Exceptions IllegalStateException: if the entity manager factory has been closed Since 2.0

public Cache getCache()

Access the cache that is associated with the entity manager factory (the "second level cache").

Returns:Cache

an instance of Cache, or null if there is no second-level cache in use

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

2.0

getCriteriaBuilder back to summary

getCriteriaBuilder	back to summary
public CriteriaBuilder getCriteriaBuilder() Return an instance of `CriteriaBuilder` which may be used to construct `jakarta.persistence.criteria.CriteriaQuery` objects. Returns:CriteriaBuilder an instance of `CriteriaBuilder` Exceptions IllegalStateException: if the entity manager factory has been closed Since 2.0 See Also `EntityManager#getCriteriaBuilder()`

public CriteriaBuilder getCriteriaBuilder()

Return an instance of CriteriaBuilder which may be used to construct jakarta.persistence.criteria.CriteriaQuery objects.

Returns:CriteriaBuilder

an instance of CriteriaBuilder

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

2.0

See Also

EntityManager#getCriteriaBuilder()

getMetamodel back to summary

getMetamodel	back to summary
public Metamodel getMetamodel() Return an instance of the `Metamodel` interface for access to the metamodel of the persistence unit. Returns:Metamodel an instance of `Metamodel` Exceptions IllegalStateException: if the entity manager factory has been closed Since 2.0

public Metamodel getMetamodel()

Return an instance of the Metamodel interface for access to the metamodel of the persistence unit.

Returns:Metamodel

an instance of Metamodel

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

2.0

getName	back to summary
public String getName() The name of the persistence unit. Since 3.2

getName

back to summary

public String getName()

The name of the persistence unit.

Since: 3.2

getNamedEntityGraphs back to summary

getNamedEntityGraphs	back to summary
public <E> Map<String, EntityGraph<? extends E>> getNamedEntityGraphs(Class<E> entityType) A map keyed by graph name, containing every named entity graph whose entity type is assignable to the given Java type. Parameters <E> the specified upper bound on the entity graph types entityType:Class<E> any Java type, including `Object.class` meaning all entity graphs Returns:Map<String, EntityGraph<? extends E>> a map keyed by graph name Since 3.2

public <E> Map<String, EntityGraph<? extends E>> getNamedEntityGraphs(Class<E> entityType)

A map keyed by graph name, containing every named entity graph whose entity type is assignable to the given Java type.

Parameters

<E>: the specified upper bound on the entity graph types
entityType:Class<E>: any Java type, including Object.class meaning all entity graphs

Returns:Map<String, EntityGraph<? extends E>>

a map keyed by graph name

Since

3.2

getNamedQueries back to summary

getNamedQueries	back to summary
public <R> Map<String, TypedQueryReference<R>> getNamedQueries(Class<R> resultType) A map keyed by query name, containing references to every named query whose result type is assignable to the given Java type. Parameters <R> the specified upper bound on the query result types resultType:Class<R> any Java type, including `Object.class` meaning all queries Returns:Map<String, TypedQueryReference<R>> a map keyed by query name Since 3.2

public <R> Map<String, TypedQueryReference<R>> getNamedQueries(Class<R> resultType)

A map keyed by query name, containing references to every named query whose result type is assignable to the given Java type.

Parameters

<R>: the specified upper bound on the query result types
resultType:Class<R>: any Java type, including Object.class meaning all queries

Returns:Map<String, TypedQueryReference<R>>

a map keyed by query name

Since

3.2

getPersistenceUnitUtil back to summary

getPersistenceUnitUtil	back to summary
public PersistenceUnitUtil getPersistenceUnitUtil() Return interface providing access to utility methods for the persistence unit. Returns:PersistenceUnitUtil an instance of `PersistenceUnitUtil` Exceptions IllegalStateException: if the entity manager factory has been closed Since 2.0

public PersistenceUnitUtil getPersistenceUnitUtil()

Return interface providing access to utility methods for the persistence unit.

Returns:PersistenceUnitUtil

an instance of PersistenceUnitUtil

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

2.0

getProperties	back to summary
public Map<String, Object> getProperties() Get the properties and associated values that are in effect for the entity manager factory. Changing the contents of the map does not change the configuration in effect. Returns:Map<String, Object> properties Exceptions IllegalStateException: if the entity manager factory has been closed Since 2.0

getProperties

back to summary

public Map<String, Object> getProperties()

Get the properties and associated values that are in effect for the entity manager factory. Changing the contents of the map does not change the configuration in effect.

Returns:Map<String, Object>

properties

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

2.0

getSchemaManager back to summary

getSchemaManager	back to summary
public SchemaManager getSchemaManager() Return interface providing access to schema management operations for the persistence unit. Returns:SchemaManager an instance of `SchemaManager` Exceptions IllegalStateException: if the entity manager factory has been closed Since 3.2

public SchemaManager getSchemaManager()

Return interface providing access to schema management operations for the persistence unit.

Returns:SchemaManager

an instance of SchemaManager

Exceptions

IllegalStateException:: if the entity manager factory has been closed

Since

3.2

getTransactionType	back to summary
public PersistenceUnitTransactionType getTransactionType() The type of transaction management used by this persistence unit, either resource-local transaction management, or JTA. Since 3.2

getTransactionType

back to summary

public PersistenceUnitTransactionType getTransactionType()

The type of transaction management used by this persistence unit, either resource-local transaction management, or JTA.

Since: 3.2

isOpen	back to summary
public boolean isOpen() Indicates whether the factory is open. Returns true until the factory has been closed. Returns:boolean boolean indicating whether the factory is open

isOpen

back to summary

public boolean isOpen()

Indicates whether the factory is open. Returns true until the factory has been closed.

Returns:boolean: boolean indicating whether the factory is open

runInTransaction back to summary

runInTransaction	back to summary
public void runInTransaction(Consumer<EntityManager> work) Create a new application-managed `EntityManager` with an active transaction, and execute the given function, passing the `EntityManager` to the function. If the transaction type of the persistence unit is JTA, and there is a JTA transaction already associated with the caller, then the `EntityManager` is associated with this current transaction. If the given function throws an exception, the JTA transaction is marked for rollback, and the exception is rethrown. Otherwise, if the transaction type of the persistence unit is resource-local, or if there is no JTA transaction already associated with the caller, then the `EntityManager` is associated with a new transaction. If the given function returns without throwing an exception, this transaction is committed. If the function does throw an exception, the transaction is rolled back, and the exception is rethrown. Finally, the `EntityManager` is closed before this method returns control to the client. Parameters work:Consumer<EntityManager> a function to be executed in the scope of the transaction Since 3.2

public void runInTransaction(Consumer<EntityManager> work)

Create a new application-managed EntityManager with an active transaction, and execute the given function, passing the EntityManager to the function.

If the transaction type of the persistence unit is JTA, and there is a JTA transaction already associated with the caller, then the EntityManager is associated with this current transaction. If the given function throws an exception, the JTA transaction is marked for rollback, and the exception is rethrown.

Otherwise, if the transaction type of the persistence unit is resource-local, or if there is no JTA transaction already associated with the caller, then the EntityManager is associated with a new transaction. If the given function returns without throwing an exception, this transaction is committed. If the function does throw an exception, the transaction is rolled back, and the exception is rethrown.

Finally, the EntityManager is closed before this method returns control to the client.

Parameters

work:Consumer<EntityManager>: a function to be executed in the scope of the transaction

Since

3.2

unwrap back to summary

unwrap	back to summary
public <T> T unwrap(Class<T> cls) Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of `EntityManagerFactory` does not support the given type, the `PersistenceException` is thrown. Parameters cls:Class<T> the class of the object to be returned. This is usually either the underlying class implementing `EntityManagerFactory` or an interface it implements. Returns:T an instance of the specified class Exceptions PersistenceException: if the provider does not support the given type Since 2.1

public <T> T unwrap(Class<T> cls)

Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of EntityManagerFactory does not support the given type, the PersistenceException is thrown.

Parameters

cls:Class<T>: the class of the object to be returned. This is usually either the underlying class implementing EntityManagerFactory or an interface it implements.

Returns:T

an instance of the specified class

Exceptions

PersistenceException:: if the provider does not support the given type

Since

2.1

public Interface EntityManagerFactory

Method Summary

Method Detail