+

Search Tips   |   Advanced Search

Develop and packaging JPA applications for a Java EE environment


Containers in the appserver can provide many of the necessary functions for the Java Persistence API (JPA) in a Java Enterprise Edition (Java EE) environment. The appserver also provides JPA tools to assist you with developing applications in a Java EE environment.

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, define a persistence unit and configure the appropriate properties to verify 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 the applications.

 

  1. Generate the entities classes. Depending upon the development model, we 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 we use this approach, we are most likely concerned with creating the architecture of the object model and then writing the entity classes. These entity classes would eventually drive the creation of the database model. For 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 the data model, which are the database schemas, and then you work upwards to the entity classes. The wsreversemapping tool would help with this approach.

    • Meet in the middle mapping: probably the most common development model. we 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 appserver 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 appserver. An enhancer is a tool that automatically adds code to the persistent classes after we 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] 

    ${APP_ROOT}/bin/wsenhancer.sh [parameters][arguments]

    (Windows) 

    ${APP_ROOT}\bin\wsenhancer.bat [parameters][arguments]

    Although JPA for the appserver and OpenJPA can automatically enhance the entities at run time, you will obtain better performance if we can enhance the entities when you build the application. The application will not attempt to enhance entities that are already enhanced.

  3. If not using the development model for bottom-up mapping, generate or update the database tables automatically or by using the wsmapping tool.

    • By default, the object-relational mapping does not occur automatically, but we can configure the appserver 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 the persistent classes must be listed in the Java .class file, mapping file, and JAR file elements in XML format.

    • To manually update or generate the database tables, run the JPA mapping tool for the appserver from the command line to create the tables in the database. For example: [AIX] [HP-UX] [Linux] [Solaris] 

      ${APP_ROOT}/bin/wsmapping.sh [parameters][arguments]

      (Windows) 

      ${app_client_root}\bin\wsmapping.bat [parameters][arguments]

  4. If using DB2 and want to use static 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 the persistence.xml file is located. If we have multiple persistence units, wsdb2gen command must be run for each persistence unit. To use the wsdb2gen tool, type the following at a command prompt: [AIX] [HP-UX] [Linux] [Solaris] 

    ${APP_ROOT}/bin/wsdb2gen.sh [parameters]

    (Windows) 

    ${APP_ROOT}\bin\wsdb2gen.bat [parameters]

  5. Set these properties.

    1. Specify the configuration options for the database. The appserver manages access to data sources. Configure the data sources, connection pooling, and JTA transaction service in the admin console. If we have a specific data source for the application, configure the data source before you install the JPA application.

      1. Set the data sources through the admin console. See the topic on configuring the JDBC provider and data source for more information.

      2. Specify the JNDI names for the <jta-data-source> and <non-jta-data-source> elements. If we use the component name space method for data source retrieval, ensure that the application defines these resource references so that we can use these JNDI names to access the data source. This configuration provides more flexibility to alter the configuration for the data source.

        See 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>

    2. If using pureQuery, configure the 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 the application. These are some of the most common packaging options. For a definitive list of packaging options, see the Java Persistence API specification.

    If 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 the persistence.xml file is located.

    • For a standalone EJB module or a standalone application client module, package the EJB and application client modules in a standard JAR file. Ensure that you package the application with these conditions:

      • The JAR file must contain the EJB class files or the Java class files for the application client.

      • The META-INF directory of the archive must include the persistence.xml file.

      • If the 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 the 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...

        WEB-INF/lib

        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 the WEB-INF/lib directory of the WAR file.

      • If the 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 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). 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, we can create a persistence archive and package the persistence archive within the EAR file.

      • Include the 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 the 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 the modules use separate persistence units and share entity classes, we 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: 

<?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>

 

Next steps

See on any of the commands, classes or other OpenJPA information discussed here, refer to the Apache OpenJPA User's Guide.


wsappid
wsenhancer
wsmapping
wsreversemapping
wsschema
wsdb2gen
ANT Task WsJpaDB2GenTask

 

Related tasks


Mapping persistent properties to XML columns
Associating persistence units and data sources
Set a JDBC provider and data source
Develop applications that use JNDI
Task overview: Data Studio pureQuery
Set to use pureQuery in a Java EE environment
Set pureQuery to use multiple package collections
Task overview: Storing and retrieving persistent data with the Java Persistence API (JPA)

 

Related


wsjpaversion

 

Related information


IBM System i: PTF Cover Letters
IBM Support: Fix Central for DB2 UDB for iSeries V6R1
IBM Support: Fix Central for DB2 UDB for iSeries V5rR3