WAS v8.5 > Develop applications > Develop EJB applications > Develop applications that use the Java Persistence API

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 EE environment. The application server also provides JPA command tools to assist you with developing applications in a Java EE environment. When we use these JPA command tools, run them from the <profile_root>/bin directory, rather than from the app_server_root/bin directory to verify we have the latest version of the commands for the 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 your 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..

JPA applications require different configuration techniques from applications that use container-managed persistence or bean-managed persistence (BMP). They do not follow the typical deployment techniques associated with applications that implement CMP or BMP. In JPA applications, you must define a persistence unit and configure the appropriate properties to ensure 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.

1. Generate your entities classes. These are Plain Old Java Object (POJO) entities. Depending upon your 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 your object model and then writing your entity classes. These entity classes would eventually drive the creation of the 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 OpenJPA functionality to generate the database tables that are based on the entity classes. The wsmapping tool helps with this approach.

   • Bottom-up mapping: You start with your data model, which are the database schemas, and then you work upwards to your entity classes. The wsreversemapping tool helps 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 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 customized persistence.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.

2. Compile the entity classes.

   Compile the entities as you would any Java class, unless you are using the Criteria API. If we are using 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 we use this option.

   For Linux, UNIX and z/OS platforms:

   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 Windows platform:

   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

   Using the javac command and the J2EE server plug-in:

   For Linux, UNIX and z/OS platforms:

   app_server_root/java/bin/javac
   -Aopenjpa.metamodel=true
   -classpath app_server_root/plugins/javax.j2ee.persistence.jar 
   mypackage/MyEntity.java

   For Windows platform:

   app_server_root\java\bin\javac
   -Aopenjpa.metamodel=true
   -classpath app_server_root\plugins\javax.j2ee.persistence.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.
3. Enhance the entity classes using the JPA enhancer tool, wsenhancer, for the application server. An enhancer is a tool that automatically adds code 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 JPA for the application server and OpenJPA can automatically enhance the entities at run time, you obtain better performance if we can enhance your entities when we build the application. The application does not attempt to enhance entities that are already enhanced.

   For examples of how to use the wsenhancer tool, see the topic, wsenhancer command.

4. Optional: If you are not using the development model for bottom-up mapping, generate or update the 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 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)"/>

     To enable automatic object-relational mapping at run time, all of your 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. For examples on how to run the wsmapping tool, see the topic, wsmapping command.

5. Optional: If we are using DB2 and want to use static 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. Refer to the Merge utility documentation in the IBM Integrated Data Management information center.

   For examples on how to run this command, see the topic, wsdbgen command.

6. Optional: If we are using 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.

   For examples on how to use the wsappid tool, see the topic wsappid command.

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.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="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="openjpa.ConnectionFactoryProperties"
                     value="PrettyPrint=true, PrettyPrintLineLength=72"/>            <property name="openjpa.jdbc.SynchronizeMappings"
                     value="buildSchema(ForeignKeys=true)"/>         </properties> 
     </persistence-unit> </persistence>

For more information about the commands, classes or other OpenJPA information, refer to the Apache OpenJPA User Guide.

Subtopics

• wsappid command
  The JPA specification supports an entity primary key to be made up of more than one column. In this case, the primary key is called a composite or compound primary key. Provide an ID class, which is specified by the @IdClass annotation, to manage a composite primary key. Use the identity tool for JPA to generate an ID class for entities that use composite primary keys.
• wsenhancer command
  The entity enhancer tool for JPA applications inserts bytecode into an entity class file that supports the JPA provider to manage the state of an entity.
• wsmapping command
  The wsmapping tool is used to provide top-down mapping of the entity object model to the database relational model. We can use the wsmapping tool to create database tables.
• wsreversemapping command
  The wsreversemapping tool generates persistent class definitions and metadata from a database schema.
• wsschema command
  The schema tool can be used to view the database schema in XML form or match an XML schema to an existing database.
• wsdbgen command
  The command supports utilization of the pureQuery feature in JPA applications.
• ANT task WsJpaDBGenTask
  The ANT task WsJpaDBGenTask provides an alternative to the wsdbgen command.

Related concepts:

Development and assembly tools

Related

Map persistent properties to XML columns for JPA
Associate persistence providers and data sources
Configure a JDBC provider and data source
Troubleshooting JPA applications
Tasks: IBM Optim pureQuery Runtime
Configure pureQuery to use multiple DB2 package collections
Configure JDBC providers to use pureQuery to access DB2

Reference:

wsjpaversion command
Criteria API

Related information:

Merge utility

Apache OpenJPA User Guide

Apache OpenJPA User Guide: JPA Criteria

Dynamic, typesafe queries in JPA 2.0
IBM System i: PTF Cover Letters
IBM Support: Fix Central for DB2 UDB for iSeries V6R1
IBM Support: Fix Central for DB2 UDB for iSeries V5rR3

Dali Java Persistence Tools

+

Search Tips   |   Advanced Search