The persistence.xml file is a simple XML deployment descriptor file that defines a persistence unit. This file configures the name of the EntityManager service, which manages a set of entity instances. The XML configuration also defines how each EntityManager connects to the database. A persistence unit may declare one or more uniquely named EntityManager instances.
The root element of the persistence.xml file is the persistence XML element and it contains a set of persistence-unit XML complex elements.
Here is a simple declaration of persistence.xml for JPA 2.1:
<persistence version=""2.1""
xmlns=""http://xmlns.jcp.org/xml/ns/persistence""
xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
xsi:schemaLocation=""http://xmlns.jcp.org/xml/ns/persistence
http://www.oracle.com/webfolder/technetwork/
jsc/xml/ns/persistence/persistence_2_1.xsd"">
<persistence-unit name=""trading""
transaction-type=""JTA"">
<jta-data-source>jdbc/trading</jta-data-source>
</persistence-unit>
<persistence-unit name=""audit""
transaction-type=""JTA"">
<jta-data-source>jdbc/audit</jta-data-source>
</persistence-unit>
</persistence>The transaction-type XML element for a persistence unit can be either JTA or RESOURCE_LOCAL. Specifying the values, JTA indicates that the entity manager partakes in distributed transactions, whereas RESOURCE_LOCAL indicates that the database transactions are just local to the particular application running in that Java EE application server on this JVM.
The element jta-data-source defines a JTA data source configured in the application server. The element non-data-source defines a non-JTA data source.
The element provider defines a particular persistence provider. Of course, the necessary configuration must be applied to the application server, or it should be supplied already by the product.
Here is an example of a persistence unit with both JPA properties and vendor properties:
<persistence version=""2.1"" ...>
<persistence-unit name=""ratings"" transaction-type=""JTA"">
<provider>org.hibernate.ejb.HibernatePersistence
</provider>
<non-jta-data-source>jdbc/rating</non-jta-data-source>
<properties>
<property name=""javax.persistence.schema-generation.database.action"" value=""create""/>
<property name=""javax.persistence.schema-generation.scripts.action"" value=""drop-and-create""/>
<property name=""javax.persistence.schema-generation.scripts.create-target"" value=""/tmp/create-sql.ddl""/>
<property name=""javax.persistence.schema-generation.scripts.drop-target"" value=""/tests/drop-sql.ddl""/>
<property name=""hibernate.flushMode"" value=""FLUSH_AUTO"" />
<property name=""hibernate.hbm2ddl.auto"" value=""none"" />
</properties>
</persistence-unit>
</persistence>The <properties> element is a container of <property> elements that configure a name and value pair. In the preceding example, the standard properties are prefixed with javax.persistence. The persistence provider is set to Hibernate JPA and there are a couple of properties defined that are only relevant to that ORM solution, namely
hibernate.flushmode and hibernate.hbm2ddl.auto.
Oracle has reorganized the location of XML Schema Definitions for
Java EE 7. All of the schemas are in present in the link http://xmlns.jcp.org/xml/ns/javaee and effectively they are under the auspices of the Java Community Process. For XML validation of resources like persistence.xml, you can find more information on exact XSD locations at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/index.html.
JPA 2.1 specification defines a set of standard properties that allows the application to optionally generate schemas or execute scripts in connection to the data source. The <properties> element in the persistence.xml file specifies both standard and vendor specific properties.
Here is a table of the JPA 2.1 properties; the property must be prefixed with javax.persistence to complete the correct name:
As an alternative to annotations on entities, JPA supports object-relational mapping from an XML. The file is called
orm.xml that is located in the /META-INF folder of the persistence unit. Developers can also explicitly name the XML mapping file using the mapping-file element. The XML representation can be useful for third-party library entities that predate annotation capabilities in Java SE 5 and where the business has no control of the source code access.
Here is a persistence unit that illustrates the concept:
<persistence version=""2.1"" ... >
<persistence-unit name=""legacyTrading"" transaction-type=""JTA"">
<jta-data-source>jdbc/legacyDB</jta-data-source>
<mapping-file>my-orm.xml</mapping-file>
<jar-file>LegacyTradeEntities.jar</jar-file>
<class>com.fxtradelib.Trade.class</class>
<class>com.fxtradelib.Order.class</class>
<class>com.txtradelib.Counterpart.class</class>
</persistence-unit>
</persistence>The jar-file element indicates that the persistence provider also searches the additional JAR file for managed persistence entities. The class element explicitly identifies provider Java types that are entity classes, embeddable classes, and mapped super classes.