You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Overview

The persistence.xml file describes persistence units. It is the deployment descriptor file for persistence using Java Persistence API (JPA). It is used to declare the following.

  • Managed persistence classes.
    The managed classes are, for example, those which are annotated using @Entity, @Embeddable or
    @MappedSuperclass.
  • Specify object/relation mapping.
    JPA provides several mechanisms to map the java classes to tables in a relational database.
  • Configuration information for entity managers and entity manager factory classes.

The persistence.xml file is placed in the META-INF directory of the root of the persistence unit. The object/relational mapping information is provided by the following ways.

  • Annotations on the managed persistence classes
  • One or more XML files contained in the root of the persistence unit
  • One or more XML files outside the root of the persistence unit on the classpath and referenced from the
    persistence.xml, or a combination of these.

In Java EE, the root of a persistence unit can be one of the following

  • EJB-JAR file
  • WEB-INF/classes directory of a WAR file
  • A jar file in the WEB-INF/lib directory of a WAR file
  • A jar file in the root of the EAR
  • A jar file in the EAR library directory
  • An application client jar file

The location of the managed persistence classes can be as follows.

  • Within the root of the persistence unit.
  • Can be specified by reference in the persistence.xml by naming the classes, archives, or mapping XML files
    that are accessible on the application classpath.
  • Some combinations of the above methods.

Packaging

The persistence.xml file is placed in the META-INF directory of the root of the persistence unit.

Schema

The schema of the persistence.xml is at this link. Apache geronimo uses OpenJPA as the JPA provider.

Schema top level elements

The top level element of the persistence.xml is <persistence>. The below sections explain the sub-elements of the <persistence> element. Typical persistence.xml looks like below.

persistence.xml
<?xml version="1.0" encoding="UTF-8"?>
<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>

<persistence-unit>

The <persistence> element can consist of more than one <persistence-unit> element each describing a persistence unit. The persistence-unit element consists of the following attributes.

Attribute : name

This attribute is required. The name attribute defines the name for the persistence unit. It uniquely identifies a persistence context. This name is used to identify a persistence unit referred to by the PersistenceContext and PersistenceUnit annotations. It is also referred while creating an entity manager factory object. The following note illustrates the usage in an application.

1. The below annotation injects EntityManager object that corresponds to Tutorial persistence unit
to the variable em .

  @PersistenceContext(unitName="Tutorial")
  private EntityManager em;

2. The below annotation injects EntityManagerFactory object that corresponds to Account
persistence unit to the variable emf. From the emf EntityManager object can be created. 

@PersistenceUnit(unitName="Account")
private EntityManagerFactory emf;

Attribute : transaction-type

This attribute can have the following values.

  • JTA
  • RESOURCE_LOCAL

The transaction-type attribute is used to specify whether the entity managers provided by the
entity manager factory for the persistence unit must be JTA entity managers or resource-local entity
managers. The value of this element is JTA or RESOURCE_LOCAL. A transaction-type of JTA assumes that a JTA data source will be provided. It is provided either as specified by the jta-data-source element or provided by the container. In general, in Java EE environments, a transaction-type of RESOURCE_LOCAL assumes that a non-JTA datasource will be provided. In a Java EE environment, if this element is not specified, the default is JTA. In a Java SE environment, if this element is not specified, a default of RESOURCE_LOCAL may be assumed.

1. The below declaration is for a persistence unit named Account and the transaction type is JTA. 

<persistence-unit name="Account" transaction-type="JTA">
...
...
</persistence-unit>

2. The below declaration is for a persistence unit named Account and the transaction type is
RESOURCE_LOCAL.

 
<persistence-unit name="Account" transaction-type="RESOURCE_LOCAL">
...
...
</persistence-unit>

Please note that there are two types of entity managers and corresponding persistence contexts. These are container managed entity manager and application managed entity manager.

The container managed entity manager is the one whose persistence context is managed by container. The persistence context is propagated along the active transaction. The persistence scope of the container managed entity manager is transaction by default. The transaction type of the entity manager is always JTA. The EntityManager object is injected by the container to the application.

The application managed entity manager is the one whose persistence context is managed by the application. The persistence context is not propagated along the transaction. The persistence context will be active even after the current transaction completes. The transaction type of the entity manager is RESOURCE_LOCAL by default. The EntityManager object should be created by using EntityManagerFactory object by the application.

  • No labels