Develop JPA 2.x applications for a Java EE environment

Develop JPA 2.x applications for a Java EE environment

Containers in the application server can provide many of the necessary functions for the Java Persistence API (JPA) in a Java Enterprise Edition (Java EE) environment. The application server also provides JPA command tools to assist with developing applications in a Java EE environment.

When we use these JPA command tools, to make sure that we have the latest version of the commands for our release level, run them from...
< profile_root>/bin

...rather than from...
app_server_root/bin

For this task, specify the com.ibm.ws.jpa-2.1.thinclient_9.0.jar stand-alone JAR file in the classpath for compiling against JPA 2.1 interfaces. To compile against JPA 2.0 interfaces, specify the com.ibm.ws.jpa-2.0.thinclient_9.0.jar. This stand-alone JAR file is available from the installation images. The location of these files on the server installation image is in...
${app_server_root}/runtimes

JPA applications require different configuration techniques from applications that use container-managed persistence (CMP) or bean-managed persistence (BMP). They do not follow the typical deployment techniques associated with applications that implement CMP or BMP. In JPA applications, define a persistence unit and configure the appropriate properties to ensure that the applications can run in a Java EE environment.
The container supports all necessary injections to ensure that applications run in the Java EE environment. For example, the container can inject the @PersistenceUnit and @PersistenceContext for the applications.

Tasks
Generate entities classes.
These are Plain Old Java Object (POJO) entities. Depending upon the development model, we might use some or all of the JPA tools:

Top-down mapping Start from scratch with the entity definitions and object-relational mappings, and then derive the database schemas from that data. If we use this approach, we are most likely concerned with creating the architecture of our object model and then writing entity classes. These entity classes would eventually drive the creation of our database model. If we are using a top-down mapping of the object model to the relational model, develop the entity classes and then use Your JPA provider's functionality to generate the database tables that are based on the entity classes. The wsmapping tool helps with this approach when we use OpenJPA as the persistence provider.
Bottom-up mapping Start with a data model, which are the (database schemas), and then work upwards to the entity classes. The wsreversemapping tool helps with this approach when we use OpenJPA as the persistence provider.
Meet in the middle mapping Most common development model. We have a combination of the data model and the object model partially complete. Depending on the goals and requirements, we must negotiate the relationships to resolve any differences. Both the wsmapping tool and the wsreversemapping tool help with this approach when we use OpenJPA as the persistence provider.

The JPA solution for the application server provides several tools that help with developing JPA applications. Combining these tools with IBM Rational Application Developer provides a solid development environment for either Java EE or Java SE applications. Rational Application Developer includes GUI tools to insert annotations, a customized persistence.xml file editor, a database explorer, and other features. Another alternative is the Eclipse Dali project.
Compile the entity classes.
Compile the entities as we would any Java class, unless we are using the Criteria API. If we are using the Criteria API, we must also generate the Criteria API metamodel classes.

The following are examples of how we use this option.

Use EclipseLink, provide the following arguments with the javac command:
-processor org.eclipse.persistence.internal.jpa.modelgen.CanonicalModelProcessor 
-Aeclipselink.persistencexml=persistence.xml_location 
For example...
app_server_root/java/bin/javac -classpath app_server_root/runtimes/com.ibm.ws.jpa-2.1.thinclient_9.0.0.jar 
                               -processor org.eclipse.persistence.internal.jpa.modelgen.CanonicalModelProcessor 
                               -Aeclipselink.persistencexml=app_location/src/META-INF/persistence.xml 
                                mypackage\MyEntity.java 
Use OpenJPA or WSJPA, provide the following arguments with the javac command:
-Aopenjpa.metamodel=true 
For example...
app_server_root/java/bin/javac -Aopenjpa.metamodel=true 
                               -classpath app_server_root/runtimes/com.ibm.ws.jpa-2.0.thinclient_9.0.0.jar  
                                mypackage/MyEntity.java 
Enhance the entity classes using the JPA enhancer tool, eclenhancer for EclipseLink and wsenhancer for OpenJPA.
An enhancer is a tool that adds provider-specific integration bytecode to your persistent classes after we have written them. The enhancer post-processes the bytecode generated by the Java compiler and adds the fields and methods necessary to implement the persistence features. Although the application server's persistence provider can automatically enhance the entities at run time, you obtain better performance if we can enhance your entities when you build the application. The application does not attempt to enhance entities that are already enhanced.
Optional: If we are not using the development model for bottom-up mapping, generate or update our database tables automatically or using the eclenhancer or wsmapping tool.
By default, the object-relational mapping does not occur automatically, but we can configure the application server to provide that mapping with the eclipselink.ddl-generation property for EclipseLink, or the openjpa.jdbc.SynchronizeMappings property for OpenJPA. These properties can accelerate development by automatically ensuring that the database tables match the object model. To enable automatic mapping, include the following line in the persistence.xml file:
For EclipseLink:
<property name="eclipselink.ddl-generation" value ="create-tables"/> 
For OpenJPA:
<property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>  
JPA 2.1 standard:
<property name="javax.persistence.schema-generation.database.action" value="create"/>  
To enable automatic object-relational mapping at run time, all of our persistent classes must be listed in the Java .class file, mapping file, and JAR file elements in XML format.
To manually update or generate the database tables, run the JPA mapping tool for the application server from the command line to create the tables in the database.
Optional: If we are using DB2 and want to use static Structured Query Language (SQL), run the wsdbgen command.
To use the wsdbgen command, IBM Optim pureQuery Run time must be installed. The wsdbgen command creates the persistence_unit_name.pdqxml file under the same META-INF directory where your persistence.xml file is located. If we have multiple persistence units, the wsdbgen command must be run for each persistence unit.
When multiple pdqxml files are referenced by an application, use the Merge utility to combine them into a single pdqxml file. Specify the combined pdqxml file as pureQueryXml property of pdqProperties.
Applications that implement the JPA and are configured to run static SQL can experience various exceptions. These exceptions might occur with the wsdbgen command, which we can use to prepare the application, or when the application is running and calls a JPA method. To resolve this problem:

Install the program temporary fixes (PTF) for the iSeries JDBC Driver V5R4.
Install PTF numbers SI32561 and SI32562. We can find the PTFs through the IBM System i Support: PTF Cover Letters website.
If we use DB2 Universal Database for iSeries V6R1 or V5R3, visit the fix website for the appropriate release.
Install the required level of pureQuery, which is Version 1.3.100 or later.
See IBM Optim pureQuery Runtime website. Install the latest JCC driver, which is Version 3.52.95 or later, with the fix for APAR PK65069. The latest JCC drivers are part of the IBM DB2 software package.
For DB2 on a z/OS server, install PTF UK39204 for the V8 alternate driver or PTF UK39205 for V9, and install the fix for APAR PK67706.

Optional: If we are using OpenJPA and application-managed identity, generate an application-managed identity class with the wsappid tool.
When we use an application-managed identity, one or more of the fields must be an identity field. Use an identity class if your entity has multiple identity fields and at least one of the fields is related to another entity. The application-managed identity tool generates Java code that uses the identity class for any persistent type that implements application-managed identity.
Example
The following is an example of a persistence.xml file:
<?xml version="1.0" encoding="UTF-8"?> 
<persistence xmlns="http://java.sun.com/xml/ns/persistence" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.1" 
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd" ">
 	  
<persistence-unit name="TheWildZooPU" transaction-type="JTA">
        <jta-data-source>jdbc/DataSourceJNDI</jta-data-source>
        <!-- additional Mapping file, in addition to orm.xml>
        <mapping-file>META-INF/JPAorm.xml</mapping-file>

        <class>com.company.bean.jpa.PersistebleObjectImpl</class>
        <class>com.company.bean.jpa.Animal</class>
        <class>com.company.bean.jpa.Dog</class>
        <class>com.company.bean.jpa.Cat</class>

        <properties>
             <property name="eclipselink.ddl-generation"
                       value="create-tables"/> 
			
        </properties>

     </persistence-unit>
</persistence>
Next topic: wsreversemapping command

Related:

Development and assembly tools
Associating persistence providers and data sources
Configure a JDBC provider and data source
Troubleshoot JPA applications
IBM Optim pureQuery Runtime
Configure pureQuery to use multiple DB2 package collections
Configure JDBC providers to use pureQuery to access DB2
wsappid command
wsenhancer command
wsjpaversion command
wsmapping command
wsschema command
wsdbgen command
ANT task WsJpaDBGenTask
Criteria API
Merge utility
Dynamic, typesafe queries in JPA 2.0
IBM System i: PTF Cover Letters
IBM Support: Fix Central for DB2 UDB for iSeries V6R1
Dali Java Persistence Tools

Top-down mapping	Start from scratch with the entity definitions and object-relational mappings, and then derive the database schemas from that data. If we use this approach, we are most likely concerned with creating the architecture of our object model and then writing entity classes. These entity classes would eventually drive the creation of our database model. If we are using a top-down mapping of the object model to the relational model, develop the entity classes and then use Your JPA provider's functionality to generate the database tables that are based on the entity classes. The wsmapping tool helps with this approach when we use OpenJPA as the persistence provider.
Bottom-up mapping	Start with a data model, which are the (database schemas), and then work upwards to the entity classes. The wsreversemapping tool helps with this approach when we use OpenJPA as the persistence provider.
Meet in the middle mapping	Most common development model. We have a combination of the data model and the object model partially complete. Depending on the goals and requirements, we must negotiate the relationships to resolve any differences. Both the wsmapping tool and the wsreversemapping tool help with this approach when we use OpenJPA as the persistence provider.