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 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. 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 the Eclipse
Dali plugin provides a solid development environment for either Java EE or
Jave SE applications. The Eclipse Dali project provides a plugin that includes
GUI tools to insert annotations, a customized persistence.xml file editor,
a database explorer, and other features. More information on the Dali plugin
can be found at the Eclipse Dali web site.
- Enhance the entity classes using the JPA enhancer tool for the
application server (wsenhancer). 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.
To use the wsenhancer tool, type the following at a command prompt:
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
will not attempt to enhance entities that are already enhanced. For more details,
see the topic on the wsenhancer tool or the section on persistent classes
in the Apache OpenJPA User's Guide.
- 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.
Refer to the section on runtime forward mapping in the Apache OpenJPA
User's Guide for more information.
- 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 on 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>
- 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.
- For a standalone EJB module or a standalone application client module,
package the EJB and application client modules in a standard Java archive
(JAR). 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.
- If your application uses mapping files, orm.xml or a custom mapping file,
the JAR file must contain those files as well. 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). 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). 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
This is a sample persistence.xml file for the Java EE 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="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>
<exclude-unlisted-classes>true</exclude-unlisted-classes>
<properties>
<property name="openjpa.ConnectionFactoryProperties" value="PrettyPrint=true, PrettyPrintLineLength=72"/>
<property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
</properties>
</persistence-unit>
</persistence>