A Beginner's Guide to JPA's persistence.

xml
The most basic persistence.xml configuration
You can use JPA with a very short, basic configuration. You only need
a persistence element as the root element and a persistence-unit
element with a name attribute. The attribute is used to identify the
persistence unit, and you can use it during the bootstrapping process
to instantiate a specific EntityManagerFactory.

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" version="2.2"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persist
ence
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
>
<!-- Define persistence unit -->
<persistence-unit name="my-persistence-unit">
</persistence-unit>
</persistence>

When you use this configuration, you configure a persistence unit

with the name "my-persistence-unit" without defining a dependency
to a specific JPA implementation. You also rely on a list of defaults
defined by the specification:
 Your persistence provider scans the root of your persistence
unit and adds all annotated managed persistence classes to the
persistence unit.
 If your META-INF directory contains a file called orm.xml, it
gets treated as a mapping file and all included mapping
information get used.
 The used transaction type depends on the environment in
which you deploy your application. In a Jakarta EE environment,
JPA expects that the container provides a JTA-compliant

www.thoughts-on-java.org
A Beginner's Guide to JPA's persistence.xml
connection provider. In a Java SE environment, it uses a
RESOURCE_LOCAL transaction instead.
 You don't configure any database connection. JPA, therefore,
expects that you provide a datasource at runtime.
 All JPA implementations support a set of proprietary
configuration parameters. Examples for that are the logging
configuration in EclipseLink JPA or Hibernate's database dialect.
As you don't define any of them in this basic configuration, you
also rely on all provider-specific defaults.

Optional configuration elements you should know

You can use the following XML elements to customize the basic
configuration:
<description>This is a short Provide a short description of
text describing my persistence your persistence unit.
unit.</description>
<class>org.thoughts.on.java.jpa.By adding one or more class
beginners.Professor</class> elements to your persistence-unit
configuration, you can add
classes to your persistence unit
which are not in the root of the
persistence unit.
<jar-file>my-entities.jar</jar- You can use one or more jar-file
file> elements to add all managed
classes contained in these jar
files.
<exclude-unlisted- The exclude-unlisted-classes
classes>true</exclude- element enables you to exclude
unlisted-classes> all classes from the persistence-
unit which were not explicitly
included.
<mapping- You can use external, XML-based
file>file:\\\C:\dev\wrk\XmlM mapping files. By default, your
apping\XmlMappings\myMap persistence provider checks if the
pings.xml</mapping-file> META-INF directory contains a
file called orm.xml and includes
its mapping information.
If you want to use multiple

www.thoughts-on-java.org
A Beginner's Guide to JPA's persistence.xml
mapping files or if the name of
your file doesn't match the
default naming pattern, you can
reference them in one or more
mapping-file elements.
<provider>org.eclipse.persisten If you use any proprietary
ce.jpa.PersistenceProvider</pr features of your persistence
ovider> provider, you should specify a
dependency to it.
<jta-data- These elements are mostly used
source>java:app/jdbc/MyData in Jakarta EE environments. They
Source</jta-data-source> enable you to reference the JNDI
<non-jta-data- name of a datasource that is or is
source>java:app/jdbc/MyData not compliant with the Java
Source</non-jta-data-source> Transaction API.
<shared-cache- You can activate the 2nd level
mode>ENABLE_SELECTIVE</s cache and specify its mode with
hared-cache-mode> the shared-cache-mode element.
You can choose between 4
different options:
1. ALL - To cache all entities
2. NONE - To cache none of
your entities (default)
3. ENABLE_SELECTIVE - To
cache only the entities
annotated with @Cacheable
or @Cacheable(true)
4. DISABLE_SELECTIVE - To
cache all entities not
annotated with
@Cacheable(false)
<validation- The 3 different values supported
mode>CALLBACK</validation- by the validation-mode element
mode> enable you to activate or
deactivate the validation:
1. AUTO - Perform the
validation if a bean
validation implementation is
available (default)
2. CALLBACK- Activate the
validation and throw an

www.thoughts-on-java.org
A Beginner's Guide to JPA's persistence.xml
exception if no bean
validation implementation is
available
3. NONE - Do not perform any
validation
<properties> You can use the properties
<property name = javax.persistence.lock.timeout
"javax.persistence.lock.timeout" and
value="100"/> javax.persistence.query.timeout
<property name = to define the pessimistic lock
"javax.persistence.query.timeou timeout and the query timeout in
t" value="100"/> milliseconds.
</properties>
<properties> You can configure one or more
<property name = groups that get validated for each
"javax.persistence.validation.gr lifecycle state change by using
oup.pre-persist" value = these property.
"javax.validation.groups.MyPers
istValidation"/>
<property name =
"javax.persistence.validation.gr
oup.pre-update" value =
"javax.validation.groups.MyUpd
ateValidation"/>
<property name =
"javax.persistence.validation.gr
oup.pre-remove" value =
"javax.validation.groups.MyRem
ovetValidation"/>
</properties>
<properties> In a Java SE environment, you
<property name = might not have a datasource that
"javax.persistence.jdbc.driver" you can reference to define the
value = "org.postgresql.Driver" database connection. In these
/> situations, you can use this set of
<property name = properties to specify the JDBC
"javax.persistence.jdbc.url" driver class, the connection URL
value = and the login information that
"jdbc:postgresql://localhost:54 your persistence provider shall
32/jpaForBeginners" /> use to connect to the database.

www.thoughts-on-java.org
A Beginner's Guide to JPA's persistence.xml
<property name =
"javax.persistence.jdbc.user"
value="postgres" />
<property name =
"javax.persistence.jdbc.passwor
d" value = "postgres" />
</properties>
<properties> Since version 2.1, JPA can create a
<property name = new database at startup and
"javax.persistence.schema- initialize it with a predefined
generation.database.action" dataset. You can activate and
value = "drop-and-create" /> configure this feature by adding
<property name = these properties to your
"javax.persistence.schema- configuration.
generation.create-script-
source" value = "create-db.sql"
/>
<property name =
"javax.persistence.schema-
generation.drop-script-source"
value = "drop-db.sql" />
<property name =
"javax.persistence.sql-load-
script-source" value = "data.sql"
/>
</properties>
<properties> You can tell your persistence
<property name = provider to generate your
"javax.persistence.schema- database scripts by configuring
generation.scripts.action" value these properties.
= "drop-and-create"/>
<property name = Please be aware that these scripts
"javax.persistence.schema- often need to be adapted and
generation.scripts.create- optimized before you can use
target" value = "./create.sql"/> them in production.
<property name =
"javax.persistence.schema-
generation.scripts.drop-target"
value = "./drop.sql"/>
</properties>

www.thoughts-on-java.org