8.8.2 Tags specified under the <persistence-unit> tag
The tags listed in the following table are specified under the <persistence-unit> tag.
|
Specified tags |
Settings |
|---|---|
|
<description> tag |
Describes the persistence unit. |
|
<provider> tag |
Specifies the JPA provider used. |
|
<jta-data-source> tag <non-jta-data-source> tag |
Specifies the JTA data source or non-JTA data source used in the JPA provider. |
|
<mapping-file> tag |
Specifies the O/R mapping file used. |
|
<jar-file> tag |
Specifies the name of the JAR file containing the entity class, embeddable class, and mappedsuper class. |
|
<class> tag |
Specifies the entity class, embeddable class, and mappedsuper class. |
|
<exclude-unlisted-classes> tag |
Specifies whether to handle the class as a Persistence class. |
|
<properties> tag |
Specifies the JPA provider-specific properties. |
The following points describe respective tags:
- Organization of this subsection
(1) <description> tag
The user can freely code the explanation about the persistence unit. The contents specified here do not affect the operations of the application. Note that you can omit this tag.
(2) <provider> tag
Specifies the JPA provider used in the persistence unit. You specify the implementation class name of the javax.persistence.spi.PersistenceProvider interface of the JPA provider with the fully qualified name containing the package name. You can omit this tag.
If this tag is omitted, the default JPA provider specified in the Easy Setup definition file is used. Also, when this tag is omitted and the default JPA provider is not specified in the Easy Setup definition file, Cosminexus JPA provider is used as the JPA provider.
If the application depends on a specific JPA provider functionality and behavior, make sure to specify the <provider> tag.
- Tip
-
To specify the default JPA provider in the Easy Setup definition file, specify ejbserver.jpa.defaultProviderClassName in the <param-name> tag of the logical J2EE server and specify the name of the default JPA provider class in the <param-value> tag.
Note that if the ejbserver.jpa.overrideProvider parameter is specified in the <param-name> tag of the logical J2EE server in the Easy Setup definition file, the name of the JPA provider class specified in the <param-value> tag of the ejbserver.jpa.overrideProvider parameter is used on a higher priority than the value specified in the <provider> tag and the ejbserver.jpa.defaultProviderClassName parameter.
For details on the parameters to be specified in the Easy Setup definition file, see 12.2.1 Parameters used for setting up the user properties for the J2EE server.
The following table describes the priority for determining the JPA provider used in the persistence unit.
|
Priority |
JPA provider to be used |
|---|---|
|
1 |
Value specified in ejbserver.jpa.overrideProvider property of the Easy Setup definition file |
|
2 |
Value specified in the <provider> tag of persistence.xml |
|
3 |
Cosminexus JPA provider (The JPA provider can also be changed by using the ejbserver.jpa.defaultProviderClassName parameter of the Easy Setup definition file) |
(3) <jta-data-source> tag and <non-jta-data-source> tag
Specifies the JTA data source or non-JTA data source used by the JPA provider. The value specified here is product-dependent as per the JPA specifications, but define the data source references with Application Server as follows:
-
When referencing a resource adapter conforming to Connector 1.0
Specify the "display-name-of-resource-adapter" or "optional-name-of-resource-adapter".
-
When referencing a resource adapter conforming to Connector 1.5
Specify the "display-name-of-resource-adapter!connection-definition-identifier" or "optional-name-of-resource-adapter".
The specified value is interpreted as "display-name-of-resource-adapter" or "display-name-of-resource-adapter!connection-definition-identifier" and the relevant resource adapter is searched. If the relevant resource adapter does not exist, the specified value is interpreted as "optional-name-of-resource-adapter" and the relevant resource adapter is searched.
The resource adapter to be referenced must be deployed as a J2EE resource adapter (method of deploying the resource adapter as a standalone module). Start the resource adapter before starting the application containing the persistence unit.
You can omit the <jta-data-source> tag and <non-jta-data-source> tag. If the tags are omitted, the value specified in the ejbserver.jpa.defaultJtaDsName parameter or ejbserver.jpa.defaultNonJtaDsName parameter of the Easy Setup definition file is used. However, these properties do not have default values.
If a value is specified in the ejbserver.jpa.overrideJtaDsName parameter or ejbserver.jpa.overrideNonJtaDsName parameter, this value is used on higher priority than the value specified in the <jta-data-source> tag and <non-jta-data-source> tag and the value specified in the ejbserver.jpa.defaultJtaDsName parameter and ejbserver.jpa.defaultNonJtaDsName parameter.
You must specify LocalTransaction or XATransaction in the transaction support level of the resource adapter specified in the <jta-data-source> tag. You must also specify NoTransaction in the transaction support level of the resource adapter specified in <non-jta-data-source>.
The following table lists the priority for determining the JTA data source and non-JTA data source used in the persistence unit.
|
Priority |
JPA provider to be used |
|---|---|
|
1 |
Value specified in the ejbserver.jpa.overrideJtaDsName property or ejbserver.jpa.overrideNonJtaDsName property of the Easy Setup definition file |
|
2 |
Value specified in the <jta-data-source> or <non-jta-data-source> element of persistence.xml |
|
3 |
Value specified in the ejbserver.jpa.defaultJtaDsName property or ejbserver.jpa.defaultNonJtaDsName property of the Easy Setup definition file |
- Important note
-
If a resource adapter display name containing characters other than one-byte alphanumeric characters and underscore (_) is specified in the <jta-data-source> tag or <non-jta-data-source> tag of persistence.xml, replace that character with an underscore (_). However, if the replaced display name is duplicated with another resource adapter display name or optional name, note that the persistence unit might perform operations using an unintended data source.
(4) <mapping-file>, <jar-file>, <class>, and <exclude-unlisted-classes> tag
The following two methods are available for specifying the entity class, embeddable class, mapped superclass included in the persistence unit:
-
Method specified explicitly by using the O/R mapping file and the <class> tag
-
Method that is not specified explicitly and uses auto-search by JPA provider
A description of method 1 is as follows:
(a) Specifying the classes using the O/R mapping file
If an XML file named orm.xml is allocated under META-INF at the persistence unit root or under META-INF in another JAR file referenced with the <jar-file> tag from the persistence unit, the file is automatically handled as an O/R mapping file even if the file is not specified in the <mapping-file> tag. Furthermore, if the name of the XML file that can be loaded on the class path is specified in the <mapping-file> tag, that XML file is also handled as an O/R mapping file. If one persistence unit contains multiple O/R mapping files, the mapping information is read from all the O/R mapping files. However, the operations for duplicate mapping defined between multiple O/R mapping files are not provided.
(b) Specifying the JAR file that searches the persistence class
In the <jar-file> tag, you can specify the JAR file containing the persistence class and O/R mapping file. From the JAR file specified in the <jar-file> tag, the class in which @Entity, @Embeddable, and @MappedSuperclass are added is searched and the mapping information is obtained automatically. If META-INF/orm.xml exists in the specified JAR file, the mapping information is also obtained from orm.xml. Note that you can also use the <jar-file> tag and the <mapping-file> tag together.
The JAR files that can be specified in the <jar-file> tag must be included in the class path. The following JAR files can be specified:
-
JAR file placed in the EAR root
-
JAR file placed in the library directory of the EAR file
-
EJB-JAR
-
JAR file placed in WEB-INF/lib in the WAR
However, you cannot specify the JAR file placed in WEB-INF/lib in the WAR in the <jar-file> tag of the persistence unit defined in the EAR level or EJB-JAR level. This is because the JAR file placed in WEB-INF/lib in the WAR is loaded using the WEB application class loader and, therefore, can only be referenced from the components in the WAR.
Also, you can only specify the JAR file included in the same WAR from the <jar-file> tag of the persistence unit defined in the WAR level. This is because the classes included in the JAR file allocated to a location other than the same WAR might be loaded using the class loader before the deployment of the persistence unit defined in the WAR level. In such cases, the conversion of the byte code by the JPA provider might not be performed correctly.
In the <jar-file> tag, specify the relative path from the persistence unit root to the JAR file. The following is an example of specification:
- Example 1
-
The specification of the relative path shown in the following figure is described below:
![[Figure]](GRAPHICS/ZU140500.GIF)
-
The EAR lib contains myEntities.jar that stores the entity class.
-
Specify myEntities.jar in the <jar-file> tag of META-INF/persistence.xml of EJB-JAR placed in the EAR root.
In this figure, the persistence unit root becomes EJB-JAR, so specify the relative path from EJB-JAR to myEntities.jar. The relative path is lib/myEntities.jar. Therefore, specify lib/myEntities.jar in the <jar-file> tag.
-
- Example 2
-
The specification of the relative path shown in the following figure is described below:
![[Figure]](GRAPHICS/ZU140600.GIF)
-
The EAR root contains myEntities.jar that stores the entity class.
-
Specify myEntities.jar in the <jar-file> tag of META-INF/persistence.xml of lib/myPersistenceUnit.jar in EAR.
In this figure, the persistence unit root becomes myPersistenceUnit.jar, so specify the relative path from myPersistenceUnit.jar to myEntities.jar. The relative path is ../myEntities.jar. Therefore, specify ../myEntities.jar in the <jar-file> tag.
-
- Example 3
-
The specification of the relative path shown in the following figure is described below:
![[Figure]](GRAPHICS/ZU140700.GIF)
-
WEB-INF/lib of the WAR contains myEntities.jar that stores the entity class.
-
Specify myEntities.jar in the <jar-file> tag of WEB-INF/classes/META-INF/persistence.xml of the WAR.
In this figure, the persistence unit root becomes WEB-INF/classes of the WAR, so specify the relative path from WEB-INF/classes to myEntities.jar. The relative path is ../lib/myEntities.jar. Therefore, specify ../lib/myEntities.jar in the <jar-file> tag.
-
(c) Specifying the persistence class list explicitly
If you use the <class> tag, you can explicitly specify the persistence class list. The mapping information is obtained from the annotation added in the specified class. Note that you can also use the <class> tag in combination with the <mapping-file> tag and <jar-file> tag.
(d) Allocating the persistence class with the added annotation to the persistence unit root
From the persistence unit root, the persistence class in which @Entity, @Embeddable, and @MappedSuperclass are added is automatically searched. The mapping information is obtained from the annotation added in the class. If you do not want to add the annotation-added class, which is allocated to the persistence unit root, in the persistence unit, you must specify the <exclude-unlisted-classes> tag beforehand.
(5) <properties> tag
You can specify the vendor-specific properties of the JPA provider. If you specify properties that cannot be understood by the JPA provider, the properties are ignored. Note that you cannot specify properties beginning with javax.persistence in <properties>.
If you specify properties with property names beginning with the prefix ejbserver.jpa.emfprop. as the system properties, the properties with the prefix removed are added in the persistence unit properties.