8.11.2 Reference scope of the persistence unit name
The components, such as the EJBs and servlets, included in the application, reference the used persistence unit by specifying the persistence unit name in the unitName attribute of @PersistenceUnit and @PersistenceContext and in the <persistence-unit-name> tag under the <persistence-context-ref> tag or under the <persistence-unit-ref> tag defined in the DD. However, the persistence unit scope that can be referenced from each component is as follows:
-
The persistence units defined in the EJB-JARs or WARs can be referenced from the components included in the EJB-JARs or WARs.
-
The persistence unit defined in the EAR file can be referenced from all the components included in the EAR file.
If the name of the persistence unit defined in the EAR file and the name of the persistence unit defined in the EJB-JARs or WARs are duplicated, from the components in the EJB-JAR or WAR, the persistence units defined with a narrower scope are given priority. For example, if persistence units with the same name are defined in the EAR and WAR files, from the components included in the WAR file, the persistence unit defined in the WAR file is visible on priority. The persistence unit existing in the EAR file is not visible.
- Organization of this subsection
(1) Persistence unit used when the persistence unit name is omitted
If you omit the persistence unit name referenced by the components when the JPA is used with Application Server, the persistence unit used is determined with the following rules:
-
If only one persistence unit is defined in the EJB-JAR or WAR that contains components, that persistence unit is used.
-
If persistence unit is not defined in the EJB-JAR or WAR that contains components and only one persistence unit is defined in the EAR, the persistence unit in the EAR is used.
Note that if the following conditions are fulfilled, one persistence unit cannot be identified, so the persistence unit name cannot be omitted:
-
When two or more persistence units are defined in the EJB-JAR or WAR that contains components
-
If persistence unit is not defined in the EJB-JAR or WAR that contains components and two or more persistence units are defined in the EAR
(2) Explicitly referencing the EAR-level persistence unit using # syntax
If the name of the persistence unit defined in the EAR and the name of the persistence unit defined in the EJB-JAR or WAR are duplicated, from the components in the EJB-JAR or WAR, the persistence units defined with a narrower scope are visible on priority. However, by using # syntax in the reference name of the persistence unit, you can explicitly reference the persistence unit defined in the EAR. When you use # syntax, specify the persistence unit name as follows:
Relative-path-from-the-EJB-JAR-or-WAR-containing-components-to-the-persistence-unit-root#Name-of-the-persistence-unit
For example, when the persistence unit myPersistenceUnit included in lib/persistenceUnitRoot.jar of the EAR file is referenced from the EJB included in ejbs/myEjbs.jar of the EAR file, the referenced persistence unit name is ../lib/persistenceUnitRoot.jar#myPersistenceUnit.