|Home > Documentation > User's guide > Deployment > persistence.xml|
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.
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.
In Java EE, the root of a persistence unit can be one of the following
The location of the managed persistence classes can be as follows.
The persistence.xml file is placed in the META-INF directory of the root of the persistence unit.
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.
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.
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 .
2. The below annotation injects EntityManagerFactory object that corresponds to Account
persistence unit to the variable emf. From the emf, the EntityManager object can be created.
This attribute can have the following values.
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.
2. The below declaration is for a persistence unit named Account and the transaction type is
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 in the application.
The description element provides optional descriptive information about the persistence unit.
1. The below XML content illustrate the use of the element.
The provider element specifies the name of the persistence provider's
javax.persistence.spi.PersistenceProvider class. The provider element must be specified if the application is dependent upon a particular persistence provider being used. The provider class supplies EntityManagers for this persistence unit.
1. The below XML content illustrate the use of the element.
For OpenJPA, the value of the provider is org.apache.openjpa.persistence.PersistenceProviderImpl.
In Java EE environments, the jta-data-source and non-jta-data-source elements are used to specify the global JNDI name of the JTA and non-JTA data source respectively to be used by the persistence provider. If neither is specified, the deployer must specify a JTA data source at deployment or a JTA data source must be provided by the container, and a JTA EntityManagerFactory will be created to correspond to it. These elements name the data source in the local environment. The format/syntax of these names and the ability to specify the names are product specific. In Java SE environments, these elements may be used or the data source information may be specified by other means; depending upon the requirements of the provider.
In the geronimo server, users can deploy datasources (database connection pools) on databases from various vendors like DB2, Oracle, MySQL, MS-SQLServer etc,. When creating a datasource, users have to specify the datasource name in the deployment plan. The name given to the datasource is to be provided in the jta-data-source and non-jta-data-source elements. The below XML fragment illustrates the usage.
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.
An object/relational mapping XML file contains mapping information for the classes listed in it. The mapping files can be provided as follows.
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.
The object_mappings.xml file must be in the classpath of the application.
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.
The account-entities.jar is placed at the root of the persistence unit.
The following classes must be implicitly or explicitly denoted as managed persistence classes to be
included within a persistence unit.
The set of managed persistence classes that are managed by a persistence unit is defined by using one or
more of the following:
In the Java SE environment, the following rules and recommendations are required to be followed.
The following procedure explains how managed persistence classes are searched.
The following XML fragment illustrate the use of class element.
The sample.jpa.Account and sample.jpa.Person are explicitly mentioned as managed persistence classes in the persistence.xml.
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.
Only account-entities.jar, sample.jpa.Account and sample.jpa.Person are scanned for managed persistence classes.
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.
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
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.
The AccountUnit can be overridden in openejb-jar.xml as follows.
The AccountUnit is overridden in openejb-jar.xml to use the JTA datasource AccountDS1. In the persistence.xml, it was declared to use the JTA datasource AccountDS.
Similarly, the persistence-units can be overridden in geronimo-web.xml right after the <sys:environment> declaration.