Jakarta EE 11.0.0 · jakarta.persistence.PersistenceConfiguration

Represents a configuration of a persistence unit, allowing programmatic creation of an EntityManagerFactory. The configuration options available via this API reflect the similarly-named elements of the persistence.xml file.

This API may not be used to configure a container-managed persistence unit. That is, the configured persistence unit should be considered a Java SE persistence unit, even when this API is used within the Jakarta EE environment.

If injection of the EntityManagerFactory is required, a CDI Producer may be used to make the EntityManagerFactory available as a CDI managed bean.

@Produces @ApplicationScoped @Documents
EntityManagerFactory configure() {
    return new PersistenceConfiguration()
            .name("DocumentData")
            .nonJtaDataSource("java:global/jdbc/DocumentDatabase")
            .managedClass(Document.class)
            .createEntityManagerFactory();
}

Similarly, if injection of an EntityManager is required, a CDI Producer method/Disposer method pair may be used to make the EntityManager available as a CDI managed bean.

@Produces @TransactionScoped @Documents
EntityManager create(@Documents EntityManagerFactory factory) {
    return factory.createEntityManager();
}

void close(@Disposes @Documents EntityManager entityManager) {
    entityManager.close();
}

It is intended that persistence providers define subclasses of this class with vendor-specific configuration options. A provider must support configuration via any instance of this class or of any subclass of this class.

Field Summary

Modifier and Type	Field and Description
public static final String	CACHE_MODE String specifying a `SharedCacheMode`.
public static final String	JDBC_DATASOURCE An instance of `javax.sql.DataSource`.
public static final String	JDBC_DRIVER Fully qualified name of the JDBC driver class.
public static final String	JDBC_PASSWORD Password for JDBC authentication.
public static final String	JDBC_URL JDBC URL.
public static final String	JDBC_USER Username for JDBC authentication.
private String	jtaDataSource
public static final String	LOCK_TIMEOUT Default pessimistic lock timeout hint.
private final List<Class<?>>	managedClasses
private final List<String>	mappingFileNames
private final String	name
private String	nonJtaDataSource
private final Map<String, Object>	properties
private String	provider
public static final String	QUERY_TIMEOUT Default query timeout hint.
public static final String	SCHEMAGEN_CREATE_SCRIPT_SOURCE An application-provided SQL script to be executed when the schema is created.
public static final String	SCHEMAGEN_CREATE_SOURCE The source of artifacts to be created.
public static final String	SCHEMAGEN_CREATE_TARGET The provider-generated SQL script which creates the schema when jakarta.persistence.schema-generation.scripts.action is set.
public static final String	SCHEMAGEN_DATABASE_ACTION The action to be performed against the database.
public static final String	SCHEMAGEN_DROP_SCRIPT_SOURCE An application-provided SQL script to be executed when the schema is dropped.
public static final String	SCHEMAGEN_DROP_SOURCE The source of artifacts to be dropped.
public static final String	SCHEMAGEN_DROP_TARGET The provider-generated SQL script which drops the schema when jakarta.persistence.schema-generation.scripts.action is set.
public static final String	SCHEMAGEN_SCRIPTS_ACTION The action to be generated as a SQL script.
private SharedCacheMode	sharedCacheMode
private PersistenceUnitTransactionType	transactionType
public static final String	VALIDATION_FACTORY An instance of `jakarta.validation.ValidatorFactory`,
public static final String	VALIDATION_GROUP_PRE_PERSIST Target groups for validation at `PrePersist`.
public static final String	VALIDATION_GROUP_PRE_REMOVE Target groups for validation at `PreRemove`.
public static final String	VALIDATION_GROUP_PRE_UPDATE Target groups for validation at `PreUpdate`.
private ValidationMode	validationMode

Constructor Summary

Access	Constructor and Description
public	PersistenceConfiguration(String the name of the persistence unit, which may be used by the persistence provider for logging and error reporting name) Create a new empty configuration.

Method Summary

Modifier and Type	Method and Description
public EntityManagerFactory	createEntityManagerFactory() Create a new `EntityManagerFactory` based on this configuration.
public PersistenceConfiguration	Returns: this configuration jtaDataSource(String the JNDI name of a JTA datasource dataSourceJndiName) Specify the JNDI name of a JTA `javax.sql.DataSource`.
public String	Returns: the configured JTA datasource, if any, or null jtaDataSource() The JNDI name of a JTA `javax.sql.DataSource`.
public PersistenceConfiguration	Returns: this configuration managedClass(Class<?> the managed class managedClass) Add a managed class (an `Entity`, `Embeddable`, `MappedSuperclass`, or `Converter`) to the configuration.
public List<Class<?>>	Returns: all configured managed classes managedClasses() The configured managed classes, that is, a list of classes annotated `Entity`, `Embeddable`, `MappedSuperclass`, or `Converter`.
public PersistenceConfiguration	Returns: this configuration mappingFile(String the resource path of the mapping file name) Add the path of an XML mapping file loaded as a resource to the configuration.
public List<String>	Returns: all configured mapping file resource paths mappingFiles() The configured resource paths of XML mapping files.
public String	Returns: the name of the persistence unit. name() The name of the persistence unit, which may be used by the persistence provider for logging and error reporting.
public PersistenceConfiguration	Returns: this configuration nonJtaDataSource(String the JNDI name of a non-JTA datasource dataSourceJndiName) Specify the JNDI name of a non-JTA `javax.sql.DataSource`.
public String	Returns: the configured non-JTA datasource, if any, or null nonJtaDataSource() The JNDI name of a non-JTA `javax.sql.DataSource`.
public PersistenceConfiguration	Returns: this configuration properties(Map<String, ?> the properties properties) Set multiple properties of this persistence unit.
public Map<String, Object>	Returns: the configured properties properties() Standard and vendor-specific property settings.
public PersistenceConfiguration	Returns: this configuration property(String the property name name, Object the property value value) Set a property of this persistence unit.
public PersistenceConfiguration	Returns: this configuration provider(String the qualified name of the persistence provider class providerClassName) Specify the persistence provider.
public String	Returns: the qualified name of the persistence provider class. provider() The fully-qualified name of a concrete class implementing `jakarta.persistence.spi.PersistenceProvider`.
public PersistenceConfiguration	Returns: this configuration sharedCacheMode(SharedCacheMode the shared cache mode sharedCacheMode) Specify the shared cache mode for the persistence unit.
public SharedCacheMode	Returns: the shared cache mode sharedCacheMode() The shared cache mode.
public PersistenceConfiguration	Returns: this configuration transactionType(PersistenceUnitTransactionType the transaction type transactionType) Specify the transaction type for the persistence unit.
public PersistenceUnitTransactionType	Returns: the transaction type transactionType() The transaction type.
public PersistenceConfiguration	Returns: this configuration validationMode(ValidationMode the shared cache mode validationMode) Specify the validation mode for the persistence unit.
public ValidationMode	Returns: the validation mode validationMode() The validation mode, `ValidationMode#AUTO` by default.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CACHE_MODE back to summary

CACHE_MODE	back to summary
public static final String CACHE_MODE String specifying a `SharedCacheMode`. Defined for use with `Persistence#createEntityManagerFactory(String, Map)`. Clients of this `PersistenceConfiguration` class should use `sharedCacheMode(SharedCacheMode)`.

public static final String CACHE_MODE

String specifying a SharedCacheMode.

Defined for use with Persistence#createEntityManagerFactory(String, Map). Clients of this PersistenceConfiguration class should use sharedCacheMode(SharedCacheMode).

JDBC_DATASOURCE	back to summary
public static final String JDBC_DATASOURCE An instance of `javax.sql.DataSource`.

JDBC_DRIVER	back to summary
public static final String JDBC_DRIVER Fully qualified name of the JDBC driver class.

JDBC_PASSWORD	back to summary
public static final String JDBC_PASSWORD Password for JDBC authentication.

JDBC_URL	back to summary
public static final String JDBC_URL JDBC URL.

JDBC_USER	back to summary
public static final String JDBC_USER Username for JDBC authentication.

jtaDataSource	back to summary
private String jtaDataSource

LOCK_TIMEOUT	back to summary
public static final String LOCK_TIMEOUT Default pessimistic lock timeout hint.

managedClasses	back to summary
private final List<Class<?>> managedClasses

mappingFileNames	back to summary
private final List<String> mappingFileNames

name	back to summary
private final String name

nonJtaDataSource	back to summary
private String nonJtaDataSource

properties	back to summary
private final Map<String, Object> properties

provider	back to summary
private String provider

QUERY_TIMEOUT	back to summary
public static final String QUERY_TIMEOUT Default query timeout hint.

SCHEMAGEN_CREATE_SCRIPT_SOURCE	back to summary
public static final String SCHEMAGEN_CREATE_SCRIPT_SOURCE An application-provided SQL script to be executed when the schema is created.

SCHEMAGEN_CREATE_SOURCE back to summary

SCHEMAGEN_CREATE_SOURCE	back to summary
public static final String SCHEMAGEN_CREATE_SOURCE The source of artifacts to be created. Standard sources are: `metadata`, `script`, `metadata-then-script`, `script-then-metadata`. The location of the script source is specified by jakarta.persistence.schema-generation.create-script-source.

public static final String SCHEMAGEN_CREATE_SOURCE

The source of artifacts to be created.

Standard sources are: metadata, script, metadata-then-script, script-then-metadata.

The location of the script source is specified by jakarta.persistence.schema-generation.create-script-source.

SCHEMAGEN_CREATE_TARGET	back to summary
public static final String SCHEMAGEN_CREATE_TARGET The provider-generated SQL script which creates the schema when jakarta.persistence.schema-generation.scripts.action is set.

SCHEMAGEN_DATABASE_ACTION back to summary

SCHEMAGEN_DATABASE_ACTION	back to summary
public static final String SCHEMAGEN_DATABASE_ACTION The action to be performed against the database. Standard actions are: `none`, `create`, `drop`, `drop-and-create`, `validate`.

public static final String SCHEMAGEN_DATABASE_ACTION

The action to be performed against the database.

Standard actions are: none, create, drop, drop-and-create, validate.

SCHEMAGEN_DROP_SCRIPT_SOURCE	back to summary
public static final String SCHEMAGEN_DROP_SCRIPT_SOURCE An application-provided SQL script to be executed when the schema is dropped.

SCHEMAGEN_DROP_SOURCE back to summary

SCHEMAGEN_DROP_SOURCE	back to summary
public static final String SCHEMAGEN_DROP_SOURCE The source of artifacts to be dropped. Standard sources are: `metadata`, `script`, `metadata-then-script`, `script-then-metadata`. The location of the script source is specified by jakarta.persistence.schema-generation.drop-script-source.

public static final String SCHEMAGEN_DROP_SOURCE

The source of artifacts to be dropped.

Standard sources are: metadata, script, metadata-then-script, script-then-metadata.

The location of the script source is specified by jakarta.persistence.schema-generation.drop-script-source.

SCHEMAGEN_DROP_TARGET	back to summary
public static final String SCHEMAGEN_DROP_TARGET The provider-generated SQL script which drops the schema when jakarta.persistence.schema-generation.scripts.action is set.

SCHEMAGEN_SCRIPTS_ACTION back to summary

SCHEMAGEN_SCRIPTS_ACTION	back to summary
public static final String SCHEMAGEN_SCRIPTS_ACTION The action to be generated as a SQL script. The script is generated in the location specified by jakarta.persistence.schema-generation.create-target or jakarta.persistence.schema-generation.drop-target. Standard actions are: `none`, `create`, `drop`, `drop-and-create`.

public static final String SCHEMAGEN_SCRIPTS_ACTION

The action to be generated as a SQL script.

The script is generated in the location specified by jakarta.persistence.schema-generation.create-target or jakarta.persistence.schema-generation.drop-target.

Standard actions are: none, create, drop, drop-and-create.

sharedCacheMode	back to summary
private SharedCacheMode sharedCacheMode

transactionType	back to summary
private PersistenceUnitTransactionType transactionType

VALIDATION_FACTORY	back to summary
public static final String VALIDATION_FACTORY An instance of `jakarta.validation.ValidatorFactory`,

VALIDATION_GROUP_PRE_PERSIST	back to summary
public static final String VALIDATION_GROUP_PRE_PERSIST Target groups for validation at `PrePersist`.

VALIDATION_GROUP_PRE_REMOVE	back to summary
public static final String VALIDATION_GROUP_PRE_REMOVE Target groups for validation at `PreRemove`.

VALIDATION_GROUP_PRE_UPDATE	back to summary
public static final String VALIDATION_GROUP_PRE_UPDATE Target groups for validation at `PreUpdate`.

validationMode	back to summary
private ValidationMode validationMode

Constructor Detail

PersistenceConfiguration back to summary

PersistenceConfiguration	back to summary
public PersistenceConfiguration(String name) Create a new empty configuration. An empty configuration does not typically hold enough information for successful invocation of `createEntityManagerFactory()`. Parameters name:String the name of the persistence unit, which may be used by the persistence provider for logging and error reporting

public PersistenceConfiguration(String name)

Create a new empty configuration. An empty configuration does not typically hold enough information for successful invocation of createEntityManagerFactory().

Parameters

name:String: the name of the persistence unit, which may be used by the persistence provider for logging and error reporting

Method Detail

createEntityManagerFactory back to summary

createEntityManagerFactory	back to summary
public EntityManagerFactory createEntityManagerFactory() Create a new `EntityManagerFactory` based on this configuration. Exceptions PersistenceException: if required configuration is missing or if the factory could not be created

public EntityManagerFactory createEntityManagerFactory()

Create a new EntityManagerFactory based on this configuration.

Exceptions

PersistenceException:: if required configuration is missing or if the factory could not be created

jtaDataSource back to summary

jtaDataSource	back to summary
public PersistenceConfiguration jtaDataSource(String dataSourceJndiName) Specify the JNDI name of a JTA `javax.sql.DataSource`. Parameters dataSourceJndiName:String the JNDI name of a JTA datasource Returns:PersistenceConfiguration this configuration

public PersistenceConfiguration jtaDataSource(String dataSourceJndiName)

Specify the JNDI name of a JTA javax.sql.DataSource.

Parameters

dataSourceJndiName:String: the JNDI name of a JTA datasource

Returns:PersistenceConfiguration

this configuration

jtaDataSource back to summary

jtaDataSource	back to summary
public String jtaDataSource() The JNDI name of a JTA `javax.sql.DataSource`. Returns:String the configured JTA datasource, if any, or null

public String jtaDataSource()

The JNDI name of a JTA javax.sql.DataSource.

Returns:String: the configured JTA datasource, if any, or null

managedClass back to summary

managedClass	back to summary
public PersistenceConfiguration managedClass(Class<?> managedClass) Add a managed class (an `Entity`, `Embeddable`, `MappedSuperclass`, or `Converter`) to the configuration. Parameters managedClass:Class<?> the managed class Returns:PersistenceConfiguration this configuration

public PersistenceConfiguration managedClass(Class<?> managedClass)

Add a managed class (an Entity, Embeddable, MappedSuperclass, or Converter) to the configuration.

Parameters

managedClass:Class<?>: the managed class

Returns:PersistenceConfiguration

this configuration

managedClasses back to summary

managedClasses	back to summary
public List<Class<?>> managedClasses() The configured managed classes, that is, a list of classes annotated `Entity`, `Embeddable`, `MappedSuperclass`, or `Converter`. Returns:List<Class<?>> all configured managed classes

public List<Class<?>> managedClasses()

The configured managed classes, that is, a list of classes annotated Entity, Embeddable, MappedSuperclass, or Converter.

Returns:List<Class<?>>: all configured managed classes

mappingFile	back to summary
public PersistenceConfiguration mappingFile(String name) Add the path of an XML mapping file loaded as a resource to the configuration. Parameters name:String the resource path of the mapping file Returns:PersistenceConfiguration this configuration

mappingFile

back to summary

public PersistenceConfiguration mappingFile(String name)

Add the path of an XML mapping file loaded as a resource to the configuration.

Parameters

name:String: the resource path of the mapping file

Returns:PersistenceConfiguration

this configuration

mappingFiles	back to summary
public List<String> mappingFiles() The configured resource paths of XML mapping files. Returns:List<String> all configured mapping file resource paths

mappingFiles

back to summary

public List<String> mappingFiles()

The configured resource paths of XML mapping files.

Returns:List<String>: all configured mapping file resource paths

name	back to summary
public String name() The name of the persistence unit, which may be used by the persistence provider for logging and error reporting. Returns:String the name of the persistence unit.

name

back to summary

public String name()

The name of the persistence unit, which may be used by the persistence provider for logging and error reporting.

Returns:String: the name of the persistence unit.

nonJtaDataSource back to summary

nonJtaDataSource	back to summary
public PersistenceConfiguration nonJtaDataSource(String dataSourceJndiName) Specify the JNDI name of a non-JTA `javax.sql.DataSource`. Parameters dataSourceJndiName:String the JNDI name of a non-JTA datasource Returns:PersistenceConfiguration this configuration

public PersistenceConfiguration nonJtaDataSource(String dataSourceJndiName)

Specify the JNDI name of a non-JTA javax.sql.DataSource.

Parameters

dataSourceJndiName:String: the JNDI name of a non-JTA datasource

Returns:PersistenceConfiguration

this configuration

nonJtaDataSource back to summary

nonJtaDataSource	back to summary
public String nonJtaDataSource() The JNDI name of a non-JTA `javax.sql.DataSource`. Returns:String the configured non-JTA datasource, if any, or null

public String nonJtaDataSource()

The JNDI name of a non-JTA javax.sql.DataSource.

Returns:String: the configured non-JTA datasource, if any, or null

properties	back to summary
public PersistenceConfiguration properties(Map<String, ?> properties) Set multiple properties of this persistence unit. Parameters properties:Map<String, ?> the properties Returns:PersistenceConfiguration this configuration

properties

back to summary

public PersistenceConfiguration properties(Map<String, ?> properties)

Set multiple properties of this persistence unit.

Parameters

properties:Map<String, ?>: the properties

Returns:PersistenceConfiguration

this configuration

properties	back to summary
public Map<String, Object> properties() Standard and vendor-specific property settings. Returns:Map<String, Object> the configured properties

properties

back to summary

public Map<String, Object> properties()

Standard and vendor-specific property settings.

Returns:Map<String, Object>: the configured properties

property	back to summary
public PersistenceConfiguration property(String name, Object value) Set a property of this persistence unit. Parameters name:String the property name value:Object the property value Returns:PersistenceConfiguration this configuration

property

back to summary

public PersistenceConfiguration property(String name, Object value)

Set a property of this persistence unit.

Parameters

name:String: the property name
value:Object: the property value

Returns:PersistenceConfiguration

this configuration

provider	back to summary
public PersistenceConfiguration provider(String providerClassName) Specify the persistence provider. Parameters providerClassName:String the qualified name of the persistence provider class Returns:PersistenceConfiguration this configuration

provider

back to summary

public PersistenceConfiguration provider(String providerClassName)

Specify the persistence provider.

Parameters

providerClassName:String: the qualified name of the persistence provider class

Returns:PersistenceConfiguration

this configuration

provider back to summary

provider	back to summary
public String provider() The fully-qualified name of a concrete class implementing `jakarta.persistence.spi.PersistenceProvider`. Returns:String the qualified name of the persistence provider class.

public String provider()

The fully-qualified name of a concrete class implementing jakarta.persistence.spi.PersistenceProvider.

Returns:String: the qualified name of the persistence provider class.

sharedCacheMode	back to summary
public PersistenceConfiguration sharedCacheMode(SharedCacheMode sharedCacheMode) Specify the shared cache mode for the persistence unit. Parameters sharedCacheMode:SharedCacheMode the shared cache mode Returns:PersistenceConfiguration this configuration

sharedCacheMode

back to summary

public PersistenceConfiguration sharedCacheMode(SharedCacheMode sharedCacheMode)

Specify the shared cache mode for the persistence unit.

Parameters