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 you
with developing applications in a Java EE
environment.
About this task
Attention: 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 you 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 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..
Important: 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 that are associated with applications that implement
CMP or BMP. In JPA applications, you must 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 your applications.
Procedure
- 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 you 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 your database model. If you 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.
- Compile the entity classes.
Compile the entities
as you would any Java class,
unless you are using the Criteria API. If you 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 you 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 topic about criteria API.
- 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 you have
written them. The enhancer post-processes the bytecode that is generated
by the Java compiler and adds
the fields and methods that are 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 you can enhance your entities when you 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.
- Optional: If you are not using
the development model for bottom-up mapping, generate or update your
database tables automatically or by using the wsmapping tool.
- By default, the object-relational mapping does not occur automatically, but you 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 your persistent classes must be listed in the Java
.class file, mapping file, and Java archive (JAR) file
elements in XML format.
- To manually update or generate your 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 you are using DB2® and want to use static Structured
Query Language (SQL), run the wsdbgen command.
In order 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 you 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 documentation.
Avoid trouble: 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 you can use to prepare the application, or when the
application is running and calls a JPA method. To resolve this problem, complete the following steps:
- Install the program temporary fixes (PTF) for the iSeries JDBC Driver V5R4. Install PTF numbers SI32561 and SI32562. You can find the PTFs
through the IBM
System i® Support: PTF Cover Letters website.
- If you 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. For more
information, see the 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.
For examples on how to run this command, see the topic, wsdbgen
command.
- Optional: If you are using 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 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="https://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>
What to do next
For more information about the commands, classes or other
OpenJPA information, refer to the Apache OpenJPA User Guide.