Developing and packaging JPA 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 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. 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.
  2. 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:
    [AIX] [HP-UX] [Linux] [Solaris] [z/OS]
    ${app_server_root}/bin/wsenhancer.sh [parameters][arguments]
    [iSeries]
    ${app_server_root}/bin/wsenhancer [parameters][arguments]
    [Windows]
    ${app_server_root}\bin\wsenhancer.bat [parameters][arguments]
    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.
  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 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 example:
      [AIX] [HP-UX] [Linux] [Solaris] [z/OS]
      ${app_client_root}/bin/wsmapping.sh [parameters][arguments]
      [iSeries]
      ${app_client_root}/bin/wsmapping [parameters][arguments]
      [Windows]
      ${app_client_root}\bin\wsmapping.bat [parameters][arguments]
    Refer to the section on runtime forward mapping in the Apache OpenJPA User's Guide for more information.
  4. 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 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>
  5. 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:
      • 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.
      • Your 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 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). 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 your EAR file.
      • Include your entity classes, any necessary supporting classes, your 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 and mapping files.
      • Each module that uses the persistence archive must have a class path entry in its META-INF/MANIFESTMF 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

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>



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 Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 2:56:59 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=tejb_jpadevee
File name: tejb_jpadevee.html