Package jakarta.persistence

Class PersistenceConfiguration

java.lang.Object

jakarta.persistence.PersistenceConfiguration

public class PersistenceConfiguration
extends Object

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.

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.

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.

Since:

3.2

See Also:

• Persistence.createEntityManagerFactory(PersistenceConfiguration)

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
PersistenceConfiguration(String name)	Create a new empty configuration.

Method Summary

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

JDBC_DRIVER

public static final String JDBC_DRIVER

Fully qualified name of the JDBC driver class.

See Also:

• Constant Field Values

JDBC_URL

public static final String JDBC_URL

JDBC URL.

See Also:

• Constant Field Values

JDBC_USER

public static final String JDBC_USER

Username for JDBC authentication.

See Also:

• Constant Field Values

JDBC_PASSWORD

public static final String JDBC_PASSWORD

Password for JDBC authentication.

See Also:

• Constant Field Values

JDBC_DATASOURCE

public static final String JDBC_DATASOURCE

An instance of javax.sql.DataSource.

See Also:

• Constant Field Values

LOCK_TIMEOUT

public static final String LOCK_TIMEOUT

Default pessimistic lock timeout hint.

See Also:

• Constant Field Values

QUERY_TIMEOUT

public static final String QUERY_TIMEOUT

Default query timeout hint.

See Also:

• Constant Field Values

SCHEMAGEN_DATABASE_ACTION

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.

See Also:

• Constant Field Values

SCHEMAGEN_SCRIPTS_ACTION

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.

See Also:

• Constant Field Values

SCHEMAGEN_CREATE_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".

See Also:

• Constant Field Values

SCHEMAGEN_DROP_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".

See Also:

• Constant Field Values

SCHEMAGEN_CREATE_SCRIPT_SOURCE

public static final String SCHEMAGEN_CREATE_SCRIPT_SOURCE

An application-provided SQL script to be executed when the schema is created.

See Also:

• Constant Field Values

SCHEMAGEN_DROP_SCRIPT_SOURCE

public static final String SCHEMAGEN_DROP_SCRIPT_SOURCE

An application-provided SQL script to be executed when the schema is dropped.

See Also:

• Constant Field Values

SCHEMAGEN_CREATE_TARGET

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.

See Also:

• Constant Field Values

SCHEMAGEN_DROP_TARGET

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.

See Also:

• Constant Field Values

VALIDATION_FACTORY

public static final String VALIDATION_FACTORY

An instance of jakarta.validation.ValidatorFactory,

See Also:

• Constant Field Values

VALIDATION_GROUP_PRE_PERSIST

public static final String VALIDATION_GROUP_PRE_PERSIST

Target groups for validation at PrePersist.

See Also:

• Constant Field Values

VALIDATION_GROUP_PRE_UPDATE

public static final String VALIDATION_GROUP_PRE_UPDATE

Target groups for validation at PreUpdate.

See Also:

• Constant Field Values

VALIDATION_GROUP_PRE_REMOVE

public static final String VALIDATION_GROUP_PRE_REMOVE

Target groups for validation at PreRemove.

See Also:

• Constant Field Values

CACHE_MODE

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).

See Also:

• Constant Field Values

Constructor Details

PersistenceConfiguration

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 - the name of the persistence unit, which may be used by the persistence provider for logging and error reporting

Method Details

createEntityManagerFactory

public EntityManagerFactory createEntityManagerFactory()

Create a new EntityManagerFactory based on this configuration.

Throws:

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

name

public String name()

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

Returns:

the name of the persistence unit.

provider

public PersistenceConfiguration provider(String providerClassName)

Specify the persistence provider.

Parameters:

providerClassName - the qualified name of the persistence provider class

Returns:

this configuration

provider

public String provider()

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

Returns:

the qualified name of the persistence provider class.

jtaDataSource

public PersistenceConfiguration jtaDataSource(String dataSourceJndiName)

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

Parameters:

dataSourceJndiName - the JNDI name of a JTA datasource

Returns:

this configuration

jtaDataSource

public String jtaDataSource()

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

Returns:

the configured JTA datasource, if any, or null

nonJtaDataSource

public PersistenceConfiguration nonJtaDataSource(String dataSourceJndiName)

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

Parameters:

dataSourceJndiName - the JNDI name of a non-JTA datasource

Returns:

this configuration

nonJtaDataSource

public String nonJtaDataSource()

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

Returns:

the configured non-JTA datasource, if any, or null

managedClass

public PersistenceConfiguration managedClass(Class<?> managedClass)

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

Parameters:

managedClass - the managed class

Returns:

this configuration

managedClasses

public List<Class<?>> managedClasses()

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

Returns:

all configured managed classes

mappingFile

public PersistenceConfiguration mappingFile(String name)

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

Parameters:

name - the resource path of the mapping file

Returns:

this configuration

mappingFiles

public List<String> mappingFiles()

The configured resource paths of XML mapping files.

Returns:

all configured mapping file resource paths

transactionType

public PersistenceConfiguration transactionType(PersistenceUnitTransactionType transactionType)

Specify the transaction type for the persistence unit.

Parameters:

transactionType - the transaction type

Returns:

this configuration

transactionType

public PersistenceUnitTransactionType transactionType()

The transaction type.

• If PersistenceUnitTransactionType.JTA, a JTA data source must be provided via jtaDataSource(), or by the container.
• If PersistenceUnitTransactionType.RESOURCE_LOCAL, database connection properties may be specified via properties(), or a non-JTA datasource may be provided via nonJtaDataSource().

Returns:

the transaction type

sharedCacheMode

public PersistenceConfiguration sharedCacheMode(SharedCacheMode sharedCacheMode)

Specify the shared cache mode for the persistence unit.

Parameters:

sharedCacheMode - the shared cache mode

Returns:

this configuration

sharedCacheMode

public SharedCacheMode sharedCacheMode()

The shared cache mode. The default behavior is unspecified and provider-specific.

Returns:

the shared cache mode

validationMode

public PersistenceConfiguration validationMode(ValidationMode validationMode)

Specify the validation mode for the persistence unit.

Parameters:

validationMode - the shared cache mode

Returns:

this configuration

validationMode

public ValidationMode validationMode()

The validation mode, ValidationMode.AUTO by default.

Returns:

the validation mode

property

public PersistenceConfiguration property(String name,
 Object value)

Set a property of this persistence unit.

Parameters:

name - the property name

value - the property value

Returns:

this configuration

properties

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

Set multiple properties of this persistence unit.

Parameters:

properties - the properties

Returns:

this configuration

properties

public Map<String,Object> properties()

Standard and vendor-specific property settings.

Returns:

the configured properties