Most of us have been dealing with JARs, WARs and EARs for many years and most of confusions surrounding packaging are past behind us. Birth of a new archive "PAR" (persistence archive file) has taken place with the release of EJB3 Public draft. I thought it is a good time to blog about the PAR module and get feedback from user communities what they feel about this. A PAR is essentially another JAR module meant for packaging a persistence unit or EJB3 entities. A PAR may contain the entity classes or references other JAR files that contain the classes.
The layout of a PAR looks like:
META-INF/
Manifest.mf (Class-path may include another jar file that includes entities classes)
persistence.xml
HRmapping.xml
Managed Classes
A persistence archive can be used either inside or outside a J2EE container. When using a persistence module inside an EAR file, the standard deployment descriptor application.xml must include the persistence module as in the following example:
<module>
<persistence>myHRApp.par</persistence>
</module>
The PAR deployment descriptor, persistence.xml, provides the configuration for persistence modules such as EM name, persistence provider class, DataSource, persistence classes or jar files and optional O-R mapping file if O-R mapping is expressed using XML.
<entity-manager>
<name>HRem</name>
<provider>oracle.toplink.persistence</provider>
<jta-data-source>java:comp/env/jdbc/hrDS</jta-data-source>
<mapping-file>HRmapping.xml</mapping-file>
<jar-file>HRApp.jar</jar-file>
</entity-manager>
If no name is specified in the persistence.xml for EntityManager then the container assigns a default value. The default value for EntityManager is the name of the PAR file without the .par extension. The name determines how the EntityManager instance is looked up or injected as a resource from applications using entities in the persistence module.
The provider element in the persistence.xml defines the persistence provider's implementation class for javax.persistence.spi.PersistenceProvider class and hence provides plug-ability of persistence engine with third-party J2EE containers. For example, many customers use Oracle TopLink CMP engine with Weblogic and Websphere and this integration are provided by TopLink in a proprietary manner. It will provide persistence providers like Oracle TopLink, JBoss Hibernate, JDO vendors implementing EJB3 persistence API to plug-into third-party application servers in a standardized manner.
The mapping file e.g. HRmapping.xml defines the O-R mapping in a standard manner using XML should you decide not to use metadata annotations. However you can mix-n-match annotations with XML e.g. you can define some Entities using annotations and some with XML. XML descriptor becomes the final source of truth for a persistent object and overrides the definition in the annotations.
The persistence.xml may have empty elements. See the persistence API doc of the EJB3 Public Draft for additional examples of the persistence.xml.
If a PAR file is deployed in a J2EE container the container discovers persistence archives and processes the persistence.xml. The container uses the PersistenceProvider SPI (createContainerEntityManagerFactory) provided by the persistence provider such as Oracle TopLink to create instance an instance of EntityManager.
If the persistence module is used by an application outside any Java EE container e.g. Java SE, the application makes call to the Persistence.createEntityManagerFactory to create an entity manager instance. The persistence provider is responsible to read the descriptors for the PAR files.
I found the definitions in the PAR, persistence.xml and mapping descriptors straight forward and simple and I'm hoping PAR file concept will not be overwhelming for developers and will not deter users to use the simplified Java persistence API.
EJB3 Resources
EJB3 Public draft
Oracle EJB3 Resource Center
5:31:29 AM 
|
