A persistence configuration XML file defines a collection of the persistence units. There must be at least one persistence unit in the file for it to be useful. A persistence unit represents a persistence context in the application, and it has a name. The name is used in an application to link EntityManager with the persistence unit. The linkage is defined with the @PersistenceContext annotation.

A persistence unit has two types of transactions: JTA and RESOURCE_LOCAL.

<persistence version = "1.0"xmlns = "http://java.sun.com/xml/ns/persistence"xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation = "http://java.sun.com/xml/ns/persistencehttp://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">

  <persistence-unit name = "{NAME}" transaction-type = "{TX-TYPE}">
  <provider>{PersistenceProvider}</provider>
  
  <!-- By default your mappings defined in orm.xml -->
  <!—- file, which is discovered automatically. -->
  <mapping-file>META-INF/my-mappings.xml</mapping-file>
  ...
  <jar-file>my-additional-jar.jar</jar-file>
  ...
  <!-- Enables auto discovery of persistent classes, -->
  <!-- otherwise they must be listed using <class>-->
  <exclude-unlisted-classes>false</exclude-unlisted-classes>
  
  <properties>
  ...
  </properties>
  </persistence-unit>
</persistence>

The transaction type JTA is normally configured inside a Java EE application, because the data source is usually configured with a transaction manager inside the product provider, such as the GlassFish or WebLogic servers.

It is possible to use the default JPA provider, provided by the Java EE product provider, or to supply your own provider implementation. Configuration for the JPA provider is in the <provider> XML element.

Inside the persistence.xml file again, a persistence unit can include an additional JAR file to load, in order to provide extra support to the application at deployment. The <jar-file> XML element declares the persistence entity beans. The persistence unit can rely on auto discovery of the entity beans or it can explicitly declare the classes that will be loaded by the <class/> XML element.

The <exclude-unlisted-classes/> stanza is specific for the Java EE environments only. It is a Boolean value that determines if the JPA provider scans for the annotated entity beans in the top level of the persistence unit. If this is not the case, then set this value to false in order to allow the JPA provider to find the annotated entity bean not in the top level. The <exclude-unlisted-classes/> XML element is helpful in certain situations for the embeddable, mapped super-classes, and converter classes.

There is an alternative way to specify the object-relational mapping, using a mapping file, which is particularly interesting if you do not have access to the source of the persist entities for a business reason. To specify a mapping file, use the <mapping-file> XML element. The object-relation mapping file contains the mapping information for the classes listed in it.

Here is a portable JPA 2.0 object-relational mapping file of the earlier SpyThriller entity bean. This file is named sample-orm.xml in the source code.

<?xml version = "1.0" encoding = "UTF-8"?>
<entity-mappings version = "2.0"xmlns = "http://java.sun.com/xml/ns/persistence/orm"xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation = "http://java.sun.com/xml/ns/persistence/orm_2_0.xsd">
<description>Mapping persistent entity in XML.</description>
<entity name = "SpyThriller" class = "SpyThriller" access = "FIELD">
<table name = "SPY_THRILLER_BOOK"/>
<attributes>
<id name = "id">
<generated-value strategy = "AUTO"/>
<column name = "BOOK_ID" nullable = "false"unique = "true" insertable = "true" updatable = "true"table = "THRILLER_BOOK"/>
</id>
<basic name = "writer">
<column name = "AUTHORS" nullable = "false"/>
</basic>
<basic name = "year">
<column name = "BOOK_YEAR" nullable = "false"/>
</basic>
<basic name = "title">
<column name = "TITLE" nullable = "false"/>
</basic>
<transient name = "secretCode"/>
</attributes>
</entity>
</entity-mappings>

The ORM mapping file is largely similar to the annotation version, although in my opinion a little verbose compared to the annotated source code. Most software development will, I think, tend to prefer the annotations. On the other hand, the XML mapping file is a standard option that permits migration and upgrade. There is a route for pre-JPA solutions and older J2EE classes to enter the modern age of persistence.

An object-relational file mapping may be specified in the META-INF/ directory of the root of the persistence unit, or the META-INF/ directory of any JAR file referenced by the persistence unit. It will then be loaded by the JPA provider at deployment.

In JPA 2.1, there are additional properties that can be used to configure the database connection. In most cases inside the Java EE application, the database connection is configured inside the Java EE product, and provided as a data source to the application.

For the benefit of writing the standalone Java SE applications and unit tests, perhaps to support other forms of integration tests, you can supply additional properties in a persistence unit configuration.