JPA Runtime Tuning & Configuration
Most Jakarta Persistence configuration is static, defined through annotations (e.g., @Entity, @Table) or set globally at the persistence unit level during bootstrappingjakarta.persistence.PersistenceConfigurationRepresents a configuration of a persistence unit, allowing programmatic creation of an EntityManagerFactory .. This section describes dynamic options that control runtime behavior and allow you to adjust settings per session, query, or operation.
Configuration scope hierarchy
For non-static configuration (i.e., settings not expressed with annotations), JPA follows a hierarchical override model:
- EntityManagerFactory (global): Defaults passed in a property map to the factory builderjakarta.persistence.PersistenceConfigurationRepresents a configuration of a persistence unit, allowing programmatic creation of an EntityManagerFactory . or defined in
persistence.xml. - EntityManager (session): Settings applied to an
EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context.instance override global defaults and affect every operation in that session. - Query (definition): Settings applied to a
Queryjakarta.persistence.QueryInterface used to control query execution.object override session defaults for that query. - Operation (argument): Settings passed to specific
EntityManageroperations (find,lock, andrefresh) override all higher-level defaults for that call.
The find, lock, and refresh methods have variable argument versions that take one or more instance of a corresponding option interface:
Each configuration setting implements the relevant option interfaces to the methods that they can apply to.
Configuration settings
The following sections list the configuration options and show how to apply them at each scope.
Flush mode
Controls when the persistence context is synchronized with the database and when in-memory entity changes are written to the database. Available options are AUTO (flush before queries and at commit) and COMMIT (flush only at transaction commit).
| Scope | Usage |
|---|---|
| EntityManager | setFlushMode(FlushModeType) |
| Query | setFlushMode(FlushModeType) |
Lock mode
Specifies the locking strategy: optimistic or pessimistic, shared (READ) or exclusive (WRITE).
| Scope | Usage |
|---|---|
| Query | setLockMode(LockModeType) |
| Operation | Implements: FindOptionjakarta.persistence.FindOptionAn option influencing the behavior of EntityManager.find ., RefreshOptionjakarta.persistence.RefreshOptionAn option influencing the behavior of EntityManager.refresh .. Pass as an argument to lock(), find(), or refresh(). |
Pessimistic lock scope
Defines the scope of a pessimistic lock: NORMAL or EXTENDED.
| Usage | |
|---|---|
| EntityManagerFactory | Set the PersistenceConfiguration.LOCK_SCOPE property when you create the EntityManagerFactory, or set "jakarta.persistence.lock.scope" in persistence.xml. |
| EntityManager | setProperty using PersistenceConfiguration.LOCK_SCOPE, or specify it when you create the EntityManager. |
| Query | setHint using PersistenceConfiguration.LOCK_SCOPE. |
| Operation | Implements: FindOptionjakarta.persistence.FindOptionAn option influencing the behavior of EntityManager.find ., LockOptionjakarta.persistence.LockOptionAn option influencing the behavior of EntityManager.lock .. Pass as a variable argument to find() and lock(). |
Cache retrieve mode
Controls whether data is read from the second-level cache: USE or BYPASS.
| Scope | Usage |
|---|---|
| EntityManagerFactory | Set the PersistenceConfiguration.CACHE_RETRIEVE_MODE property when you create the EntityManagerFactory, or set "jakarta.persistence.cache.retrieveMode" in persistence.xml. |
| EntityManager | setCacheRetrieveMode(CacheRetrieveMode) |
| Query | setCacheRetrieveMode(CacheRetrieveMode) |
| Operation | Implements: FindOptionjakarta.persistence.FindOptionAn option influencing the behavior of EntityManager.find .. Pass as a variable argument to find(). |
Cache store mode
Controls how data is stored in the cache: USE, BYPASS, or REFRESH.
| Scope | Usage |
|---|---|
| EntityManagerFactory | Set the PersistenceConfiguration.CACHE_STORE_MODE property when you create the EntityManagerFactory, or set "jakarta.persistence.cache.storeMode" in persistence.xml. |
| EntityManager | setCacheStoreMode(CacheStoreMode) |
| Query | setCacheStoreMode(CacheStoreMode) |
| Operation | Implements: FindOptionjakarta.persistence.FindOptionAn option influencing the behavior of EntityManager.find ., RefreshOptionjakarta.persistence.RefreshOptionAn option influencing the behavior of EntityManager.refresh .. Pass as a variable argument to find() and refresh(). |
Timeout
Specifies the time limit (in milliseconds) for an operation.
| Scope | Usage |
|---|---|
| EntityManagerFactory | Set the PersistenceConfiguration.QUERY_TIMEOUT or LOCK_TIMEOUT property when you create the EntityManagerFactory, or set "jakarta.persistence.query.timeout" (or lock.timeout) in persistence.xml. |
| EntityManager | setProperty using PersistenceConfiguration.QUERY_TIMEOUT or LOCK_TIMEOUT, or specify it when you build the EntityManager. |
| Query | setTimeout(Integer). |
| Operation | Implements: FindOptionjakarta.persistence.FindOptionAn option influencing the behavior of EntityManager.find ., LockOptionjakarta.persistence.LockOptionAn option influencing the behavior of EntityManager.lock ., RefreshOptionjakarta.persistence.RefreshOptionAn option influencing the behavior of EntityManager.refresh .. Pass as a variable argument to find(), lock(), and refresh(). |
Summary
The following matrix provides a quick reference for applying these settings across different scopes.