Develop JPA 2.x applications for a Java SE environment

Develop JPA 2.x applications for a Java SE environment

Prepare persistence applications to test outside of the application server container in a Java SE environment.

When you use these JPA command tools, run them from the profile_root/bin directory, rather than from the app_server_root/bin directory to make sure that we have the latest version of the commands for your release level.
For this task, you must specify the com.ibm.ws.jpa.thinclient_8.0.0.jar stand-alone Java archive (JAR) file in our class path. This stand-alone JAR file is available from the installation images. The location of this file on the server installation image is ${ app_server_root}/runtimes/com.ibm.ws.jpa.thinclient_8.0.0.jar..
Important: Java Persistence API (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 in the persistence.xml file to ensure that the applications can run in a Java SE environment.
There are some considerations for running JPA applications in a Java SE environment:

Resource injection is not available. We must configure these services specifically or programmatically.

The life cycle of the EntityManagerFactory and EntityManager are managed by the application. Applications control the creation, manipulation, and deletion of these constructs programmatically.
Generate the entities classes.
These are Plain Old Java Object (POJO) entities. Depending upon the development model, you might use some or all of the JPA tools:

Top-down mapping

You start from scratch with the entity definitions and the object-relational mappings, and then you derive the database schemas from that data. If we use this approach, you are most likely concerned with creating the architecture of the object model and then writing the entity classes. These entity classes would eventually drive the creation of the database model. For a top-down mapping of the object model to the relational model, develop the entity classes and then use OpenJPA functionality to generate the database tables based on the entity classes. The wsmapping tool would help with this approach.

Bottom-up mapping

You start with the data model, which are the database schemas, and then you work upwards to the entity classes. The wsreversemapping tool would help with this approach.

Meet in the middle mapping

Probably the most common development model. You have a combination of the data model and the object model partially complete. Depending on the goals and requirements, you must negotiate the relationships to resolve any differences. Both the wsmapping tool and the wsreversemapping tool would help with this approach.

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 customizedpersistence.xml file editor, a database explorer, and other features. Another alternative is the Eclipse Dali project. More information about Rational Application Developer or the Eclipse Dali plug-in can be found at their respective websites.
Compile the entity classes.
Compile the entities as you would any Java class, unless you are using the Criteria API. For the Criteria API, you must also generate the Criteria API metamodel classes by including the following option with the javac command:
-Aopenjpa.metamodel=true

The following are examples of how you use this option.
(zos)
app_server_root/java/bin/javac
-Aopenjpa.metamodel=true
-classpath app_server_root/runtimes/com.ibm.ws.jpa.thinclient_8.0.0.jar
mypackage/MyEntity.java
app_server_root\java\bin\javac
-Aopenjpa.metamodel=true
-classpath app_server_root\runtimes\com.ibm.ws.jpa.thinclient_8.0.0.jar
 mypackage\MyEntity.java
For more information about using Criteria API and AnnotationProcessor6, refer to the Apache OpenJPA User Guide, Chapter 11: JPA Criteria and Chapter 4: Generation of Canonical Metamodel classes for AnnotationProcessor6 options and the information center topic, Criteria API.
Enhance the entity classes using the JPA enhancer tool, or specify the Java agent to perform dynamic enhancement at run time.

Use the wsenhancer tool. The enhancer post-processes the bytecode that is generated by the Java compiler and adds the fields and methods necessary to implement the persistence features. For example examples on how to use the wsenhancer tool, see the topic, wsenhancer command.

We can specify the Java agent mechanism to perform the dynamic enhancement at run time. For example, type the following at the command prompt:
java -javaagent:${ app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_8.0.0.jar com.xyz.Main

We can either run the wsenhancer tool or specify the javaagent command. You do not need to do both.

Optional: If we are not using the development model for bottom-up mapping, generate or update your database tables automatically or using the 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 openjpa.jdbc.SynchronizeMappings property. This property 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:
<property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>

Avoid trouble: To enable automatic object-relational mapping at run time, all of the persistent classes must be listed in the Java .class file, mapping file, and JAR file elements in XML format.gotcha

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. For examples on how to run the wsmapping tool, see the topic, wsmapping command.

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 the 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. See the Merge utility documentation in the IBM Integrated Data Management information center.
Avoid trouble: Applications that utilize 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, complete the following:

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 web site for the appropriate release.

Install the required level of IBM Optim PureQuery Run time, which is Version 1.3.100 or later. For more information, see the IBM Data Studio pureQuery Runtime website. Install the latest JCC drivers, 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.
gotcha
For examples on how to run this command, see the topic, wsdbgen command.

Optional: For application-managed identity, generate an application-managed identity class with the wsappid tool. When you 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.
For examples on how to use the wsappid tool, see the topic wsappid command.
Example

The following is a sample persistence.xml file for the Java SE Environment:
<?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.0"               xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
                 http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
         <persistence-unit name="TheWildZooPU" transaction-type="RESOURCE_LOCAL">
             <!-- 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="openjpa.ConnectionDriverName"                        value="org.apache.derby.jdbc.EmbeddedDriver" />
            <property name="openjpa.ConnectionURL"
                      value="jdbc:derby:target/database/jpa-test-database;create=true" />
            <property name="openjpa.Log"
                      value="DefaultLevel=INFO,SQL=TRACE,File=./dist/jpaEnhancerLog.log,Runtime=INFO,Tool=INFO" />
            <property name="openjpa.ConnectionFactoryProperties"                        value="PrettyPrint=true, PrettyPrintLineLength=72" />
            <property name="openjpa.jdbc.SynchronizeMappings"                        value="buildSchema(ForeignKeys=true)" />
            <property name="openjpa.ConnectionUserName"                        value="user" />
            <property name="openjpa.ConnectionPassword"                        value="password"/>
        </properties>
      </persistence-unit>
      </persistence>
What to do next
For more information about any of the commands, classes or other OpenJPA information, refer to the Apache OpenJPA User Guide.

Related concepts

Development and assembly tools

Related tasks

Task overview: Storing and retrieving persistent data with the JPA API
Associate persistence providers and data sources
Task overview: IBM Optim pureQuery Runtime
Configure JDBC providers to use pureQuery to access DB2
Configure pureQuery to use multiple DB2 package collections
Configure JPA to work in the environment
Configure JDBC providers to use pureQuery to access Informix
Troubleshooting JPA applications

wsappid command
wsenhancer command
wsjpaversion command
wsmapping command
wsreversemapping command
wsschema command
Criteria API

Related information:

Merge utility
Apache OpenJPA User Guide: JPA
Apache OpenJPA User Guide: JPA Criteria
Dali Java Persistence Tools