Prepare persistence applications to test outside of the
application server container in a Java™ SE
environment.
About this task
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 that are
associated with applications that implement CMP or BMP. In JPA applications,
you must 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. You 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.
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 you have the latest version of the commands for your
release level.
For
this task, you need to specify the com.ibm.ws.jpa.thinclient_JPA2FEP1.0.0.jar
standalone Java archive (JAR) file in your
class path. This standalone JAR file is available from the install
images. The location of this file on the server install image is
${app_server_root}/feature_packs/jpa/runtimes/com.ibm.ws.jpa.thinclient_JPA2FEP1.0.0.jar.
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 would help 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 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 will
need to 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 customized persistence.xml file
editor, a database explorer, and other features. Another alternative
is the Eclipse Dali project. More information on Rational Application Developer or the Eclipse
Dali plugin can be found at their respective web sites.
- 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 need to also generate the Criteria
API metamodel classes by including the following option with the javac
command:
-Aopenjpa.metamodel=true
Examples
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
mypackage/MyEntity.java
For Windows® platform:
app_server_root\java\bin\javac
-Aopenjpa.metamodel=true
mypackage\MyEntity.java
For more information about using Criteria
API and AnnotationProcessor6, refer to the Apache OpenJPA User's
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,
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 will 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: Enhance the entity classes using
the JPA enhancer tool, or specify the Java agent
to perform dynamic enhancement at run time.
- 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.
- 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, pureQuery runtime 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 information center.
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:
- 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 Web site.
- If you use DB2
Universal Database™ for iSeries V6R1
or V5R3, visit the fix web site for the appropriate release.
- Install the required level of PureQuery, which is Version 1.3.100
or later. For more information, see the IBM Data
Studio pureQuery Runtime Web site. 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: 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 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="1.0"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_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 on any of the commands, classes or other
OpenJPA information discussed here, refer to the Apache OpenJPA User's
Guide.