4.3 Configuring Persistence Units

The persistence.xml file is a descriptor that declares that a .jar file is a persistence archive file containing JPA entities. The persistence.xml file is located in each entity project, in the Application Sources folder within the META-INF directory, as shown in Figure 4-1:

Figure 4-1 Location of the persistance.xml file in its project

Within this file, there are one or more <persistence-unit> entries defined. Each persistence-unit identifies a subset (possibly all) of the entities included in the deployed JAR file, which may be a dedicated persistence archive, an EJB JAR file, or a WAR file. The persistence unit associates metadata with this entity group, including a named entity manager. The entity manager is covered in Section 4.5, "Accessing Entities from a Session Bean".

The same entity can appear in multiple persistence units, but hold different mapping behavior in each one. In addition to defining the entity classes that it represents, the persistence-unit defines its datasource information (when overriding the default connection) and any of a number of platform-specific properties. A common need for creating separate persistence units is to run the same entities both inside and outside the Java EE container. Testing EJBs outside the container is covered in Section 4.8.1, "Testing Entities Outside the Container with a Java Service Facade".

4.3.1 How to Create a Persistence Unit

To create a persistence unit, use the Create Persistence Unit dialog.

The Create Persistence Unit dialog lets you create persistence-units that are configured to run either inside or outside a Java EE container. When running inside a Java EE container, the unit can be associated with a JTA (Java Transaction API) datasource, which lets the entities participate in distributed transactions. The <jta-data-source> must be defined in the server. This may be defined in a data-sources.xml file provided during deployment, or deployed with the persistence unit, or it could have been pre-configured on the server. When running outside the container, entities can't participate in JTA transactions, so the properties that identify the datasource connection are defined explicitly.

To create a a persistence unit:

1. In the Navigator, right click the persistence.xml file and choose New Persistence Unit.

2. Enter the appropriate information in the Create Persistence Unit dialog. Click Help in the dialog or press the F1 key if you need more information.

3. Click OK to save your changes.

4.3.2 How to Edit a Persistence Unit

In JDeveloper 10.1.3.1, the easiest way to modify a persistence unit is to browse it in the Structure pane and modifiy it in the property inspector. However, if you want to edit an existing persistence unit by hand, you may do so by editing the XML code.

In the Navigator, double click the persistence.xml file to open it in the editor. Use the persistence.xml file from the SOA Order Booking application shown in Example 4-2 as sample code.

Example 4-2 persistence.xml file

<?xml version="1.0" encoding="windows-1252" ?>
<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
             xmlns="http://java.sun.com/xml/ns/persistence">
  <persistence-unit name="customerServiceUnit">   
<provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provider>
    <jta-data-source>jdbc/soademoDS</jta-data-source>
  </persistence-unit>
</persistence>