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
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 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.
- 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: 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.
- Configure these properties.
- Specify the configuration options for your database.
The application server manages access to data sources. You can
configure the data sources, connection pooling, and JTA transaction
service in the administrative console. If you have a specific data
source for your application, configure the data source before you
install your JPA application.
- Configure your data sources through the administrative console.
See the topic on configuring the JDBC provider and data source for
more information.
- Specify the Java Naming
and Directory Interface (JNDI) names for the <jta-data-source>
and <non-jta-data-source> elements. If you use the component
name space method for data source retrieval, ensure that your application
defines these resource references so that you can use these JNDI names
to access the data source. This configuration provides more flexibility
if you need to alter the configuration for the data source. For more
information on using the JNDI interface, refer to the topic, Developing
applications that use JNDI. For example, the persistence.xml file
would have a entry like the following:
<jta-data-source>java:comp/env/jdbc/FooBarDataSourceJNDI</jta-data-source>
- If you are using pureQuery, configure your data source
to use pureQuery. Ensure the pdq.jar and pdqmgmt.jar files
are included on the JDBC provider class path. The JPA provider implementation
must be the IBM implementation
of JPA provider of com.ibm.websphere.persistence.PersistenceProviderImpl.
The OpenJPA persistence provider does not provide support for pureQuery.
For more information, refer to the topic, Configuring a data source
to use pureQuery.
- Package the application. There are several packaging
options for an application that uses JPA in a Java EE environment. Choose the packaging option
that best suits the JPA usage and configuration within the modules
of your application. These are some of the most common packaging options.
For a definitive list of packaging options, see the Java Persistence API specification.
Note: If
you are using pureQuery, 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.
- For a standalone Enterprise JavaBeans™ (EJB)
module or a standalone application client module, package the EJB
and application client modules in a standard Java archive (JAR) file. Ensure that you package
the application with these conditions:
- The JAR file must contain your EJB class files or the Java class files for the application client.
- The META-INF directory of the archive must include your persistence.xml file.
- If your application uses mapping files, orm.xml, or a custom mapping
file, the JAR file must also contain those files. If the location
of the orm.xml file is not specified in the persistence unit,
the default location is the META-INF directory of the JAR file.
- For a standalone Web module, package the application in a
standard Web Application archive (WAR) file. Ensure that you package
the application with these conditions:
- For enterprise application that contains one or more modules,
package the application in a standard Enterprise application archive
(EAR) file. An enterprise application can contain one ore more EJB
module, Web module, or application client module. Ensure that you
package the application with these conditions:
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="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="JTA">
<jta-data-source>jdbc/FooBarDataSourceJNDI</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's Guide.