Developing JPA and packaging applications for a Java EE environment

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

  1. 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.
  2. 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.

  3. 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.
    • By default, the object-relational mapping does not occur automatically, but you can configure the application server to provide that mapping with the openjpa.jdbc.SynchronizeMappings property. This property 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:
      <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
      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 wsmapping tool, see the topic, wsmapping command.
  4. Optional: If you are using DB2® and want to use static Structured Query Language (SQL), run the wsdb2gen command. In order to use the wsdb2gen tool, pureQuery runtime must be installed. The wsdb2gen tool creates 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 wsdb2gen command must be run for each persistence unit.
    Avoid trouble: Applications that implement the JPA and are configured to run static SQL can experience various exceptions. These exceptions might occur with the wsdb2gen 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:
    1. 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.
    2. If you use DB2 Universal Database™ for iSeries V6R1 or V5R3, visit the fix web site for the appropriate release.
    3. 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.
    4. 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, wsdb2gen command.

  5. Configure these properties.
    1. 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.
      1. Configure your data sources through the administrative console. See the topic on configuring the JDBC provider and data source for more information.
      2. 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>
    2. 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.
  6. 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:
      • The WAR file must contain your Web application class files. The Web application class files must be included in the WEB-INF/classes directory or in a JAR file that is located in the WEB-INF/lib directory of the WAR file.
      • The persistence.xml file must be included in the WEB-INF/classes/META-INF directory or in the META-INF directory of a JAR file that is included in your WEB-INF/lib directory of your WAR file.
      • If your application uses mapping files, orm.xml, or a custom mapping file, the WAR file must also contain those files. Mapping files can reside in the WEB-INF/classes directory or in a JAR file that is contained within the WEB-INF/lib directory of the WAR file. Use the <mapping-file> element of the persistence.xml file to specify the location of mapping files. For example:
        <mapping-file>META-INF/JPAorm.xml</mapping-file>
    • 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:
      • If multiple modules use the same persistence unit, you can create a persistence archive and package the persistence archive within the EAR file.
      • Include your entity classes, any necessary supporting classes, the persistence.xml file, and additional mapping files in the persistence archive file. Follow the packaging rules for EJB and application client modules for the location of your persistence.xml file and mapping files.
      • Each module that uses the persistence archive must have a class path entry in its META-INF/MANIFEST.MF file. Here is an example manifest file:
        Manifest-Version: 1.0 
        Class-Path: MyJPAEntities.jar
      • If your modules use separate persistence units and share entity classes, you can package the entity classes in a persistence archive and specify different persistence.xml file and mapping files for each module. If the modules do not share entity classes or a persistence configuration, package each module as a standalone EJB module, a standalone application client module, or a standalone Web archive and then package them in the EAR file.

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.



In this information ...


Related reference

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Oct 22, 2010 12:21:29 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-zos&topic=tejb_jpadevee
File name: tejb_jpadevee.html