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-2.1.thinclient_9.0.jar
stand-alone Java archive (JAR) file in your 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 the ${app_server_root}/runtimes
directory.
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.
- 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 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 you use OpenJPA as your persistence provider.
- 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 when you use OpenJPA as your persistence provider.
- 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 when you use OpenJPA as your 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. 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.
The following are examples of how you use this option.
Using EclipseLink, provide the following arguments with the
javac command:
-processor
org.eclipse.persistence.internal.jpa.modelgen.CanonicalModelProcessor
-Aeclipselink.persistencexml= persistence.xml_location
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
Using OpenJPA or WSJPA, provide the following arguments with the
javac
command:
-Aopenjpa.metamodel=true
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 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 the application server’s persistence provider 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 eclenhancer tool, see the eclenhancer command
topic. For examples of how to use the wsenhancer tool, see the wsenhancer command
topic.
- Optional: If you are not using the development model for bottom-up mapping, generate or
update your database tables automatically or by using the eclenhancer or
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 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"/>
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.
gotcha
- 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 eclenhancer tool, see the eclenhancer command topic. For examples of
how to use the wsmapping tool, see the wsmapping command topic.
- 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 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 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.
gotcha
For examples on how to run this command, see the topic, wsdbgen
command.
- Optional: If you are using OpenJPA and 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="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>