Prepare and package 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.
For this task, you need to specify the com.ibm.ws.jpa.thinclient_7.0.0.jar
standalone Java archive (JAR) file in your
class path. This standalone JAR file is available from the client
and server install images. The location of this file on the client
install image is ${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar.
The location of this file on the server install image is ${app_server_root}/runtimes/com.ibm.ws.jpa.thinclient_7.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.
- 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 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.
- Configure the properties of the persistence unit in the persistence.xml file
that will be used in the JPA application.
- Specify your data source. Use the openjpa.Connection
property to obtain a connection to the database. When you run a JPA
application in a Java SE environment, a JTA data
source is treated as a data source that is not JTA compliant.
- Select com.ibm.websphere.persistence.PersistenceProviderImpl
as the persistence provider.
Avoid trouble: Include
the persistence provider in the classpath if you run the JPA application
as a standalone application.
gotcha
- Specify your database configuration options. If
you are using IBM Optim pureQuery Runtime, configure your data source
to use IBM Optim pureQuery Runtime, ensure the pdq.jar and pdqmgmt.jar files
are included on the JDBC provider classpath. For more information,
see the documentation about configuring a data source to use IBM Optim
pureQuery Runtime. Indicate the database type and method
of connection in the persistence.xml file.
<property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver" />
<property name="openjpa.ConnectionURL" value="jdbc:derby:target/database/jpa-test-database;create=true"/>
- Specify the transaction type to RESOURCE_LOCAL.
For example, the following entry should be in the persistence.xml file:
<persistence-unit name="persistence_unit" transaction-type="RESOURCE_LOCAL">
- Include the location of the object relationship mapping
file, orm.xml, and any additional mapping files. For
example, the following entry should be in the persistence.xml file:
<mapping-file>META-INF/JPAorm.xml</mapping-file>
- Add any vendor specific properties to the persistence
unit.
- Package the application.
Note: Package
the persistence units in separate JAR files to make them more accessible
and reusable. If you package the persistence units this way, they
can be tested outside the container both with and without the occurrence
of database persistence. The persistence units can be included in
standalone applications or they can be packaged into EAR files as
persistence archive files. If you package the persistence unit into
a persistence archive file, all of the application components must
be able to access the persistence archive. The application that uses
the persistence units must declare a dependency on the persistence
archive using the MANIFEST.MF Class-Path: declaration.
Note: If you are using IBM Optim pureQuery
Runtime, add the persistence_unit_name.pdqxml files
created previous or the or persistence_unit_name.pdqxml files
created in the above Step 4 to the JPA application JAR file. The files
are located in same META-INF directory where your persistence.xml file
is located.
To package the application use the
following command:jar -cvf ${jar_Name} ${entity_Path}
where
${jar_Name} represents the name of the JAR file
to create, and ${entityPath} represents the root
location where the entities reside, which is where you compiled them.
- When you run your standalone application, specify the JAR
files in your classpath when executing your application.
The JAR file to execute is the stand-alone JAR file, com.ibm.ws.jpa.thinclient_7.0.0.jar.
For example, use the following Java call
to run the com.xyz.Main standalone application:
java -classpath ${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar other_jar_file.jar com.xyz.Main
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.