The tags listed in the following table are specified under the <persistence-unit> tag.
Table 5-7 Tags 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:
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.
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.
The following table describes the priority for determining the JPA provider used in the persistence unit.
Table 5-8 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) |
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:
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.
Table 5-9 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 |
The following two methods are available for specifying the entity class, embeddable class, mapped superclass included in the persistence unit:
A description of method 1 is as follows:
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.
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:
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:
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.
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.
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.