...

<persistence-unit name="Account" transaction-type="JTA">
  <description>ContainerManagedJPA</description>
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
  <jta-data-source>AccountDB2DataSource</jta-data-source>
  ...
  ...
</persistence-unit>

<mapping-file>

An object/relational mapping XML file contains mapping information for the classes listed in it. The mapping files can be provided as follows.

• Object/relational mapping XML file named orm.xml may be specified in the META-INF directory in the root of the
  persistence unit.

• Object/relational mapping XML file named orm.xml may be specified in the META-INF directory of any jar file
  referenced by the persistence.xml.

• In addition, other mapping files may be referenced by the mapping-file elements of the persistence-unit
  element, and may be present anywhere on the classpath.

The non-jta-datasource must be a datasource that has no transaction support. It can be deployed on the geronimo server by using the <no-transaction/> element instead of <local-transaction/> or <xa-transaction> in the connector plan as illustrated below.

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
...
...
 <resourceadapter>
 ...
 ...
  <connectionmanager>
   <local-transaction/>
    <no-transaction/>
     <max-size>10</max-size>
     <min-size>0</min-size>
     <match-one/>
    </single-pool>
  </connectionmanager>
 ...
 ...
 </resourceadapter>
...
...
</connector>

<mapping-file>

An object/relational mapping XML file contains mapping information for the classes listed in it. The mapping files can be provided as follows.

• Object/relational mapping XML file named orm.xml may be specified in the META-INF directory in the root of the
  persistence unit.

• Object/relational mapping XML file named orm.xml may be specified in the META-INF directory of any jar file
  referenced by the persistence.xml.

• In addition, other mapping files may be referenced by the mapping-file elements of the persistence-unit
  element, and may be present anywhere on the classpath.

An orm.xml file or other mapping file is loaded as a resource by the persistence provider. If a mapping file is specified, the classes and mapping information specified in the mapping file will be used. If multiple mapping files are specified (possibly including one or more orm.xml files), the resulting mappings are obtained by combining the mappings from all of the files. The result is undefined if multiple mapping files (including any orm.xml file) referenced within a single persistence unit contain overlapping mapping information for any given class. The below XML fragment illustrates the usage.

<persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<non-jta-data-source>ProductDS-nonJTA</non-jta-data-source>
<mapping-file>object_mappings.xml</mapping-file>
     ...
     ...
</persistence-unit>

<jar-file>

One or more JAR files may be specified using the jar-file elements instead of, or in addition to the mapping files specified in the mapping-file elements. If specified, JPA processes these jar files as follows.

• These JAR files will be searched for managed persistence classes, and any mapping metadata annotations found on them will be processed.

• They will be mapped using the mapping annotation defaults defined by the JPA specification. JAR files are specified relative to the root of the persistence unit.

• A list of named managed persistence classes may also be specified instead of, or in addition to, the JAR files and mapping files (using class xml element explained below). Any mapping metadata annotations found on these classes will be processed, or they will be mapped using the mapping annotation defaults. The following XML fragment illustrates the usage.

  Note

  Code Block XML XML borderStyle solid <persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL"> <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> <jta-data-source>AccountDS</jta-data-source> <mapping-file>account_mappings.xml</mapping-file> <jar-file>account-entities.jar</jar-file> ... ... </persistence-unit> The account-entities.jar is placed at the root of the persistence unit.

<Class>

The following classes must be implicitly or explicitly denoted as managed persistence classes to be
included within a persistence unit.

• Entity classes
• Embeddable classes
• Mapped superclasses.

The set of managed persistence classes that are managed by a persistence unit is defined by using one or
more of the following:

• One or more object/relational mapping XML files (explained in mapping-file section above).
• One or more jar files that will be searched for classes explained in jar-file section above).
• An explicit list of the classes (using class element).
• The annotated managed persistence classes contained in the root of the persistence unit
  (unless the exclude-unlisted-classes element is specified)

In the Java SE environment, the following rules and recommendations are required to be followed.

• The class element is used to list a managed persistence class. A list of all named managed persistence classes must be specified in Java SE environments to insure portability.
• Portable Java SE applications should not rely on the other mechanisms described here to specify the managed persistence classes of a persistence unit.
• Persistence providers may also require that the set of entity classes that are to be managed must be fully enumerated in persistence.xml.

The following procedure explains how managed persistence classes are searched.

• All classes contained in the root of the persistence unit are also searched for annotated managed persistence classes and any mapping metadata annotations found on them will be processed, or they will be mapped using the mapping annotation defaults.
• If it is not intended that the annotated persistence classes contained in the root of the persistence unit be included in the persistence unit, the exclude-unlisted-classes element should be used.

• The exclude-unlisted-classes element is not intended for use in Java SE environments.

• The resulting set of entities managed by the persistence unit is the union of these sources, with the mapping metadata annotations (or annotation defaults) for any given class being overridden by the XML mapping information file if there are both annotations as well as XML mappings for that class.

• The minimum portable level of overriding is at the level of the persistent field or property.

• The classes and/or jars that are named as part of a persistence unit must be on the classpath. Referencing them from the persistence.xml file does not cause them to be placed on the classpath.

• All classes must be on the classpath to ensure that entity managers from different persistence units that map the same class will be accessing the same identical class.

The following XML fragment illustrate the use of class element.

<persistence-unit name="AccountUnit" transaction-type="JTA">
  <description>ContainerManagedJPA</description>
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
  <jta-data-source>AccountDS</jta-data-source>
  <class>sample.jpa.Account</class>
  <class>sample.jpa.Person</class>
  ...
  ...
</persistence-unit> 

<exclude-unlisted-classes>

When set to true, only listed classes and jars will be scanned for persistent classes. Otherwise the enclosing jar or directory will also be scanned. This is not applicable to Java SE persistence units. The following XML fragment illustrate the use of exclude-unlisted-classes elementAn orm.xml file or other mapping file is loaded as a resource by the persistence provider. If a mapping file is specified, the classes and mapping information specified in the mapping file will be used. If multiple mapping files are specified (possibly including one or more orm.xml files), the resulting mappings are obtained by combining the mappings from all of the files. The result is undefined if multiple mapping files (including any orm.xml file) referenced within a single persistence unit contain overlapping mapping information for any given class. The below XML fragment illustrates the usage.

<persistence-unit name="TutorialAccountUnit" transaction-type="RESOURCE_LOCAL">
"JTA">
  <description>ContainerManagedJPA</description>
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<non-jta  <jta-data-source>ProductDS-nonJTA<source>AccountDS</non-jta-data-source>
<mapping-file>object_mappings.xml</mapping  <jar-file>account-entities.jar</jar-file>
     <class>sample.jpa..Account</class>
     ...
</persistence-unit>

<jar-file>

One or more JAR files may be specified using the jar-file elements instead of, or in addition to the mapping files specified in the mapping-file elements. If specified, JPA processes these jar files as follows.

• These JAR files will be searched for managed persistence classes, and any mapping metadata annotations found on them will be processed.

• They will be mapped using the mapping annotation defaults defined by the JPA specification. JAR files are specified relative to the root of the persistence unit.

...

<class>sample.jpa.Person</class>
  <exclude-unlisted-classes>true</exclude-unlisted-classes>
  ...
  ...
 </persistence-unit> 

<properties>

• The properties element is used to specify vendor-specific properties that apply to the persistence unit and its entity manager factory configuration.
• If a persistence provider does not recognize properties (other than those defined by this specification), the provider will ignore those properties.
• Vendors will use vendor namespaces for properties.

The following XML fragment illustrate the use of properties element. The specified properties and the values enable JPA to connect to VehicleDB database created in the embedded derby of geronimo server.

<persistence-unit name="Inheritence">
 <description>Single Table Inheritence example</description>
 <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
 <class>com.jpa.RoadVehicle</class>
 <class>com.jpa.Car</class>
 <class>com.jpa.Coupe</class>
 <class>com.jpa.Motorcycle</class>
 <class>com.jpa.Roadster</class>
 <properties>
   <property name="openjpa.ConnectionURL" value="jdbc:derby:VehicleDB" />
   <property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver" />
   <property name="ConnectionUserName" value="app" />
   <property name="openjpa.jdbc.SynchronizeMappings" value="false" />
 </properties>
</persistence-unit>

JPA configuration and geronimo plans

The persistence.xml file can declare more than one persistence-units. A persistence-unit declaration in the persistence.xml can be overridden in geronimo plans (geronimo-web.xml or openejb-jar.xml) as follows.

• If a persistence-unit is declared in both in persistence.xml as well as in a geronimo plan
  (geronimo-web.xml or openejb-jar.xml), the declaration in the geronimo plan will override the declaration
  in the persistence.xml

• The below example illustrate the overriding feature in geronimo

...

<persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL">
 <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
 <jta-data-source>AccountDS</jta-data-source>
 <mapping-file>account_mappings.xml</mapping-file>
 <jar-file>account-entities.jar</jar-file>
  ...
  ...
</persistence-unit>

The account-entities.jar is placed at the root of the persistence unit.

<Class>

The following classes must be implicitly or explicitly denoted as managed persistence classes to be
included within a persistence unit.

• Entity classes
• Embeddable classes
• Mapped superclasses.

The set of managed persistence classes that are managed by a persistence unit is defined by using one or
more of the following:

• One or more object/relational mapping XML files (explained in mapping-file section above).
• One or more jar files that will be searched for classes explained in jar-file section above).
• An explicit list of the classes (using class element).
• The annotated managed persistence classes contained in the root of the persistence unit
  (unless the exclude-unlisted-classes element is specified)

In the Java SE environment, the following rules and recommendations are required to be followed.

• The class element is used to list a managed persistence class. A list of all named managed persistence classes must be specified in Java SE environments to insure portability.
• Portable Java SE applications should not rely on the other mechanisms described here to specify the managed persistence classes of a persistence unit.
• Persistence providers may also require that the set of entity classes that are to be managed must be fully enumerated in persistence.xml.

The following procedure explains how managed persistence classes are searched.

• All classes contained in the root of the persistence unit are also searched for annotated managed persistence classes and any mapping metadata annotations found on them will be processed, or they will be mapped using the mapping annotation defaults.
• If it is not intended that the annotated persistence classes contained in the root of the persistence unit be included in the persistence unit, the exclude-unlisted-classes element should be used.

• The exclude-unlisted-classes element is not intended for use in Java SE environments.

• The resulting set of entities managed by the persistence unit is the union of these sources, with the mapping metadata annotations (or annotation defaults) for any given class being overridden by the XML mapping information file if there are both annotations as well as XML mappings for that class.

• The minimum portable level of overriding is at the level of the persistent field or property.

• The classes and/or jars that are named as part of a persistence unit must be on the classpath. Referencing them from the persistence.xml file does not cause them to be placed on the classpath.

• All classes must be on the classpath to ensure that entity managers from different persistence units that map the same class will be accessing the same identical class.

...

• .

<persistence-unit name<?xml version="AccountUnit1.0" transaction-typeencoding="JTAUTF-8">
  <description>ContainerManagedJPA</description>
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
  <jta-data-source>AccountDS</jta-data-source>
  <class>sample.jpa.Account</class>
  <class>sample.jpa.Person</class>
  ...
  ...
</persistence-unit> 

<exclude-unlisted-classes>

When set to true, only listed classes and jars will be scanned for persistent classes. Otherwise the enclosing jar or directory will also be scanned. This is not applicable to Java SE persistence units. The following XML fragment illustrate the use of exclude-unlisted-classes element.

?>

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

 <persistence-unit name="AccountUnit" transaction-type="JTA">
  <description>ContainerManagedJPA</description>
  <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
  <jta-data-source>AccountDS</jta-data-source>
  <class>sample.jpa.Account</class>
   <jar-file>account-entities.jar</jar-file>
  <class>sample.jpa.Account</class>
  <class>sample.jpa.Person</class>
  <exclude-unlisted-classes>true</exclude-unlisted-classes>
  ...
  ...
 </persistence-unit> 

<properties>

• The properties element is used to specify vendor-specific properties that apply to the persistence unit and its entity manager factory configuration.
• If a persistence provider does not recognize properties (other than those defined by this specification), the provider will ignore those properties.
• Vendors will use vendor namespaces for properties.

The following XML fragment illustrate the use of properties element.

The above properties are specific to OpenJPA provider. The OpenJPA provider reads these properties and creates appropriate EntityManagerFactory. The properties supported by OpenJPA is at this link

<class>sample.jpa.Person</class>
 </persistence-unit>

</persistence>

<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2" 
 xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2" 
 xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" 
 xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">
 
 <sys:environment>

  <sys:moduleId>
   <sys:groupId>ContainerManagedJPA</sys:groupId>
   <sys:artifactId>EJB</sys:artifactId>
   <sys:version>1.0</sys:version>
   <sys:type>car</sys:type>
  </sys:moduleId>

 <dependencies>
  <dependency>
   <groupId>console.dbpool</groupId>
   <artifactId>AccountDS1</artifactId>
  </dependency>
 </dependencies>

 </sys:environment>

 <persistence xmlns="http://java.sun.com/xml/ns/persistence">
  <persistence-unit name="AccountUnit" transaction-type="JTA">
   <description>ContainerManagedJPA</description>
   <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
   <jta-data-source>AccountDS1</jta-data-source>
   <class>sample.jpa.Account</class>
   <class>sample.jpa.Person</class>
  </persistence-unit>
 </persistence>
 
 <enterprise-beans/>

</openejb-jar>

<persistence-unit name="Inheritence">
 <description>Single Table Inheritence example</description>
 <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
 <class>com.jpa.RoadVehicle</class>
 <class>com.jpa.Car</class>
 <class>com.jpa.Coupe</class>
 <class>com.jpa.Motorcycle</class>
 <class>com.jpa.Roadster</class>
 <properties>
   <property name="openjpa.ConnectionURL" value="jdbc:derby:VehicleDB" />
   <property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver" />
   <property name="ConnectionUserName" value="app" />
   <property name="openjpa.jdbc.SynchronizeMappings" value="false" />
 </properties>
</persistence-unit>