-
- All Superinterfaces:
java.lang.AutoCloseable
public interface EntityManagerFactory extends java.lang.AutoCloseable
Interface used to interact with the persistence unit, and to create new instances ofEntityManager
.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 thePersistenceConfiguration
API.Every persistence unit has a transaction type, either
JTA
, orRESOURCE_LOCAL
. Resource-local transactions are managed programmatically via theEntityTransaction
interface.An
EntityManagerFactory
with a lifecycle managed by the application may be created using the static operations of thePersistence
class:- if the persistence unit is defined in
persistence.xml
, an entity manager factory may be created by callingPersistence.createEntityManagerFactory(String)
orPersistence.createEntityManagerFactory(String,Map)
, or - if the persistence unit was defined using
PersistenceConfiguration
, an entity manager factory may be created by callingPersistence.createEntityManagerFactory(PersistenceConfiguration)
.
Usually, there is exactly one
EntityManagerFactory
for each persistence unit:Alternatively, in the Jakarta EE environment, a container-managed
EntityManagerFactory
may be obtained by dependency injection, usingPersistenceUnit
. {@snippet : // inject the container-managed factory- Since:
- 1.0
- See Also:
EntityManager
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <T> void
addNamedEntityGraph(java.lang.String graphName, EntityGraph<T> entityGraph)
Add a named copy of the givenEntityGraph
to thisEntityManagerFactory
.void
addNamedQuery(java.lang.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 theEntityManager.createNamedQuery(java.lang.String)
orEntityManager.createNamedStoredProcedureQuery(java.lang.String)
methods.<R> R
callInTransaction(java.util.function.Function<EntityManager,R> work)
Create a new application-managedEntityManager
with an active transaction, and call the given function, passing theEntityManager
to the function.void
close()
Close the factory, releasing any resources that it holds.EntityManager
createEntityManager()
Create a new application-managedEntityManager
.EntityManager
createEntityManager(SynchronizationType synchronizationType)
Create a new JTA application-managedEntityManager
with the specified synchronization type.EntityManager
createEntityManager(SynchronizationType synchronizationType, java.util.Map<?,?> map)
Create a new JTA application-managedEntityManager
with the specified synchronization type and map of properties.EntityManager
createEntityManager(java.util.Map<?,?> map)
Create a new application-managedEntityManager
with the givenMap
specifying property settings.Cache
getCache()
Access the cache that is associated with the entity manager factory (the "second level cache").CriteriaBuilder
getCriteriaBuilder()
Return an instance ofCriteriaBuilder
which may be used to constructCriteriaQuery
objects.Metamodel
getMetamodel()
Return an instance of theMetamodel
interface for access to the metamodel of the persistence unit.java.lang.String
getName()
The name of the persistence unit.<E> java.util.Map<java.lang.String,EntityGraph<? extends E>>
getNamedEntityGraphs(java.lang.Class<E> entityType)
A map keyed by graph name, containing every named entity graph whose entity type is assignable to the given Java type.<R> java.util.Map<java.lang.String,TypedQueryReference<R>>
getNamedQueries(java.lang.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.PersistenceUnitUtil
getPersistenceUnitUtil()
Return interface providing access to utility methods for the persistence unit.java.util.Map<java.lang.String,java.lang.Object>
getProperties()
Get the properties and associated values that are in effect for the entity manager factory.SchemaManager
getSchemaManager()
Return interface providing access to schema management operations for the persistence unit.PersistenceUnitTransactionType
getTransactionType()
The type of transaction management used by this persistence unit, either resource-local transaction management, or JTA.boolean
isOpen()
Indicates whether the factory is open.void
runInTransaction(java.util.function.Consumer<EntityManager> work)
Create a new application-managedEntityManager
with an active transaction, and execute the given function, passing theEntityManager
to the function.<T> T
unwrap(java.lang.Class<T> cls)
Return an object of the specified type to allow access to a provider-specific API.
-
-
-
Method Detail
-
createEntityManager
EntityManager createEntityManager()
Create a new application-managedEntityManager
. This method returns a newEntityManager
instance each time it is invoked.The
EntityManager.isOpen()
method will return true on the returned instance.- Returns:
- entity manager instance
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed
-
createEntityManager
EntityManager createEntityManager(java.util.Map<?,?> map)
Create a new application-managedEntityManager
with the givenMap
specifying property settings. This method returns a newEntityManager
instance each time it is invoked.The
EntityManager.isOpen()
method will return true on the returned instance.- Parameters:
map
- properties for entity manager- Returns:
- entity manager instance
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed
-
createEntityManager
EntityManager createEntityManager(SynchronizationType synchronizationType)
Create a new JTA application-managedEntityManager
with the specified synchronization type. This method returns a newEntityManager
instance each time it is invoked.The
EntityManager.isOpen()
method will return true on the returned instance.- Parameters:
synchronizationType
- how and when the entity manager should be synchronized with the current JTA transaction- Returns:
- entity manager instance
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been configured for resource-local entity managers or is closed- Since:
- 2.1
-
createEntityManager
EntityManager createEntityManager(SynchronizationType synchronizationType, java.util.Map<?,?> map)
Create a new JTA application-managedEntityManager
with the specified synchronization type and map of properties. This method returns a newEntityManager
instance each time it is invoked.The
EntityManager.isOpen()
method will return true on the returned instance.- Parameters:
synchronizationType
- how and when the entity manager should be synchronized with the current JTA transactionmap
- properties for entity manager- Returns:
- entity manager instance
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been configured for resource-local entity managers or is closed- Since:
- 2.1
-
getCriteriaBuilder
CriteriaBuilder getCriteriaBuilder()
Return an instance ofCriteriaBuilder
which may be used to constructCriteriaQuery
objects.- Returns:
- an instance of
CriteriaBuilder
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 2.0
- See Also:
EntityManager.getCriteriaBuilder()
-
getMetamodel
Metamodel getMetamodel()
Return an instance of theMetamodel
interface for access to the metamodel of the persistence unit.- Returns:
- an instance of
Metamodel
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 2.0
-
isOpen
boolean isOpen()
Indicates whether the factory is open. Returns true until the factory has been closed.- Returns:
- boolean indicating whether the factory is open
-
close
void close()
Close the factory, releasing any resources that it holds. After a factory instance has been closed, all methods invoked on it will throw theIllegalStateException
, except forisOpen()
, which will return false. Once anEntityManagerFactory
has been closed, all its entity managers are considered to be in the closed state.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed
-
getName
java.lang.String getName()
The name of the persistence unit.- Since:
- 3.2
-
getProperties
java.util.Map<java.lang.String,java.lang.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:
- properties
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 2.0
-
getCache
Cache getCache()
Access the cache that is associated with the entity manager factory (the "second level cache").- Returns:
- an instance of
Cache
, or null if there is no second-level cache in use - Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 2.0
-
getPersistenceUnitUtil
PersistenceUnitUtil getPersistenceUnitUtil()
Return interface providing access to utility methods for the persistence unit.- Returns:
- an instance of
PersistenceUnitUtil
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 2.0
-
getTransactionType
PersistenceUnitTransactionType getTransactionType()
The type of transaction management used by this persistence unit, either resource-local transaction management, or JTA.- Since:
- 3.2
-
getSchemaManager
SchemaManager getSchemaManager()
Return interface providing access to schema management operations for the persistence unit.- Returns:
- an instance of
SchemaManager
- Throws:
java.lang.IllegalStateException
- if the entity manager factory has been closed- Since:
- 3.2
-
addNamedQuery
void addNamedQuery(java.lang.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 theEntityManager.createNamedQuery(java.lang.String)
orEntityManager.createNamedStoredProcedureQuery(java.lang.String)
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
orcreateNamedStoredProcedureQuery
.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
- name for the queryquery
- aQuery
,TypedQuery
, orStoredProcedureQuery
- Since:
- 2.1
-
unwrap
<T> T unwrap(java.lang.Class<T> cls)
Return an object of the specified type to allow access to a provider-specific API. If the provider implementation ofEntityManagerFactory
does not support the given type, thePersistenceException
is thrown.- Parameters:
cls
- the class of the object to be returned. This is usually either the underlying class implementingEntityManagerFactory
or an interface it implements.- Returns:
- an instance of the specified class
- Throws:
PersistenceException
- if the provider does not support the given type- Since:
- 2.1
-
addNamedEntityGraph
<T> void addNamedEntityGraph(java.lang.String graphName, EntityGraph<T> entityGraph)
Add a named copy of the givenEntityGraph
to thisEntityManagerFactory
. If an entity graph with the given name already exists, it is replaced.- Parameters:
graphName
- name for the entity graphentityGraph
- entity graph- Since:
- 2.1
-
getNamedQueries
<R> java.util.Map<java.lang.String,TypedQueryReference<R>> getNamedQueries(java.lang.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.- Type Parameters:
R
- the specified upper bound on the query result types- Parameters:
resultType
- any Java type, includingObject.class
meaning all queries- Returns:
- a map keyed by query name
- Since:
- 3.2
-
getNamedEntityGraphs
<E> java.util.Map<java.lang.String,EntityGraph<? extends E>> getNamedEntityGraphs(java.lang.Class<E> entityType)
A map keyed by graph name, containing every named entity graph whose entity type is assignable to the given Java type.- Type Parameters:
E
- the specified upper bound on the entity graph types- Parameters:
entityType
- any Java type, includingObject.class
meaning all entity graphs- Returns:
- a map keyed by graph name
- Since:
- 3.2
-
runInTransaction
void runInTransaction(java.util.function.Consumer<EntityManager> work)
Create a new application-managedEntityManager
with an active transaction, and execute the given function, passing theEntityManager
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
- a function to be executed in the scope of the transaction- Since:
- 3.2
-
callInTransaction
<R> R callInTransaction(java.util.function.Function<EntityManager,R> work)
Create a new application-managedEntityManager
with an active transaction, and call the given function, passing theEntityManager
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
- a function to be called in the scope of the transaction- Returns:
- the value returned by the given function
- Since:
- 3.2
-
-